.NET MAUI 應用程式的項目組態

.NET MAUI 使用單一 項目系統 來管理跨平臺應用程式的組態。 .NET MAUI 中的專案組態類似於 Visual Studio 中的其他專案，以滑鼠右鍵按兩下 方案總管 中的項目，然後選取 [屬性]。

應用程式

[應用程式] 區段描述一些與您的應用程式目標平臺，以及輸出檔案和預設命名空間相關的設定。

• 一般

  描述您的應用程式的一些基本設定。

  設定	預設值	說明
  組件名稱	$(MSBuildProjectName)	指定將保留組件資訊清單之輸出檔的名稱。
  預設命名空間	變動。	指定新增至專案之檔案的基底命名空間。 這通常預設為項目的名稱，或您在建立專案時所指定的值。

• iOS 目標

  如果您要以 iOS 和 macOS 為目標（使用 Mac Catalyst），這些設定會描述目標 iOS 版本。

  設定	預設值	說明
  以 iOS 平台為目標	已選取	指定此專案會以 iOS 平台為目標。
  目標 iOS 架構	net8.0-ios	用來以 iOS 為目標的目標 Framework Moniker。
  最低目標 iOS 架構	14.2	應用程式目標的最低 iOS 版本。

• Android 目標

  如果您要以 Android 為目標，這些設定會描述目標 Android 版本。

  設定	預設值	說明
  以Android平台為目標	已選取	核取時，.NET MAUI 專案會以應用程式為目標並建置 Android 版本。 取消核取以停用Android目標。
  目標 Android Framework	net8.0-android	用來以 Android 為目標的目標 Framework Moniker。
  最低目標 Android Framework	21.0	應用程式目標的最低 Android 版本。

• Windows 目標

  如果您要以 Windows 為目標，這些設定會描述目標 Windows 版本。

  設定	預設值	說明
  以 Windows 平台為目標	已選取	核取時，.NET MAUI 專案會以應用程式為目標並建置 Windows 版本。 取消核取以停用 Windows 目標。
  目標 Windows Framework	net8.0-windows10.0.19041.0	用來以 Windows 為目標的目標 Framework Moniker。
  最低目標 Windows Framework	10.0.17763.0	您的應用程式目標的最低 Windows 版本。

組建

[建置] 區段描述編譯應用程式的相關設定。

一般

與目標平臺相關的 設定。

• 條件式編譯的符號

  指定執行條件式編譯的符號。 以分號 ;分隔符號。 符號可以分成目標平臺。 如需詳細資訊，請參閱 條件式編譯。

• 平台目標

  指定輸出檔設為目標的處理器。 選擇 Any CPU 指定可接受任何處理器，讓應用程式可在最廣泛的硬體上執行。

  這通常設定為 ， Any CPU 而運行時間標識元設定是用來以CPU平台為目標。

  選項	描述
  Any CPU	（預設值）編譯您的元件以在任何平台上執行。 您的應用程式會盡可能做為 64 位元處理序執行，而且只有在 32 位元模式可用時才會回到該模式。
  x86	編譯您的元件，以由32位、x86 相容的運行時間執行。
  x64	編譯您的元件，以在支援 AMD64 或 EM64T 指令集的電腦上由 64 位運行時間執行。
  ARM32	編譯您的元件，以在具有進階 RISC 計算機 （ARM） 處理器的電腦上執行。
  ARM64	編譯您的元件，以在具有支援 A64 指令集之進階 RISC 計算機 （ARM） 處理器的電腦上，由 64 位運行時間執行。

• 可為 Null

  指定全專案 C# 可為 Null 的內容。 如需詳細資訊，請參閱 可為 Null 的參考。

  選項	描述
  取消設定	（預設值）如果未設定這個設定，預設值為 Disable。
  Disable	停用可為 Null 的警告。 所有參考類型變數都是可為 Null 的參考型別。
  Enable	編譯程式會啟用所有 Null 參考分析和所有語言功能。
  Warnings	編譯程式會執行所有 Null 分析，並在程式代碼可能取值 Null 時發出警告。
  Annotations	當程式代碼可能取值 Null 時，編譯程式不會執行 Null 分析或發出警告。

• 隱含全域使用

  啟用專案 SDK 所宣告的隱含全域使用。 默認會啟用此功能，並將許多 .NET MAUI 命名空間自動匯入至所有程式碼檔案。 程式代碼檔案不需要新增 using 一般 .NET MAUI 命名空間的語句。 如需詳細資訊，請參閱 MSBuild 屬性 - ImplicitUsings。

• 不安全的程式碼

  允許使用 unsafe 關鍵詞編譯的程序代碼。 此選項預設為停用狀態。

• 最佳化程式碼

  啟用編譯程式優化，以縮小、更快且更有效率的輸出。 在 [偵錯] 或 [發行] 模式中，每個目標平臺都有一個選項。 一般而言，這會針對發行模式啟用，因為程式代碼會以犧牲有用的偵錯資訊來優化速度。

• 偵錯符號

  指定建置期間產生的偵錯符號種類。

錯誤和警告

設定 與編譯期間如何處理和報告錯誤和警告有關。

• 警告層級

  指定顯示編譯器警告的層級。

• 隱藏特定警告

  封鎖編譯程式產生指定的警告。 以逗號 , 或分號 ;分隔多個警告編號。

• 將警告視為錯誤

  啟用時，會指示編譯程式將警告視為錯誤。 此選項預設為停用狀態。

• 將特定警告視為錯誤

  指定哪些警告會視為錯誤。 以逗號 , 或分號 ;分隔多個警告編號。

輸出

與產生輸出檔案相關的 設定。

• 基底輸出路徑

  指定建置期間項目輸出的基底位置。 子資料夾將會附加至此路徑，以區分項目組態。

  預設為 .\bin\。

• 基底中繼輸出路徑

  指定建置期間專案中繼輸出的基底位置。 子資料夾將會附加至路徑，以區分項目組態。

  預設為 .\obj\。

• 參考元件

  啟用時，會產生包含專案公用 API 的參考元件。 此選項預設為停用狀態。

• 檔檔案

  啟用時，會產生包含 API 檔案的檔案。 此選項預設為停用狀態。

事件

在本節中，您可以新增在建置期間執行的命令。

• 建置前事件

  指定在建置開始之前執行的命令。 如果專案為最新狀態，則不會執行。 非零結束代碼在執行之前，組建將會失敗。

• 建置後事件

  指定在建置開始之前執行的命令。 如果專案為最新狀態，則不會執行。 非零結束代碼在執行之前，組建將會失敗。

• 何時執行建置後事件

  指定後續建置後執行的條件。

強式命名

與簽署元件相關的 設定。

• 簽署元件

  啟用時，簽署輸出元件以為其命名強名稱。

進階

與組建相關的其他設定。

• Language version (語言版本)

  專案中程式代碼可用的語言版本。 預設為 10.0。

• 檢查算術溢位

  當整數算術產生超出範圍值時擲回例外狀況。 此設定適用於每個平臺。 預設會針對每個平臺停用。

• 具決定性

  針對相同的輸入產生相同的編譯輸出。 此設定適用於每個平臺。 預設會針對每個平台啟用。

• 內部編譯程式錯誤報告

  將內部編譯程式錯誤報告傳送給 Microsoft。 預設為 Prompt before sending。

• 檔案對齊方式

  以位元組為單位，指定要對齊輸出檔案區段的位置。 此設定適用於每個平臺。 預設為 512 每個平臺。

套件

[套件] 區段描述產生 NuGet 套件的相關設定。

一般

與產生 NuGet 套件相關的 設定。

• 在組建時產生 NuGet 套件

  啟用時，在建置作業期間產生 NuGet 套件檔案。 此選項預設為停用狀態。

• 封裝識別碼

  不區分大小寫的套件標識碼，在 NuGet 套件庫中必須是唯一的，例如 nuget.org。標識元不能包含對 URL 無效的空格或字元，而且通常會遵循 .NET 命名空間規則。

  預設為的 $(AssemblyName)MSBuild 值。

• 標題

  套件的易記標題，通常會用於 UI 顯示，以及 nuget.org 和 Visual Studio 套件管理員中。

• 套件版本

  遵循模式的套件 major.minor.patch 版本。 版本號碼可能包含發行前版本後綴。

  預設為的 $(ApplicationDisplayVersion)MSBuild 值。

• 作者

  以逗號分隔的作者清單，符合 nuget.org 上的配置檔名稱。這些會顯示在 nuget.org 上的 NuGet 資源庫中，並用來由相同的作者交叉參考套件。

  預設為的 $(AssemblyName)MSBuild 值。

• 公司

  與 NuGet 套件相關聯的公司名稱。

  預設為的 $(Authors)MSBuild 值。

• 產品

  與 NuGet 套件相關聯的產品名稱。

  預設為的 $(AssemblyName)MSBuild 值。

• 說明

  UI 顯示套件的描述。

• 著作權

  套件的著作權詳細資料。

• 專案 URL

  套件首頁的 URL，通常會顯示在 UI 顯示及 nuget.org 中。

• 圖示

  封裝的圖示影像。 圖像檔案大小限制為 1 MB。 支援的檔案格式包括 JPEG 和 PNG。 建議使用 128x128 的影像解析度。

• 讀我檔案

  封裝的自述檔。 必須是 Markdown （.md） 檔案。

• 存放庫 URL

  指定存放庫的 URL，此存放庫是套件原始程式碼的所在位置及 (或) 正在建置的來源位置。 若要連結至項目頁面，請改用 [專案 URL] 字段。

• 存放庫類型

  指定存放庫的類型。 預設值為 『git』。

• Tags (標籤)

  以分號分隔的標籤和關鍵詞清單，描述套件，並透過搜尋和篩選協助探索套件。

• 版本資訊

  套件版本中所做的變更描述，通常用於UI中，例如Visual Studio 封裝管理員的 [更新] 索引卷標，以取代套件描述。

• 封裝為 .NET 工具

  啟用時，請將專案封裝為特殊的套件，其中包含可透過 「dotnet tool」 命令安裝的控制台應用程式。 此選項預設為停用狀態。

• 封裝輸出路徑

  決定要卸載封裝的輸出路徑。

  預設為的 $(OutputPath)MSBuild 值。

• 元件中性語言

  哪一種語言程式代碼會被視為中性語言。 預設為 unset。

• 元件版本

  元件的版本，如果未設定，預設為 1.0.0.0 。

• 檔案版本

  與檔案相關聯的版本，如果未設定，則預設為 1.0.0.0 。

授權

• 套件授權

  指定專案的套件授權。 預設為 None。

• Symbols

  • 產生符號套件

    啟用時，會在封裝專案時建立其他符號套件。 此選項預設為停用狀態。

程式碼分析

與程式代碼分析相關的 設定。

所有分析器

與分析執行時相關的 設定。

• 在組建上執行

  啟用時，在組建上執行程序代碼分析。 預設值為已啟用。

• 在即時分析上執行

  啟用時，會在您輸入時即時在編輯器中執行程式代碼分析。 預設值為已啟用。

.NET 分析

與 .NET 分析器相關的 設定。

• 在組建上強制執行程式碼樣式 （實驗性）

  啟用時，產生建置程式代碼樣式的相關診斷。 此選項預設為停用狀態。

• 啟用 .NET 分析器

  啟用時，執行 .NET 分析器以協助 API 使用量。 預設值為已啟用。

• 分析層級

  應該在專案中執行的分析器集合。 預設為 Latest。 如需詳細資訊，請參閱 MSBuild：AnalysisLevel。

MAUI 共用

這些是所有目標平台共用之 .NET MAUI 的項目設定。

一般

與 .NET MAUI 相關的一般設定。

• 應用程式標題

  應用程式的顯示名稱。

• 應用程式識別碼

  反向功能變數名稱格式的應用程式識別碼，例如： com.microsoft.maui。

• 應用程式識別碼 （GUID）

  GUID 格式之應用程式的識別碼。

• 應用程式顯示版本

  應用程式的版本。 這應該是一位數整數。 預設為 1。

Android

這些是 Android 特定的 .NET MAUI 設定。

Manifest

與 Android 指令清單相關的 設定。

• 應用程式名稱

  顯示為應用程式名稱的字串。 這是應用程式標題列中顯示的名稱。 如果未設定，則會使用應用程式 MainActivity 的標籤作為應用程式名稱。 默認設定為 @string/app_name，其是指中的Resources/values/Strings.xaml字串資源app_name位置。

• 應用程式套件名稱

  用來唯一識別應用程式的字串。 一般而言，套件名稱是以反向因特網域名慣例為基礎，例如 com.company.appname。

• 應用程式圖示

  指定將針對應用程式顯示的應用程式圖示資源。 此設定@drawable/icon是指位於資料夾中的影像Resources/mipmap檔icon.png。

• 應用程式主題

  設定套用至整個應用程式的UI樣式。 應用程式中的每個檢視都會套用至所選主題中定義的樣式屬性。

• 應用程式版本號碼

  大於零的整數值，定義應用程式的版本號碼。 較高的數位表示較新版本。 此值是由 Android 和其他應用程式以程式設計方式評估，不會向使用者顯示此值。

• 應用程式版本名稱

  字串，指定使用者的應用程式版本。 版本名稱可以是原始字串或字串資源的參考。

• 安裝位置

  指出應儲存應用程式的喜好設定，不論是在內部或外部記憶體中。

  選項	描述
  Internal-only	（預設值）指定應用程式無法安裝或移至外部記憶體。
  Prefer external	指定應用程式應盡可能安裝在外部記憶體中。
  Prefer internal	指定應用程式應盡可能安裝在內部記憶體中。

• 最低 Android 版本

  Android 裝置的最舊 API 層級，可安裝和執行應用程式。 minSdkVersion也稱為 。

• 目標 Android 版本

  應用程式預期執行所在 Android 裝置的目標 API 層級。 此 API 層級會在運行時間使用，不同於在建置階段使用的 Target Framework。 Android 會使用此版本作為提供向前相容性的方式。 targetSdkVersion也稱為 ，這應該符合 Target Framework compileSdkVersion。

選項。

建置Android應用程式之其他選項。

• Android 套件格式

  apk或bundle，分別將Android應用程式封裝為 APK 檔案或 Android 應用程式套件組合。 這可以針對偵錯和發行模式個別設定。

  應用程式套件組合是 Android 版本組建的最新格式，適用於在 Google Play 上提交。

  預設值是 apk。

  選取時 bundle ，會設定其他 MSBuild 屬性：

  • AndroidUseAapt2 設定為 True。
  • AndroidUseApkSigner 設定為 False。
  • AndroidCreatePackagePerAbi 設定為 False。

• 快速部署 （僅限偵錯模式）

  啟用時，將應用程式部署速度比平常快到目標裝置。 此程式可加速建置/部署/偵錯循環，因為只有元件變更時，不會重新安裝套件。 只有更新的元件會重新同步處理至目標裝置。

  此功能預設為啟用。

• 為每個 ABI 產生

  啟用時，會為每個選取的應用程式二進位介面 （ABI） 產生一個 Android 套件 （apk）。 此選項預設為停用狀態。

• 使用累加式封裝

  啟用時，使用累加式 Android 封裝系統 （aapt2）。 此功能預設為啟用。

• 多重索引

  啟用時，允許Android建置系統使用 multidex。 預設為停用。

• 程式代碼壓縮器

  選取要使用的程式代碼壓縮器。

  • ProGuard （預設值） 會被視為舊版程式代碼壓縮器。
  • r8 是新一代工具，可將Java位元組程式代碼轉換成優化的 dex 程式代碼。

• 未壓縮的資源

  將指定的資源延伸模組保留為未壓縮。 以分號 ;分隔延伸模組。 例如： .mp3;.dll;.png 。

• 開發人員檢測

  啟用時，會提供開發人員檢測來進行偵錯和分析。 這可以針對偵錯和發行模式個別設定。

  針對偵錯組建啟用預設值。

• Debugger

  選取要使用的調試程式。 預設值為 .NET (Xamarin)，用於Managed程式碼。 您可以選取 C++ 除錯程式來偵錯應用程式所使用的原生連結庫。

• AOT

  開啟預先編譯 （AOT） 。 這可以針對偵錯和發行模式個別設定。

  發行組建會啟用預設值。

• LLVM

  啟用 LLVM 優化編譯程式。 預設為停用。

• 啟動追蹤

  啟用啟動追蹤。 這可以針對偵錯和發行模式個別設定。

  發行組建會啟用預設值。

• 記憶體回收

  啟用時，請使用並行垃圾收集行程。 預設值為已啟用。

• 啟用修剪

  啟用時，會在發佈期間修剪應用程式。 這可以針對偵錯和發行模式個別設定。 如需詳細資訊，請參閱 修剪獨立部署和可執行檔 和 Trim 選項。

  發行組建會啟用預設值。

• 修剪數據粒度

  控制如何積極捨棄 IL。 有兩種模式可從中選取：

  • Link 會啟用成員層級修剪，這會從類型中移除未使用的成員。
  • CopyUsed （預設值） 會啟用元件層級修剪，這會在使用元件的任何部分時保留整個元件。

• Java 最大堆積大小

  將此值設定為增加應用程式可以使用的記憶體大小。 例如，的值 2G 會將堆積大小增加為 2 GB。 請注意，無法保證堆積的大小，而且要求太多堆積記憶體可能會強制其他應用程式過早終止。

  預設值為 1G。

• 其他 Java 選項

  指定建 置 .dex 檔案時要傳遞至 Java 編譯程式的其他命令行選項。 您可以從命令列輸入 java -help 以檢視可用的選項。

套件簽署

開啟時，簽署 。使用金鑰存放區詳細資料的 APK 檔案。 此選項預設為停用狀態。

iOS

這些是 iOS 特定的 .NET MAUI 設定。

組建

與建置 iOS 應用程式相關的 設定。

• 鏈接器行為

  鏈接器可以去除未使用的方法、屬性、欄位、事件、結構，甚至是類別，以減少應用程式的整體大小。 您可以將屬性加入其中任何一項 Preserve ，以防止連結器在串行化或反映時將其去除。

  警告

  啟用此功能可能會妨礙偵錯，因為它可能會去除屬性存取子，讓您檢查物件的狀態。

  選項為：

  • Don't link
  • Link Framework SDKs only (預設值)
  • Link All

• LLVM

  啟用時，使用 LLVM 優化編譯程式。 這可以針對偵錯和發行模式個別設定。

  發行組建會啟用預設值。

• 浮點數作業

  以 64 位浮點數作業的形式執行所有 32 位浮點數作業。

• Symbols

  啟用時，會從輸出中移除原生偵錯符號。 此功能預設為啟用。

• 垃圾收集行程

  啟用時，請使用並行垃圾收集行程。 此選項預設為停用狀態。

• 其他自變數

  要傳遞至應用程式組合程式代碼的其他命令行自變數。

• 最佳化

  啟用時，將 .PNG 映射優化。 此功能預設為啟用。

套件組合簽署

這些設定與產生和簽署應用程式套件組合有關。

• 方案

  設定套件組合的簽署配置。 它可以設定為下列其中一個值：

  • Manual provisioning：使用此值，您將負責自行設定布建配置檔和簽署憑證。
  • Automatic provisioning:(預設值） 使用此值，Visual Studio 會為您設定布建配置檔和簽署憑證，以簡化在裝置上測試時的應用程式部署。

• 簽署身分識別

  簽署身分識別是用於使用Apple codeign 公用程式進行程式代碼簽署應用程式套件組合的憑證和私鑰組。

  • Developer (automatic) (預設值)
  • Distribution (automatic)

• 布建配置檔

  布建配置檔是將應用程式識別碼和測試裝置清單的開發人員小組系結在一起的方式。 布建配置檔清單會篩選為只顯示符合所選身分識別和 Info.plist 中設定的應用程式識別碼（也稱為套件組合識別碼）的布建配置檔。 如果您要尋找的佈建配置檔不在清單中，請確定您已選擇相容的身分識別，並仔細檢查 Info.plist 中設定的套件組合識別碼是否正確。

• 自定義權利

  要用於權利之 plist 檔案。 如需詳細資訊，請參閱 權利。

• 自訂資源規則

  包含 Apple codeign 公用程式所使用的自訂規則的 plist 檔案。

  注意

  從 Mac OSX 10.10 起，Apple 已取代使用自定義資源規則。 因此，除非絕對必要，否則應該避免此設定。

• 其他自變數

  在組建的程式代碼簽署階段，要傳遞至 Apple 程式代碼簽署公用程式的其他命令行自變數。

偵錯

這些是與偵錯相關的設定。

• 偵錯

  啟用時，開啟偵錯。 預設值是以目前的配置檔為基礎。 偵錯配置檔會啟用偵錯，而發行配置檔則停用偵錯。

• 程式碼剖析

  啟用時，開啟程式代碼剖析。

IPA 選項

啟用時，會建置 iTunes 套件封存 （IPA）。

隨選資源

與隨選資源相關的 設定。 如需詳細資訊，請參閱 Apple Developer 檔 - 隨選資源基本資訊。

• 初始標記

  同時從 App Store 下載應用程式時所下載之隨選資源的標籤。 以分號 ;分隔標記。

• 預先擷取順序

  安裝應用程式之後所下載之隨選資源的標籤。 以分號 ;分隔標記。

• 嵌入

  啟用時，在應用程式套件組合中內嵌隨選資源。 此功能預設為啟用。 停用此設定以使用 網頁伺服器。

• Web server

  裝載隨選資源之 Web 伺服器的 URI。

執行選項

在 iOS 或 macOS 裝置上執行應用程式的相關選項。

• 執行模式

  此設定會決定應用程式在目標裝置上執行的方式。

• Start 自變數

  在裝置上啟動時，要傳遞至應用程式的其他命令行自變數。

• 額外的 mlaunch 自變數

  要傳遞至 mlaunch 的其他命令行自變數。

• 環境變數

  在裝置上執行應用程式時，要設定的環境變數名稱/值組。