安装

若要开始在 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 开发人员计划注册。 需要 Apple ID 才能将应用部署到设备，以及将应用提交到 Apple Store。

或者，要使用热重启将应用的调试版本直接从 Windows 部署到 iOS 设备，需要：

• Apple 开发人员帐户和付费的 Apple 开发人员计划注册。

安装

1. 若要创建 .NET MAUI 应用，需要下载最新版本的 Visual Studio 2022：

   • 下载 Visual Studio 2022 社区

   • 下载 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 开发人员计划注册。 需要 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 扩展

在 Visual Studio Code 中创建 .NET MAUI 应用之前，需要安装 .NET MAUI 扩展：

1. 启动 Visual Studio Code。

2. 在 Visual Studio Code 中，导航到扩展选项卡并搜索“.NET MAUI”。 然后选择 .NET MAUI 扩展，然后按 安装 按钮进行安装：

   

   .NET MAUI 扩展会自动安装 C# 开发工具包和 C# 扩展，有了它们，.NET MAUI 扩展才能运行。 有关 C# 开发工具包的详细信息，请参阅 适用于 Visual Studio Code 的 C# 开发工具包。

将帐户连接到 C# 开发工具包

使用 C# 开发工具包需要您使用具有有效 Visual Studio 订阅的 Microsoft 帐户登录。

1. 在用于开始使用 .NET MAUI 的欢迎选项卡中，按连接按钮：

   

   按照提示登录到Microsoft帐户。 有关详细信息，请参阅登录到 C# 开发工具包。

有关 C# 开发工具包许可的详细信息，请参阅 C# 开发工具包常见问题解答。

设置 .NET 环境

需要计算机上安装的 .NET SDK 才能开发 .NET MAUI 应用。 如果计算机上未安装 .NET SDK，在 Windows 上安装它的首选方法是通过 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 上安装它的首选方法是通过 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 工作负载 ID。 但是，如果你已通过 Windows 上的 Visual Studio 安装程序安装了它，则会列出以下工作负荷 ID：

   android
   maui-windows
   maccatalyst
   ios
   

   在 Linux 上，您应该会看到与已安装版本一起列出的 maui-android 工作负载 ID。

设置目标平台

若要构建和调试 .NET MAUI 应用，您需要有一个适用于开发计算机操作系统的有效目标平台。 下表列出了每个操作系统上支持的目标平台：

生成适用于 Android 和 Apple 平台的 .NET MAUI 应用需要执行其他设置和配置。

安卓

要在 Android 上通过 Visual Studio Code 进行 .NET MAUI 开发，需要设置计算机的步骤如下：

• 下载并安装 Java SDK 有关详细信息，请参阅 下载并安装 Java JDK。
• 下载并安装 Android SDK。 有关详细信息，请参阅 下载并安装 Android SDK。
• 下载并安装 Android 仿真器。 有关详细信息，请参阅 下载并安装 Android 仿真器。

下载并安装 Java SDK

若要下载并安装 Java SDK，并配置 Visual Studio Code 以使用它：

1. 下载并安装 Microsoft OpenJDK 17。 有关安装 OpenJDK 的信息，请参阅 安装 OpenJDK的 Microsoft 版本。

   或者，可以使用 InstallAndroidDependencies 生成目标来安装 Java SDK（和 Android SDK），而不是手动下载和安装 Java SDK。 有关详细信息，请参阅使用 InstallAndroidDependencies 目标。

   重要

   确保记下 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. 通过将 $(JavaSdkDirectory) MSBuild 属性设置为 OpenJDK 路径，在 .csproj 文件中配置 Java SDK 路径。 这将在项目级别定义 Java SDK 路径。

下载并安装 Android SDK

若要下载并安装 Android SDK，并配置 Visual Studio Code 以使用它：

1. 通过以下方法之一下载并安装 Android SDK：

   1. 创建新的 .NET MAUI 项目后，下载并安装 Android SDK，然后使用 InstallAndroidDependencies 构建目标，这将帮助设置 Android 环境。 这是建议的方法。 有关详细信息，请参阅使用 InstallAndroidDependencies 目标。
   2. 通过在 Visual Studio中 安装 .NET MAUI 开发工作负载，然后在 Android上创建并运行 .NET MAUI 应用，在 Windows 上下载并安装 Android SDK。 此过程将确保已安装 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. 通过将 $(AndroidSdkDirectory) MSBuild 属性设置为 Android SDK 路径，在 .csproj 文件中配置 Android SDK 路径。 这将在项目级别定义 Android SDK 路径。

3. 在 Visual Studio Code 中，通过按 Windows 上的 Ctrl+Shift+P 或 macOS 上的 Cmd+Shift+P ，然后选择 .NET MAUI：配置 Android，然后 刷新 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 文件夹具有子文件夹，例如 生成工具、cmdline-tools，以及 平台工具。
   • 确保 OpenJDK 文件夹具有子文件夹，例如 bin、库等。
   • 确保 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 许可证以便进行开发。
• （可选）-p:JavaSdkDirectory="/path/to/sdk" 将 Java SDK 安装到指定的绝对路径。

尝试避免使用包含空格或非 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 在 iOS 和 Mac Catalyst 上设置 Mac for .NET MAUI 开发，请执行以下操作：

1. 安装你使用的 .NET MAUI 版本所需的 Xcode 版本。 有关信息，请参阅发行版本。 可以从 Apple App Store 下载最新的稳定 Xcode 版本。

2. 在终端中，运行以下命令以获取 Xcode 命令行工具：

   xcode-select --install
   

3. 启动 Xcode 并接受任何许可协议。 如果模拟器未开始安装，请导航到 Xcode > 设置 > 组件，并安装你选择的模拟器运行环境。

4. 在 Visual Studio Code 中，按 Cmd+Shift+P ，然后选择 .NET MAUI：配置 Apple，然后 刷新 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 扩展的反馈，请导航到 帮助 > 报告问题 对话框。 然后，请确保选择“Bug 报告”作为这是一个下拉列表的值，“A VS Code 扩展”作为对于下拉列表的值，“.NET MAUI”作为扩展下拉列表的值：

先决条件

若要生成、签名和部署适用于 iOS 和 Mac Catalyst 的 .NET MAUI 应用，需要：

• 与 Xcode 兼容的 Mac。 有关详细信息，请参阅 Apple 的最低要求文档。
• Xcode 的特定版本，具体取决于你使用的 .NET MAUI 版本。 有关信息，请参阅发行版本。
• Apple ID 和付费 Apple 开发人员计划注册。 需要 Apple ID 才能将应用部署到设备，以及将应用提交到 Apple Store。

若要开始在 Windows、macOS 或 Linux 上开发本机跨平台 .NET MAUI 应用，请按照 安装 步骤安装最新的 Visual Studio Code。

若要构建和调试 .NET MAUI 应用，您需要有一个适用于开发计算机操作系统的有效目标平台。 下表列出了每个操作系统上支持的目标平台：

安装 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 扩展

在 Visual Studio Code 中创建 .NET MAUI 应用之前，需要安装 .NET MAUI 扩展：

1. 启动 Visual Studio Code。

2. 在 Visual Studio Code 中，导航到扩展选项卡并搜索“.NET MAUI”。 然后选择 .NET MAUI 扩展，然后按 安装 按钮进行安装：

   

   .NET MAUI 扩展会自动安装 C# 开发工具包和 C# 扩展，有了它们，.NET MAUI 扩展才能运行。 有关 C# 开发工具包的详细信息，请参阅 适用于 Visual Studio Code 的 C# 开发工具包。

完成演练中的步骤

安装 .NET MAUI 扩展后，你将看到 .NET MAUI 演练“.NET MAUI 入门”欢迎。

单击并按照每个步骤中的提示完全配置 .NET MAUI 环境和目标平台：

1. 将帐户连接到 C# 开发工具包扩展
2. 设置 .NET 环境
3. 设置 .NET MAUI 环境
4. 设置 iOS 和 macOS 环境
5. 设置 Android 环境

设置 Android 环境步骤将设置在 Android 作为目标平台时成功所需的一切，设置 iOS 和 macOS 环境步骤将设置 iOS 和 Mac 作为目标平台成功所需的一切。

您也可以通过命令面板访问此操作指南。 选择 “欢迎：打开演练...”，然后选择 开始使用 .NET MAUI。

访问改进的设置体验

1. 在 Visual Studio Code 中，按 Windows 上的 Ctrl+Shift+P，或在 macOS 上按 Cmd+Shift+P，选择“首选项：打开设置”（UI）。

   

2. 前往扩展 > .NET MAUI 并检查 Maui > 配置: 改进的设置体验 选项。

   

3. 返回 .NET MAUI 入门演练。 确保你能够在演练的各个步骤中看到设置 Android 环境。

   

将帐户连接到 C# 开发工具包

使用 C# 开发工具包需要您使用具有有效 Visual Studio 订阅的 Microsoft 帐户登录。

1. 在用于开始使用 .NET MAUI 的欢迎选项卡中，按连接按钮：

   

   按照提示登录到Microsoft帐户。 有关详细信息，请参阅登录到 C# 开发工具包。

有关 C# 开发工具包许可的详细信息，请参阅 C# 开发工具包常见问题解答。

设置 .NET 环境

需要计算机上安装的 .NET SDK 才能开发 .NET MAUI 应用。 如果计算机上未安装 .NET SDK，在 Windows 上安装它的首选方法是通过 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 上安装它的首选方法是通过 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 工作负载 ID。 但是，如果你已通过 Windows 上的 Visual Studio 安装程序安装了它，则会列出以下工作负荷 ID：

   android
   maui-windows
   maccatalyst
   ios
   

   在 Linux 上，您应该会看到与已安装版本一起列出的 maui-android 工作负载 ID。

设置 Android 环境

若要设置 Android 开发环境，只需单击“设置 Android 环境”演练步骤中的“配置 Android 环境”按钮即可输入完整的 Android 购置流。

Android 下载安装流程将分析你的 Android 环境，并建议安装所有缺少的组件：

• Android SDK 和 Java SDK：需要 Android SDK 和 Java SDK 组件。

  • Android 获取流将提示你直接安装这些组件，或选择你可能已经安装的预先存在的安装。

    

  • 若要进一步配置 SDK 和 JDK 安装，请参阅有关如何 手动安装和配置 Android 的说明。

• Android 模拟器：建议安装 Android 仿真器，并且不需要物理设备。

  • Android 购置流将提示你直接安装默认模拟器。

    

  • 若要进一步配置模拟器，请按照说明 手动安装 Android 模拟器。

正确配置 Android 环境后，系统会通知你“适用于 .NET MAUI 的 Android 环境已全部设置！”

查看“输出”窗格，了解有关 Android 环境状态的更多详细信息。

设置 iOS 和 macOS 环境

若要使用 Visual Studio Code 在 iOS 和 Mac Catalyst 上设置 Mac for .NET MAUI 开发，请执行以下操作：

1. 安装你使用的 .NET MAUI 版本所需的 Xcode 版本。 有关信息，请参阅发行版本。 可以从 Apple App Store 下载最新的稳定 Xcode 版本。

2. 在终端中，运行以下命令以获取 Xcode 命令行工具：

   xcode-select --install
   

3. 启动 Xcode 并接受任何许可协议。 如果模拟器未开始安装，请导航到 Xcode > 设置 > 组件，并安装你选择的模拟器运行环境。

4. 在 Visual Studio Code 中，通过单击“设置 iOS 和 macOS 环境”演练步骤中的“配置 iOS 和 macOS 环境”，验证是否已配置 Xcode 环境。

必须解决检测到的任何错误：

• 确保已在终端中运行 xcode-select --install。
• 如果收到 Xcode 未找到的错误，请在终端中运行 xcode-select -p，并检查它是否返回 Xcode 安装的路径。
• 打开 Xcode 以确保它正确加载，然后导航到 Xcode > 设置 > 位置，并检查 命令行工具 字段是否指向正确的 Xcode 安装。

正确配置 Xcode 环境后，将收到通知：“已设置适用于 .NET MAUI 的 iOS 和 macOS 环境！

提供反馈

若要从 Visual Studio Code 内部提供有关 .NET MAUI 扩展的反馈，请导航到 帮助 > 报告问题 对话框。 然后，请确保选择“Bug 报告”作为这是一个下拉列表的值，“A VS Code 扩展”作为对于下拉列表的值，“.NET MAUI”作为扩展下拉列表的值：