.NET MAUI 应用的项目配置

.NET MAUI 使用单项目系统来管理跨平台应用的配置。 .NET MAUI 中的项目配置类似于 Visual Studio 中的其他项目，右键单击“解决方案资源管理器”中的项目，然后选择“属性”。

应用程序

“应用程序”部分介绍与应用面向的平台相关的一些设置以及输出文件和默认命名空间。

• 常规

  介绍有关应用的一些基本设置。

  设置	默认值	说明
  程序集名称	$(MSBuildProjectName)	指定将保存程序集清单的输出文件的名称。
  默认命名空间	多种多样。	指定添加到项目中的文件的基命名空间。 这通常默认为项目的名称或创建项目时指定的值。

• 面向 iOS

  如果要面向 iOS 和 macOS（使用 Mac Catalyst），则这些设置将描述目标 iOS 版本。

  设置	默认值	说明
  面向 iOS 平台	已选中	指定此项目将面向 iOS 平台。
  面向 iOS 框架	net8.0-ios	用于面向 iOS 的目标框架名字对象。
  目标 iOS 框架最低版本	14.2	应用面向的 iOS 最低版本。

• 面向 Android

  如果要面向 Android，则这些设置将描述目标 Android 版本。

  设置	默认值	说明
  面向 Android 平台	已选中	选中后，.NET MAUI 项目将面向并生成应用的 Android 版本。 取消选中以禁用 Android 目标。
  面向 Android 框架	net8.0-android	用于面向 Android 的目标框架名字对象。
  目标 Android 框架最低版本	21.0	应用面向的最低 Android 版本。

• 面向 Windows

  如果要面向 Windows，则这些设置将描述目标 Windows 版本。

  设置	默认值	说明
  面向 Windows 平台	已选中	选中后，.NET MAUI 项目将面向并生成应用的 Windows 版本。 取消选中以禁用 Windows 目标。
  面向 Windows 框架	net8.0-windows10.0.19041.0	用于面向 Windows 的目标框架名字对象。
  目标 Windows 框架最低版本	10.0.17763.0	应用面向的最低 Windows 版本。

生成

“生成”部分介绍与编译应用相关的设置。

常规

与目标平台相关的设置。

• “条件编译符”号

  指定要在其上执行条件编译的符号。 用分号 ; 分隔符号。 符号可以分解为目标平台。 有关详细信息，请参阅条件编译。

• 目标平台

  指定将作为输出文件目标的处理器。 选择 Any CPU 以指定可接受任何处理器，以便应用程序可以在各种各样的硬件上运行。

  通常，此值设置为 Any CPU，运行时标识符设置用于面向 CPU 平台。

  选项	说明
  Any CPU	（默认）将程序集编译成可在任意平台上运行。 您的应用程序将尽可能作为 64 位进程运行；当只有 32 位模式可用时，才会回退到 32 位。
  x86	将程序集编译成可由兼容 32 位、x86 的运行时运行。
  x64	将程序集编译成可由支持 AMD64 或 EM64T 指令集的计算机上的 64 位运行时运行。
  ARM32	将程序集编译成可由支持 AMD64 或 EM64T 指令集的计算机上的 64 位运行时运行。
  ARM64	将程序集编译成可以在搭载支持 A64 指令集的高级 RISC 计算机 (ARM) 处理器的计算机上由 64 位运行时运行。

• 可以为 Null

  指定项目范围内可以为 null 的 C# 上下文。 有关详细信息，请参阅可为空的引用。

  选项	说明
  取消设置	（默认）如果未设置此设置，则默认值为 Disable。
  Disable	禁用可为 null 警告。 所有引用类型变量都是可为 null 引用类型。
  Enable	此编译器支持所有 null 引用分析和所有语言功能。
  Warnings	此编译器可执行所有 null 分析，并在代码可能取消引用 null 时发出警告。
  Annotations	当代码可能取消引用 null 时，编译器不会执行 null 分析，也不发出警告。

• 隐式全局使用

  支持项目 SDK 声明隐式全局使用。 默认情况下，此功能处于启用状态，并自动将许多 .NET MAUI 命名空间导入到所有代码文件中。 代码文件不需要为常见的 .NET MAUI 命名空间添加 using 语句。 有关更多信息，请参阅 MSBuild 属性 - ImplicitUsings。

• 不安全代码

  允许使用 unsafe 关键字的代码进行编译。 默认禁用了此属性。

• 优化代码

  启用编译器优化，使输出更小、更快、更高效。 每个目标平台都有一个处于“调试”或“发布”模式的选项。 通常，此功能针对“发布”模式启用，因为代码以牺牲有用调试信息为代价针对速度进行了优化。

• 调试符号

  指定生成过程中生成的调试符号的种类。

错误和警告

与编译期间如何处理和报告错误和警告相关的设置。

• 警告级别

  指定编译器警告的显示等级。

• 抑制特定警告

  阻止编译器生成指定警告。 使用逗号 , 或分号 ; 分隔多个警告编号。

• 将警告视为错误

  启用后，指示编译器将警告视为错误。 默认禁用了此属性。

• 将特定警告视为错误

  指定将哪些警告视为错误。 使用逗号 , 或分号 ; 分隔多个警告编号。

输出

与生成输出文件相关的设置。

• 基本输出路径

  指定生成过程中项目输出的基本位置。 将子文件夹追加到此路径，以区分项目配置。

  默认为 .\bin\。

• 基本中间输出路径

  指定生成过程中项目中间输出的基位置。 将子文件夹追加到路径以区分项目配置。

  默认为 .\obj\。

• 引用程序集

  启用后，将生成包含项目公共 API 的引用程序集。 默认禁用了此属性。

• 文档文件

  启用后，将生成包含 API 文档的文件。 默认禁用了此属性。

事件

在本部分中，可以添加在生成期间运行的命令。

• 预生成事件

  指定在生成开始前运行的命令。 如果项目是最新的，则不会运行。 非零退出代码会在生成运行之前使其失败。

• 生成后事件

  指定在生成开始前运行的命令。 如果项目是最新的，则不会运行。 非零退出代码会在生成运行之前使其失败。

• 何时运行生成后事件

  指定在哪种条件下运行生成后事件。

强命名

与对程序集进行签名相关的设置。

• 对程序集签名

  启用后，对输出程序集进行签名，使其具有强名称。

高级

与生成相关的其他设置。

• 语言版本

  项目中代码可用的语言版本。 默认为 10.0。

• 检查算法溢出

  当整数算术生成超出范围值时引发例外。 此设置可用于每个平台。 对于每个平台，默认处于禁用状态。

• 具有确定性

  为相同的输入生成相同的编译输出。 此设置可用于每个平台。 为每个平台启用默认值。

• 内部编译器错误报告

  向 Microsoft 发送内部编译器错误报告。 默认为 Prompt before sending。

• 文件对齐

  指定输出文件各部分的对齐位置，以字节为单位。 此设置可用于每个平台。 每个平台默认为 512。

包

“包”部分介绍与生成 NuGet 包相关的设置。

常规

与生成 NuGet 包相关的设置。

• 在生成时生成 NuGet 包

  启用后，在生成操作期间生成 NuGet 包文件。 默认禁用了此属性。

• 包 ID

  不区分大小写的包标识符，该标识符在 NuGet 包库中必须是唯一的，例如 nuget.org。ID 可能不包含对 URL 无效的空格或字符，通常遵循 .NET 命名空间规则。

  默认为 MSBuild 值 $(AssemblyName)。

• 标题

  明了易用的包标题，通常用在 UI 显示中，如 nuget.org 上和 Visual Studio 中包管理器上的那样。

• 包版本

  包的版本，遵循 major.minor.patch 模式。 版本号可能包括预发行后缀。

  默认为 MSBuild 值 $(ApplicationDisplayVersion)。

• 作者

  用逗号分隔的作者列表与 nuget.org 上的个人资料名称匹配。这些内容会显示在 nuget.org 上的 NuGet 库中，且由同一作者用于交叉引用包。

  默认为 MSBuild 值 $(AssemblyName)。

• 公司

  与 NuGet 包关联的公司的名称。

  默认为 MSBuild 值 $(Authors)。

• Product

  与 NuGet 包关联的产品的名称。

  默认为 MSBuild 值 $(AssemblyName)。

• 描述

  用于 UI 显示的包的说明。

• 版权

  包的版权详细信息。

• 项目 URL

  包的主页 URL，通常显示在 UI 中以及 nuget.org 中。

• 图标

  包的图标图像。 图像文件大小被限制为 1 MB。 支持的文件格式为 JPEG 和 PNG。 建议图像分辨率为 128x128。

• 自述文件

  包的自述文件。 必须是 Markdown (.md) 文件。

• 存储库 URL

  指定存储库的 URL，该存储库是包的源代码所驻留和/或生成的位置。 要链接到项目页，请改用“项目 URL”字段。

• 存储库类型

  指定存储库的类型。 默认为“git”。

• 标记

  以分号分隔的标记和关键字列表，用于描述包并通过搜索和筛选功能帮助查找包。

• 发行说明

  在包版本中对更改所做的说明，通常在 UI 中使用，如 Visual Studio 包管理器中代替包说明的“更新”选项卡。

• 打包为 .NET 工具

  启用后，将项目打包为一种特殊包，包含可以通过“dotnet tool”命令安装的控制台应用程序。 默认禁用了此属性。

• 包输出路径

  确定将放置包的输出路径。

  默认为 MSBuild 值 $(OutputPath)。

• 程序集非特定语言

  哪个语言代码被视为非特定语言。 默认为未设置。

• 程序集版本

  如果未设置程序集的版本，则默认为 1.0.0.0。

• 文件版本

  如果未设置与文件关联的版本，则默认为 1.0.0.0。

许可证

• 包许可证

  指定项目包的许可证。 默认为 None。

• 符号

  • 生成符号包

    启用后，在打包项目时创建额外的符号包。 默认禁用了此属性。

代码分析

与代码分析相关的设置。

所有分析器

与分析运行时间相关的设置。

• 在生成时运行

  启用后，在生成时运行代码分析。 默认为已启用。

• 在实时分析时运行

  启用后，在键入时在编辑器中实时运行代码分析。 默认为已启用。

.NET 分析

与 .NET 分析器相关的设置。

• 在生成时强制执行代码样式（实验性）

  启用后，将在生成时生成有关代码样式的诊断。 默认禁用了此属性。

• 启用 .NET 分析器

  启用后，运行 .NET 分析器来帮助使用 API。 默认为已启用。

• 分析级别

  应在项目中运行的分析器集。 默认为 Latest。 有关详细信息，请参阅 MSBuild: AnalysisLevel。

MAUI 共享

这些是跨所有目标平台共享的 .NET MAUI 的项目设置。

常规

与 .NET MAUI 相关的常规设置。

• 应用程序标题

  应用程序的显示名称。

• 应用程序 ID

  采用反向域名格式的应用程序标识符，例如：com.microsoft.maui。

• 应用程序 ID (GUID)

  采用 GUID 格式的应用程序标识符。

• 应用程序显示版本

  应用程序的版本。 这应该是单位数整数。 默认为 1。

Android

这些是特定于 Android 的 .NET MAUI 设置。

清单

与 Android 清单相关的设置。

• 应用程序名称

  显示为应用程序名称的字符串。 这是应用标题栏中显示的名称。 如果未设置，则应用的 MainActivity 标签将用作应用程序名称。 默认设置为 @string/app_name，指示字符串资源 app_name 在 Resources/values/Strings.xaml 中的位置。

• 应用程序包名称

  用于唯一标识应用程序的字符串。 通常，包名称基于反向 Internet 域名约定，例如 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 级别在运行时使用，与在生成时使用的目标框架不同。 Android 将此版本用作提供向前兼容的一种方式。 也称为 targetSdkVersion，这应与目标框架 compileSdkVersion 匹配。

选项

用于生成 Android 应用的杂项选项。

• Android 包格式

  apk 或 bundle，分别将 Android 应用程序打包为 APK 文件或 Android 应用程序包。 这可以针对“调试”模式和“发布”模式单独设置。

  应用程序包是一种最新格式，适用于要在 Google Play 上提交的 Android 发布版本。

  默认值为 apk。

  选择 bundle 后，将设置其他 MSBuild 属性：

  • 将 AndroidUseAapt2 设置为 True。
  • 将 AndroidUseApkSigner 设置为 False。
  • 将 AndroidCreatePackagePerAbi 设置为 False。

• 快速部署（仅限调试模式）

  启用后，会以快于平常的速度将应用部署到目标设备。 此进程加快了生成/部署/调试周期，因为如果只更改程序集，则不会重新安装该包。 只有更新的程序集才会重新同步到目标设备。

  此项已默认启用。

• 按 ABI 生成

  启用后，将为每个选定的应用程序二进制接口 (ABI) 生成一个 Android 包 (apk)。 默认禁用了此属性。

• 使用增量打包

  启用后，将使用增量 Android 打包系统 (aapt2)。 此项已默认启用。

• Multi-Dex

  启用后，将允许 Android 生成系统使用 MultiDex。 默认为禁用。

• 代码收缩器

  选择要使用的代码收缩器。

  • ProGuard（默认）被视为旧代码收缩器。
  • r8 是下一代工具，它将 Java 字节代码转换为优化的索引代码。

• 未压缩的资源

  使指定的资源扩展保持未压缩状态。 用分号 ; 分隔扩展名。 例如：.mp3;.dll;.png。

• 开发人员检测

  启用后，将提供开发人员检测以用于进行调试和分析。 这可以为“调试”模式和“发布”模式单独设置。

  已为调试版本启用默认值。

• Debugger

  选择要使用的调试器。 默认值为 .NET (Xamarin)，用于托管代码。 可以选择 C++ 调试器来调试应用所用的本机库。

• AOT

  启用预先 (AOT) 编译。 这可以为“调试”模式和“发布”模式单独设置。

  已为发布版本启用默认设置。

• LLVM

  启用 LLVM 优化编译器。 默认为禁用。

• 启动跟踪

  启用启动跟踪。 这可以为“调试”模式和“发布”模式单独设置。

  已为发布版本启用默认设置。

• 垃圾回收

  启用后，将使用并发垃圾回收器。 默认为已启用。

• 启用剪裁

  启用后，将在发布期间剪裁应用程序。 这可以为“调试”模式和“发布”模式单独设置。 有关详细信息，请参阅剪裁自包含的部署和可执行项和剪裁选项。

  已为发布版本启用默认设置。

• 剪裁粒度

  控制 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 位浮点运算。

• 符号

  启用后，将从输出中剥离本机调试符号。 此项已默认启用。

• 垃圾回收器

  启用后，将使用并发垃圾回收器。 默认禁用了此属性。

• 其他参数

  要传递给应用程序绑定代码的其他命令行参数。

• 优化

  启用后，将优化 .PNG 图像。 此项已默认启用。

捆绑签名

这些设置与生成应用程序包并对其进行签名的操作相关。

• 方案

  配置捆绑包的签名方案。 它可以设置为以下值中的一个：

  • Manual provisioning：使用此值时，你将负责自行设置预配配置文件和签名证书。
  • Automatic provisioning：（默认）使用此值时，Visual Studio 将为你设置预配配置文件和签名证书，从而简化在设备上进行测试时的应用部署。

• 签名标识

  签名标识是证书和私钥对，用于使用 Apple 代码签名实用工具对应用程序包进行代码签名。

  • Developer (automatic)（默认值）
  • Distribution (automatic)

• 预配配置文件

  预配配置文件是一种将开发人员团队与应用 ID 和测试设备列表（可能有）绑定在一起的方法。 预置配置文件列表经过筛选，仅显示与所选标识和 Info.plist 中设置的应用 ID（也称为捆绑包标识符）匹配的预置配置文件。 如果要查找的预配配置文件不在列表中，请确保已选择兼容的标识，并仔细检查 Info.plist 中设置的捆绑包标识符是否正确。

• 自定义权利

  要用于权利的 plist 文件。 有关详细信息，请参阅权利。

• 自定义资源规则

  包含 Apple 代码签名实用工具使用的自定义规则的 plist 文件。

  注意

  从 Mac OSX 10.10 开始，Apple 已弃用自定义资源规则。 因此，除非绝对必要，否则应避免此设置。

• 其他参数

  要在生成的代码签名阶段传递给 Apple 代码签名实用工具的其他命令行参数。

调试

这些设置与调试相关。

• 调试

  启用后，将开启调试。 默认设置基于当前配置文件。 调试配置文件可启用调试，而发布配置文件可禁用调试。

• 分析

  启用后，将开启分析。

IPA 选项

启用后，将生成 iTunes 包存档 (IPA)。

按需资源

与按需资源相关的设置。 有关详细信息，请参阅 Apple 开发人员文档 - 按需资源基本信息。

• 初始标记

  从应用商店下载应用的同时下载的按需资源的标记。 使用分号 ; 分隔标记。

• 预提取顺序

  安装应用后下载的按需资源的标记。 使用分号 ; 分隔标记。

• 嵌入

  启用后，将在应用程序包中嵌入按需资源。 此项已默认启用。 禁用此设置以使用 Web 服务器。

• Web server

  托管按需资源的 Web 服务器的 URI。

运行选项

与在 iOS 或 macOS 设备上运行应用相关的选项。

• 执行模式

  此设置可确定如何在目标设备上运行应用。

• 启动参数

  在设备上启动应用时要传递给此应用的其他命令行参数。

• 其他 mlaunch 参数

  要传递给 mlaunch 的其他命令行参数。

• 环境变量

  在设备上运行应用时要设置的环境变量的名称-值对。