安裝

若要開始在 Windows 上開發原生、跨平臺 .NET MAUI 應用程式，請遵循 安裝 步驟安裝 Visual Studio 2022 17.12 或更新版本。

必要條件

• Visual Studio 2022 17.12 或更新版本。 如需支援的操作系統、硬體、支持的語言和其他需求和指引的相關信息，請參閱 Visual Studio 2022系統需求。

若要建置、簽署及部署適用於 iOS 和 Mac Catalyst 的 .NET MAUI 應用程式，您也需要：

• 與 Xcode 相容的 Mac。 如需詳細資訊，請參閱Apple的最低 需求檔。
• 特定版本的 Xcode，視您使用的 .NET MAUI 版本而定。 如需詳細資訊，請參閱 發行版本。
• Apple ID 和付費 Apple Developer Program 註冊。 需要 Apple ID 才能將應用程式部署至裝置，以及將應用程式提交至 Apple Store。

或者，若要直接從 Windows 將應用程式的偵錯組建部署至具有經常性重新啟動的 iOS 裝置，您需要：

• Apple Developer 帳戶和付費的 Apple Developer Program 註冊。

安裝

1. 若要建立 .NET MAUI 應用程式，您必須下載最新版的 Visual Studio 2022：

   • 下載 Visual Studio 2022 Community

   • 下載 Visual Studio 2022 Professional

   • 下載 Visual Studio 2022 Enterprise

2. 安裝 Visual Studio，或透過 Visual Studio 安裝程式修改現有的安裝，並使用其預設選擇性安裝選項安裝 .NET 多平臺應用程式 UI 開發工作負載：

   

若要開始在 Windows、macOS 或 Linux 上開發原生、跨平臺 .NET MAUI 應用程式，請遵循 安裝 步驟安裝最新的 Visual Studio Code。

必要條件

若要建置、簽署及部署適用於 iOS 和 Mac Catalyst 的 .NET MAUI 應用程式，您需要：

• 與 Xcode 相容的 Mac。 如需詳細資訊，請參閱Apple的最低 需求檔。
• 特定版本的 Xcode，視您使用的 .NET MAUI 版本而定。 如需詳細資訊，請參閱 發行版本。
• Apple ID 和付費 Apple Developer Program 註冊。 需要 Apple ID 才能將應用程式部署至裝置，以及將應用程式提交至 Apple Store。

安裝 Visual Studio Code

1. 若要建立 .NET MAUI 應用程式，您必須下載最新版本的 Visual Studio Code：

   • 下載 Visual Studio Code

2. 安裝 Visual Studio Code。 如需如何安裝 Visual Studio Code 的詳細指示，請參閱在 Windows上 Visual Studio Code、macOS 上的 Visual Studio Code和 Linux 上的 Visual Studio Code。

安裝 .NET MAUI 擴充功能

您必須先安裝 .NET MAUI 擴充功能，才能在 Visual Studio Code 中建立 .NET MAUI 應用程式：

1. 啟動 Visual Studio Code。

2. 在 Visual Studio Code 中，流覽至 [延伸模組] 索引卷標，然後搜尋 “.NET MAUI”。 然後，按 [安裝] 按鈕，選取 .NET MAUI 擴充功能 並加以安裝：

   

   .NET MAUI 延伸模組會自動安裝 C# 開發工具包和 C# 延伸模組，這是 .NET MAUI 延伸模組執行的必要專案。 如需 C# 開發工具包的詳細資訊，請參閱 C# Dev Kit for Visual Studio Code。

將您的帳戶連線至 C# 開發工具包

使用 C# Dev Kit 需要您使用具備有效 Visual Studio 訂閱的 Microsoft 帳戶進行登入：

1. 在開始使用 .NET MAUI 的 [歡迎] 頁籤中，按下 [連線 (Connect)] 按鈕：

   

   請依照提示登入您的Microsoft帳戶。 如需詳細資訊，請參閱 登入 C# 開發工具包。

如需 C# 開發工具組授權的詳細資訊，請參閱 C# 開發工具包常見問題。

設定 .NET 環境

您必須在電腦上安裝 .NET SDK，才能開發 .NET MAUI 應用程式。 如果您沒有在計算機上安裝 .NET SDK，在 Windows 上安裝 .NET SDK 的慣用方法是透過 Visual Studio 安裝程式。 如需詳細資訊，請參閱 安裝資訊。

或者，若要手動安裝 .NET SDK：

1. 下載 .NET 安裝程式。

2. 執行 .NET 安裝程式來安裝 .NET SDK。 如需詳細資訊，請參閱 在 Windows、Linux 和 macOS 上安裝 .NET。

   提示

   在 Linux 上，您可以使用 文稿式安裝指示來安裝 .NET SDK。

若要確認已安裝 .NET SDK：

1. 開啟終端機。

2. 在終端機中，執行下列命令：

   dotnet --version
   

   您應該會看到已安裝的 .NET SDK 版本。

   注意

   您可能需要先重新啟動計算機，再確認已安裝 .NET SDK。

設定 .NET MAUI 環境

您必須在電腦上安裝 .NET MAUI SDK，才能開發 .NET MAUI 應用程式。 如果您沒有在計算機上安裝 .NET MAUI SDK，在 Windows 上安裝 .NET MAUI SDK 的慣用方法是透過 Visual Studio 安裝程式。 如需詳細資訊，請參閱 安裝資訊。

或者，若要手動安裝 .NET MAUI SDK：

1. 開啟終端機。

2. 在 Windows 上的終端機中，執行下列命令：

   dotnet workload install maui
   

   在macOS上的終端機中，執行下列命令：

   sudo dotnet workload install maui
   

   在 Linux 上的終端機中，執行下列命令：

   dotnet workload install maui-android
   

若要確認已安裝 .NET MAUI SDK：

1. 開啟終端機。

2. 在終端機中，執行下列命令：

   dotnet workload list
   

   在 Windows 和 macOS 上，您應該會看到 maui 工作負載標識碼與已安裝的版本一起列出。 不過，如果您已透過 Windows 上的 Visual Studio 安裝程式安裝它，則會列出下列工作負載標識碼：

   android
   maui-windows
   maccatalyst
   ios
   

   在 Linux 上，您應該會看到 maui-android 工作負載標識碼與已安裝的版本一起列出。

設定目標平臺

若要建置和偵錯 .NET MAUI 應用程式，您必須擁有相對於開發電腦作業系統的有效目標平臺。 下表列出每個作業系統上支援的目標平臺：

建置適用於 Android 和 Apple 平臺的 .NET MAUI 應用程式需要您執行額外的設定和設定。

Android

為了使用 Visual Studio Code 在 Android 上進行 .NET MAUI 開發設置機器，請按照以下步驟操作：

• 下載並安裝 Java SDK 如需詳細資訊，請參閱 下載並安裝 Java JDK。
• 下載並安裝 Android SDK。 如需詳細資訊，請參閱 下載並安裝 Android SDK。
• 下載並安裝Android模擬器。 如需詳細資訊，請參閱 下載並安裝 Android 模擬器。

下載並安裝 Java SDK

若要下載並安裝 Java SDK，並將 Visual Studio Code 設定為使用它：

1. 下載並安裝 Microsoft OpenJDK 17.0 或更新版本。 如需安裝 OpenJDK 的相關資訊，請參閱 安裝 Microsoft 版本的 OpenJDK。

   重要

   請確定您記下 OpenJDK 安裝的位置，因為下一個步驟中是必要的。

2. 請確定您已透過下列其中一種方法設定 OpenJDK 的路徑：

   1. 設定 JAVA_HOME 環境變數，以定義您電腦的 Java SDK 路徑。 這是建議的方法，它會在機器層級定義 Java SDK 路徑。

      注意

      如果您透過 MSI 在 Windows 上安裝 OpenJDK，您可以選擇加入安裝程式設定 JAVA_HOME 環境變數。

   2. 在 Visual Studio Code 中，在 Windows 上按 CTRL+SHIFT+P，或在 macOS 上 CMD+SHIFT+P，然後選取 [.NET MAUI：設定 Android，然後選取 [選取 Java SDK 位置]， 在使用者/工作區層級設定 Java SDK 路徑。

   3. 將 Java SDK 路徑配置在 .csproj 檔案中，方法是將 $(JavaSdkDirectory) MSBuild 屬性設定為 OpenJDK 路徑。 這會在專案層級定義 Java SDK 路徑。

下載並安裝 Android SDK

若要下載並安裝 Android SDK，並設定 Visual Studio Code 以使用它：

1. 透過下列其中一種方法下載並安裝 Android SDK：

   1. 建立新的 .NET MAUI 專案，然後使用 InstallAndroidDependencies 建置目標，以下載並安裝 Android SDK，以協助設定 Android 環境。 這是建議的方法。 如需詳細資訊，請參閱 使用 InstallAndroidDependencies 目標。
   2. 在 Windows 上下載並安裝 Android SDK，方法是 在 Visual Studio中安裝 .NET MAUI 開發工作負載，然後在 Android上 建立和執行 .NET MAUI 應用程式。 此程式可確保已安裝 Android SDK 和 Android 模擬器。
   3. 透過 Android Studio 下載並安裝 Android SDK。 如需詳細資訊，請參閱 在 developer.android.com 上安裝 Android Studio。
   4. 透過您慣用的套件管理員在Linux上下載並安裝Android SDK。

2. 請確定您已透過下列其中一種方法設定 Android SDK 的路徑：

   1. 設定 ANDROID_HOME 環境變數，以定義您電腦的 Android SDK 路徑。 這是建議的方法，它會在機器層級定義Android SDK 路徑。
   2. 在 Visual Studio Code 中，在 Windows 上按 CTRL+SHIFT+P，或在 macOS 上 CMD+SHIFT+P，然後選取 [.NET MAUI：設定 Android，然後選取 [選取 Android SDK 位置]，在使用者/工作區層級設定 Android SDK 路徑。
   3. 在 .csproj 檔案中設定 Android SDK 路徑，方法是將 $(AndroidSdkDirectory) MSBuild 屬性設定為 Android SDK 路徑。 這會在專案層級定義 Android SDK 路徑。

3. 在 Visual Studio Code 中，若要確認您的 Android 環境設定正確，請在 Windows 中按下 CTRL+SHIFT+P，或在 macOS 中按下 CMD+SHIFT+P，然後選取「.NET MAUI：設定 Android」，接著選取「重新整理 Android 環境」。 必須解決任何偵測到的錯誤：

   • 在命令選擇區中，選取 .NET MAUI：設定 Android，然後分別選取 選取 Android SDK 位置 和 選取 Android SDK 位置，並驗證它們是否正確指向各自的安裝位置。 在 Windows 上，如果您透過 Visual Studio 安裝 SDK，OpenJDK 會位於 C：\Program Files\Microsoft，而 Android SDK 會位於 C：\Program Files （x86）\Android\android-sdk。
   • 請確定您的 Android SDK 資料夾具有子資料夾，例如 build-tools、cmdline-tools，以及 平臺工具。
   • 請確定 OpenJDK 資料夾具有子資料夾，例如 bin、lib等等。
   • 請確定 ANDROID_HOME 環境變數已設定為 Android SDK 路徑。
   • 請確定 JAVA_HOME 環境變數已設定為 Java SDK 路徑。
   • 如果尚未接受 Android 授權，請在具有提升權限的終端機中，瀏覽到 Android SDK 的 cmdline-tools/{version}/bin 資料夾，然後執行 sdkmanager --licenses，並遵循 CLI 提示。

使用 InstallAndroidDependencies 目標

在 Android 上安裝 .NET MAUI 專案所需相依性的建議方法是執行 InstallAndroidDependencies MSBuild 目標。 如果尚未安裝，此目標將會為您安裝 Android SDK。

在終端機中，建立新的 .NET MAUI 專案：

dotnet new maui -n "MyMauiApp"

在終端機中，將目錄變更為 MyMauiApp，並在指定 InstallAndroidDependencies 建置目標時建置應用程式：

cd MyMauiApp
dotnet build -t:InstallAndroidDependencies -f:net9.0-android -p:AndroidSdkDirectory="/path/to/sdk" -p:AcceptAndroidSDKLicenses=True

在上述命令中：

• -p:AndroidSdkDirectory="/path/to/sdk" 將 Android 相依性安裝或更新至指定的絕對路徑。 建議的路徑是在 Windows 上 %LOCALAPPDATA%/Android/Sdk，以及 macOS 上的 $HOME/Library/Android/sdk。
• -p:AcceptAndroidSDKLicenses=True 接受開發所需的 Android 授權。

請嘗試避免使用包含空格或非 ASCII 字元的路徑。

下載並安裝Android模擬器

若要下載並安裝要在其中執行應用程式的 Android 模擬器：

1. 在終端機中，流覽至 {YOUR_ANDROID_SDK_FOLDER}/cmdline-tools/{version}/bin/。

2. 在終端機中，使用 sdkmanager 命令來下載並安裝 Android 模擬器：

   在 Windows 上，執行下列命令：

   sdkmanager --install emulator
   sdkmanager --install "system-images;android-35;google_apis;x86_64"
   

   在macOS上，執行下列命令：

   ./sdkmanager --install emulator
   ./sdkmanager --install "system-images;android-35;google_apis;arm64-v8a"
   

   注意

   上述命令假設 Apple Silicon Mac。 針對 Intel Mac，請將 arm64-v8a 取代為 x86_64。

   如需 sdkmanager 命令的詳細資訊，請參閱 developer.android.com 上的 sdkmanager。

3. 在終端機中，使用 avdmanager 命令來建立新的 Android 模擬器：

   在 Windows 上，執行下列命令：

   avdmanager create avd -n MyAndroidVirtualDevice-API35 -k "system-images;android-35;google_apis;x86_64"
   

   在macOS上，執行下列命令：

   ./avdmanager create avd -n MyAndroidVirtualDevice-API35 -k "system-images;android-35;google_apis;arm64-v8a"
   

   注意

   上述命令假設 Apple Silicon Mac。 針對 Intel Mac，請將 arm64-v8a 取代為 x86_64。

   如需 avdmanager 命令的詳細資訊，請參閱 developer.android.com 上的 avdmanager。

iOS 和 macOS

使用 Visual Studio Code 設定您的 Mac，以便在 iOS 和 Mac Catalyst 上進行 .NET MAUI 開發：

1. 安裝您使用之 .NET MAUI 版本所需的 Xcode 版本。 如需詳細資訊，請參閱 發行版本。 您可以從 Apple App Store 下載最新的穩定 Xcode 版本。

2. 在終端機中，執行下列命令以取得 Xcode 命令行工具：

   xcode-select --install
   

3. 啟動 Xcode 並接受任何許可協定。 如果模擬器未開始安裝，請流覽至 Xcode > 設定 > 元件，並安裝您選擇的模擬器運行時間。

4. 要確認您的 Apple 環境已在 Visual Studio Code 中正確設定，請按下 CMD+SHIFT+P，然後選取 [.NET MAUI：設定 Apple]，接著選擇 重新整理 Apple 環境。 必須解決任何偵測到的錯誤：

   • 請確定您已在終端機中執行 xcode-select --install。
   • 如果您收到找不到 Xcode 的錯誤，請在終端機中執行 xcode-select -p，並檢查它是否傳回 Xcode 安裝的路徑。
   • 開啟 Xcode 以確保它正確載入，然後流覽至 [Xcode > 設定] > [位置]，並檢查 [命令行工具] 字段是否指向正確的 Xcode 安裝。

疑難排解

如果您在 Visual Studio Code 中安裝 .NET MAUI 延伸模組時遇到問題，可找到更多相關資訊，方法是前往 [輸出] 視窗（在 Windows 上按CTRL+SHIFT+U，或在 macOS 上按 CMD+SHIFT+U），然後在下拉式清單中選取 [.NET MAUI]。

提供意見反應

若要從 Visual Studio Code 內部提供 .NET MAUI 延伸模塊的意見反應，請流覽至 [說明 > 報表問題] 對話框。 然後，請確定您選取 [錯誤報告] 作為 [] 的值，這是 下拉式清單、[A VS Code 擴充功能] 作為 [For] 下拉式清單的值，並將 “.NET MAUI” 作為 Extension 下拉式清單的值：