生成属性

MSBuild 属性控制目标的行为。

它们是在项目文件中指定的,例如 MSBuild PropertyGroup 中的 MyApp.csproj。

注意

在 .NET for Android 中,应用程序与绑定项目在技术上没有区别,因此属性将在两者中都起作用。 在实践中,强烈建议创建单独的应用程序和绑定项目。 MSBuild 绑定项目属性参考指南中 记录了主要用于绑定项目的属性 。

运行时范围

普通 Android 应用程序面向 .NET 11 及更高版本中的 CoreCLR。 面向 .NET 10 和更早版本的 Android 应用程序默认使用 Mono。 将 $(PublishAot) 设置为 true 会为受支持的发布版本或优化构建选择 NativeAOT 运行时,并且其优先级高于 $(UseMonoRuntime)。

$(UseMonoRuntime)=true 不是 .NET 11 的权宜之计。 .NET 11 SDK 会因 NETSDK1242 而拒绝它。 仅当目标框架支持 Mono 时,才使用适用于 .NET 10 及更早版本的 Mono 指南。

.NET 11 个 Android 应用程序需要 Android API 级别 24 或更高版本。 $(SupportedOSPlatformVersion) 设置应用程序的部署最小值,并映射到 //uses-sdk/@android:minSdkVersion Android 清单中。 它不选择目标 SDK 或表示 Google Play 策略。

.NET 11 CoreCLR 运行时包支持以下.NET运行时标识符(RID)和相应的 Android 应用程序二进制接口(API):

  • android-arm: armeabi-v7a
  • android-arm64: arm64-v8a
  • android-x64: x86_64

Android NativeAOT 是实验性的,支持相同的三个 RID。 RID 不同于 Android ABI 名称和模拟器系统映像体系结构。

AdbTarget

$(AdbTarget) 属性指定 Android 包可能要安装到或从中删除的 Android 目标设备。 此属性的值与 adb 目标设备选项相同。

AfterGenerateAndroidManifest

此属性中列出的 MSBuild 目标将在内部 _GenerateJavaStubs 目标(及在 AndroidManifest.xml 中生成 $(IntermediateOutputPath) 的位置)后直接运行。 如果想要对生成的 AndroidManifest.xml 文件进行任何修改,则可以使用此扩展点完成。

AndroidAapt2CompileExtraArgs

指定处理 Android 资产和资源时传递给 aapt2 compile 命令的命令行选项。

AndroidAapt2LinkExtraArgs

指定处理 Android 资产和资源时传递给 aapt2 link 命令的命令行选项。

AndroidAddKeepAlives

一个布尔属性,该属性控制链接器是否在绑定项目中插入 GC.KeepAlive() 调用,以防止过早地收集对象。

发布配置版本的默认值为 True。

对于使用 trimmable 类型映射的未裁剪构建,仅会在以下情况下插入 GC.KeepAlive() 调用 $(AndroidEnableLegacyCompatibilityAssemblyFixups) 也是 True。 使用 trimmable 类型映射的经裁剪生成版本不会插入这些调用。

AndroidAotAdditionalArguments

一个字符串属性,允许受支持的、使用 Mono 的 .NET 10 及更早版本项目在 Mono AOT 编译器的 --aot=... 参数中传递其他以逗号分隔的选项。 仅当启用了 Mono AOT 编译时,才会使用该属性。

通常情况下,此属性应保留为空,但在某些特殊场景中,它可以提供有用的灵活性。

该 $(AndroidAotAdditionalArguments) 属性不同于相关 $(AndroidExtraAotOptions) 属性; $(AndroidAotAdditionalArguments) 包含在选项中 --aot ,同时 $(AndroidExtraAotOptions) 将独立参数直接传递给 Mono AOT 编译器进程。

AndroidAotCustomProfilePath

aprofutil 应创建的用于保存 Mono AOT 分析器数据的文件。 默认值为 custom.aprof。

此属性适用于使用 Mono 的受支持的 .NET 10 及更早版本项目的旧版 AOT 分析目标。

AndroidAotProfilerPort

获取 Mono AOT 分析数据时应连接到的 aprofutil 端口。 默认值为 9999。

此属性适用于使用 Mono 的受支持的 .NET 10 及更早版本项目的旧版 AOT 分析目标。

AndroidAotEnableLazyLoad

启用经 Mono AOT 编译的程序集的延迟加载,而非在启动时预先加载这些程序集。

此属性适用于使用 Mono 的受支持的 .NET 10 及更早版本项目。 当启用 Mono AOT 且未包含调试符号时,默认值为 True。 它未配置 CoreCLR 或 NativeAOT。

在 .NET 6 中引入。

AndroidApk摘要算法

一个字符串值,指定将用于 jarsigner -digestalg 的摘要算法。

默认值为 SHA-256。

安卓Apk签名器附加参数

一个字符串属性,允许开发人员向 apksigner 工具提供自变量。

AndroidApk签名算法

一个字符串值,指定将用于 jarsigner -sigalg 的签名算法。

默认值为 SHA256withRSA。

AndroidApplication

此布尔值指示项目是用于 Android 应用程序 (True) 还是用于 Android 库项目(False 或不存在)。

在 Android 包中,可能只存在一个具有 <AndroidApplication>True</AndroidApplication> 的项目。 (遗憾的是,这一要求尚未得到验证,这可能会导致与 Android 资源有关的微妙和奇怪的错误。)

AndroidApplicationJavaClass

用于替代 android.app.Application 的完整 Java 类名称,当一个类继承自 Android.App.Application 时。

$(AndroidApplicationJavaClass) 属性通常由其他属性(如 $(AndroidEnableMultiDex) MSBuild 属性)设置。

AndroidAvoidEmitForPerformance

一个布尔属性,确定是否“避开” System.Reflection.Emit 以提高启动性能。 该属性默认为 True。

System.Reflection.Emit使用对 Android 上的启动性能有明显影响。 对于以下功能开关,默认禁用此行为:

  • Switch.System.Reflection.ForceInterpretedInvoke:在第二次调用MethodInfo.Invoke()或ConstructorInfo.Invoke()之后,会生成代码以优化重复调用的性能。

  • Microsoft.Extensions.DependencyInjection.DisableDynamicEngine:在从依赖项注入容器检索服务的第二次调用后,将发出代码以提高重复调用的性能。

在大多数 Android 应用程序中,最好禁用此行为。

有关可用功能开关的详细信息,请参阅基类库功能开关文档。

在 .NET 8 中添加。

AndroidBinUtilsPath

包含 Android binutils(如本机链接器 ld 和本机汇编程序 as)的目录路径。 这些工具包含在适用于 Android 工作负载的 .NET 中。

默认值为 $(MonoAndroidBinDirectory)\binutils\bin\。

AndroidBoundExceptionType

一个字符串值,指定当 .NET for Android 提供的类型使用 Java 类型实现 .NET 类型或接口时(例如 Android.Runtime.InputStreamInvoker 和 System.IO.Stream,或 Android.Runtime.JavaDictionary 和 System.Collections.IDictionary),应如何传播异常。

  • Java:原始 Java 异常类型按原样传播。

    Java 意味着,例如 InputStreamInvoker 未正确实现 System.IO.Stream API,因为 Stream.Read() 可能引发 Java.IO.IOException,而不是 System.IO.IOException。

  • System:捕获原始 Java 异常类型,并将其包装到适当的 .NET 异常类型中。

    System 意味着,例如,InputStreamInvoker 正确实现 System.IO.Stream,Stream.Read()不会引发 Java.IO.IOException 实例。 (它可能会引发包含 Java.IO.IOException 作为 Exception.InnerException 值的 System.IO.IOException。)

    默认值为 System。

Android绑定接口包含常量

一个布尔属性,用于确定是否支持接口上的绑定常数,或者是否会使用创建 IMyInterfaceConsts 类的替代方法。

默认值为 True。

安卓绑定接口包含静态和默认接口方法

一个布尔属性,支持接口上的默认成员和静态成员,还是创建一个包含静态成员的同级类(如 abstract class MyInterface)的旧解决方法。

在 .NET 6 中,默认值为 True,在旧版中为 False。

Android绑定接口包含类型

一个布尔属性,用于决定是否支持接口中嵌套的类型,或者使用创建非嵌套类型(如IMyInterfaceMyNestedClass)的替代方法。

在 .NET 6 中,默认值为 True,在旧版中为 False。

Android构建应用程序包

此布尔值指示是否创建包 (.apk) 并为其签名。 将此值设置为 True 等效于使用 SignAndroidPackage 生成目标。

该属性默认为 False。

AndroidBundleConfigurationFile

指定一个文件名,用作配置文件以便在生成 Android 应用程序捆绑包时与bundletool一起使用。 此文件从某些方面控制捆绑包如何生成 APK,例如从哪些维度拆分捆绑包来生成 APK。 适用于 Android 的 .NET 会自动配置其中一些设置,包括要保持未压缩的文件扩展名列表。

仅当 $(AndroidPackageFormat) 设置为 aab 时,此属性才是相关的。

AndroidBundleToolExtraArgs

指定在生成应用程序包时传递给 bundletool 命令的命令行选项。

AndroidClassParser

一个字符串属性,用于控制如何分析 .jar 文件。 可能的值包括:

  • class-parse:使用 class-parse.exe 直接解析 Java 字节码,无需 JVM 的帮助。

  • jar2xml:此值已过时,不再受支持。

AndroidCodegenTarget

一个字符串属性,用于控制代码生成目标 ABI。 可能的值包括:

  • XamarinAndroid:此值已过时,不再受支持。

  • XAJavaInterop1:使用 Java.Interop 进行 JNI 调用。 只能通过 Xamarin.Android 6.1 或更高版本构建和执行使用 XAJavaInterop1 的绑定程序集。 Xamarin.Android 6.1 和更高版本会将 Mono.Android.dll 与此值绑定。

  • JavaInterop1:实验性值,当前是 NativeAOT 运行时的默认值。

默认值为 XAJavaInterop1。

AndroidCreatePackagePerAbi

一个布尔属性,用于确定是否要为每个选定的 Android ABI(例如 .apk)各创建一个 arm64-v8a,而不是仅创建一个支持所有选定 ABI 的 .apk。 $(RuntimeIdentifiers) 中的 RIDs 用于选择这些 ABI;APK 是按 ABI 生成的,而不是按 RID 生成。

另请参阅生成 ABI 特定的 APK 指南。

AndroidCreateProguardMappingFile

一个布尔属性,用于控制在构建过程中是否生成 proguard 映射文件。

将以下内容添加到 csproj 将导致生成文件,并使用 AndroidProguardMappingFile 属性来控制最终映射文件的位置。

<AndroidCreateProguardMappingFile>True</AndroidCreateProguardMappingFile>

生成 .aab 文件时,映射文件会自动包含在包中。 无需手动将其上传到 Google Play 商店。 使用 .apk 文件时,需要手动上传 AndroidProguardMappingFile。

使用 True=r8 时,默认值为 $(AndroidLinkTool)。

AndroidDebugKeyAlgorithm

指定要用于 debug.keystore 的默认算法。 默认值为 RSA。

Android调试密钥有效性

指定要用于 debug.keystore 的默认有效期。 默认值为 10950、30 * 365 或 30 years。

AndroidDebugStoreType

指定用于 debug.keystore 的密钥存储文件格式。 默认为 pkcs12。

AndroidDeviceUserId

允许在来宾帐户或工作帐户下部署和调试应用程序。 该值是从以下 adb 命令获得的 uid 值:

adb shell pm list users

上述命令将返回以下数据:

Users:
	UserInfo{0:Owner:c13} running
	UserInfo{10:Guest:404}

uid 是第一个整数值。 在上述输出中,它们为 0 和 10。

AndroidDexTool

一个有效值为d8的枚举类型属性。 以前,Xamarin.Android 支持此值 dx 。

指示在 .NET for Android 生成过程中使用哪个 Android dex 编译器。 默认值为 d8。 请参阅有关 D8 和 R8 的文档。

AndroidEnableDesugar

用以确定 desugar 是否已启用的布尔值属性。 Android 当前不支持所有 Java 8 功能;默认工具链通过对 desugar 编译器的输出执行称为 javac 的字节码转换,实现新的语言功能。 如果使用 False,则默认值为 $(AndroidDexTool)=dx;如果使用 True$(AndroidDexTool)=,则为 d8。

AndroidEnableFastDeployment

一个布尔属性,用于确定是否启用 快速部署 。 快速部署会在应用程序包之外安装程序集,这可以减少部署和重新生成时间。

默认值适用于 True 调试生成和 False 发布版本。 设置此属性等效于设置逆值 $(EmbedAssembliesIntoApk)。 如果设置了这两个属性, $(EmbedAssembliesIntoApk) 则优先。

Android启用Google Play Store检查

一个布尔属性,允许开发人员禁用以下 Google Play 商店检查:XA1004、XA1005 和 XA1006。 对于目标不是 Google Play 商店并且不想运行这些检查的开发人员来说,禁用这些检查非常有用。

AndroidEnableLegacyCompatibilityAssemblyFixups

一个布尔属性,用于控制未裁剪的生成是否会修改引用程序集,以支持旧版绑定和资源设计器的行为。 这些修改包括添加缺失的接口抽象方法、更新旧版资源设计器引用,以及向较旧的 Xamarin.Android 绑定程序集插入 GC.KeepAlive() 调用。 使用 trimmable 类型映射的裁剪版本不会执行这些兼容性修正,并且将此属性设置为 True 也不会为裁剪版本启用这些修正。

当 为 时,默认值为 ;否则为 。

AndroidEnableMarshalMethods

一个布尔属性,确定是否启用 LLVM 封送方法。 LLVM 封送方法是一种应用启动优化,它使用本机入口点进行 Java native 方法注册。

此属性的默认值为 False。

当 $(PublishReadyToRun) 为 true 时,此属性不能设置为 true。 将这两个属性都设置为 true 会导致生成停止,并显示 XA1049。

在 .NET 8 中添加。

AndroidEnableMultiDex

此布尔属性确定是否将在最终的 .apk 中使用 multi-dex 支持。

该属性默认为 False。

AndroidEnableProfiler

对于 Mono 应用程序,这是属性的 $(EnableDiagnostics) 同义词。 如果是 true,则应用程序中会包含 Mono 诊断组件 libmono-component-diagnostics_tracing.so。

对于 .NET 11 及更高版本的 CoreCLR 应用程序,此属性会启用供 dotnet-trace 和 dotnet-gcdump 等工具使用的 CoreCLR 诊断端口配置;它不会添加 Mono 诊断组件。 NativeAOT 是由 $(PublishAot) 选择的独立运行时,而此属性仅说明受支持的 Android 打包和配置行为。

该属性默认为 False。

AndroidEnableObsoleteOverrideInheritance

一个布尔属性,确定绑定方法是否自动从其所重写的方法继承 [Obsolete] 特性。

.NET 8 中添加了对此属性的支持。

该属性默认为 True。

AndroidEnablePreloadAssemblies

一个布尔属性,用于控制在进程启动时是否加载或不加载应用程序包内绑定的所有托管程序集。

如果设置为 True,在进程启动时,将在调用任何应用程序代码前加载应用程序包内绑定的所有程序集。

如果设置为 False,将仅根据需要加载程序集。 根据需要加载程序集可让应用程序更快地启动,并且也更符合桌面 .NET 语义。 若要查看节省的时间,请将 debug.mono.log 系统属性设置为包含 timing,然后在 Finished loading assemblies: preloaded 中查找 adb logcat 消息。

使用依赖项注入的应用程序或库可能要求此属性为 True(如果它们又要求 AppDomain.CurrentDomain.GetAssemblies() 返回应用程序捆绑包中的所有程序集),即使不需要程序集也是如此。

默认情况下,此值为 False。

AndroidEnableProfiledAot

一个布尔属性,用于确定在预编译期间是否使用 Mono AOT 配置文件。 它适用于使用 Mono 的受支持的 .NET 10 及更早版本项目,并且不会配置 ReadyToRun、MIBC 配置文件、动态 PGO 或 NativeAOT。

配置文件在 @(AndroidAotProfile) 项组。 启用已分析的 AOT 后,会包含默认配置文件,除非 $(AndroidUseDefaultAotProfile) 为 false。 可以使用 @(AndroidAotProfile) 添加自定义配置文件。

当 $(RunAOTCompilation) 为 true 且未设置此属性时,默认值为 true。 因此,对于适用的使用 Mono 的 Release 版本,默认值为 true。

AndroidEnableRestrictToAttributes

一个具有obsolete和disable有效值的枚举样式属性。

设置为 obsolete 时,标记有 Java 注解 androidx.annotation.RestrictTo或 位于未导出 Java 包中的类型和成员,将在 C# 绑定中标记有 [Obsolete]特性。

此属性 [Obsolete] 具有描述性消息,说明 Java 包所有者认为 API 为“内部”,并警告其使用。

此属性还具有自定义警告代码 XAOBS001 ,因此可以独立于“普通”过时 API 将其取消。

设置为 disable 时,API 将正常生成,无需其他属性。 (这与 .NET 8 之前的行为相同。

添加 [Obsolete] 属性而不是自动删除 API 是为了保持与现有包的 API 兼容性。 如果您更希望 删除 具有 @RestrictTo 批注或位于非导出 Java 包中的成员,除了此属性之外,您还可以使用 转化文件 来防止这些类型被绑定:

<remove-node path="//*[@annotated-visibility]" />

.NET 8 中添加了对此属性的支持。

此属性默认设置为 obsolete <

AndroidEnableSGenConcurrent

此布尔属性确定是否使用 Mono 的并发垃圾收集器。

该属性默认为 True。 它适用于受支持的、使用 Mono 的 .NET 10 及更早版本项目,并且不会配置 CoreCLR 或 NativeAOT 垃圾回收器。

AndroidErrorOnCustomJavaObject

此布尔属性确定类型能否实现 Android.Runtime.IJavaObject,而无需同时继承自 Java.Lang.Object 或 Java.Lang.Throwable:

class BadType : IJavaObject {
    public IntPtr Handle {
        get {return IntPtr.Zero;}
    }

    public void Dispose()
    {
    }
}

若为 True,这些类型生成 XA4212 错误;否则,生成 XA4212 警告。

该属性默认为 True。

AndroidExplicitCrunch

不再支持此属性。

AndroidExtraAotOptions

一个字符串属性,允许使用 Mono 的受支持的 .NET 10 及更早版本项目将以分号分隔的独立参数直接传递给 Mono AOT 编译器进程。 仅当启用了 Mono AOT 编译时,才会使用该属性。

通常情况下,此属性应保留为空,但在某些特殊场景中,它可以提供有用的灵活性。

该 $(AndroidExtraAotOptions) 属性不同于相关 $(AndroidAotAdditionalArguments) 属性; $(AndroidExtraAotOptions) 传递独立进程参数,同时 $(AndroidAotAdditionalArguments) 包含在逗号分隔 --aot=... 选项中。

AndroidFastDeploymentType

此属性已在 .NET 9 中删除,不起作用。

AndroidFragmentType

指定在生成布局绑定代码时,所有 <fragment> 布局元素要使用的默认完全限定类型。 默认值为标准 Android Android.App.Fragment 类型。

AndroidGenerateJniMarshalMethods

.NET 11 中删除了此实验性功能。 设置属性不起作用。

安卓生成Jni Marshal方法的附加参数

.NET 11 中删除了此实验性功能。 设置属性不起作用。

AndroidGenerateLayoutBindings

如果设置为 true,则允许生成布局代码隐藏,如果设置为 false,则完全禁止。

默认值为 false。

Android生成资源设计器

默认值为 true。 设置为 false 时,禁用 Resource.designer.cs 的生成。

AndroidHttpClientHandlerType

注意

.NET 11 不支持此属性。 将其从项目文件中删除,并改用 UseNativeHttpHandler 。

AndroidIgnoreAllJniPreload

一个布尔值,如果设置为 true,则免除在应用程序启动时预加载所有本机 JNI 库。 默认情况下,所有此类库将在应用程序启动期间早期由运行时加载,以确保其正确初始化。 但是,在某些情况下,它可能不是所需的行为,此属性允许你有效地禁用它。

在应用程序启动时必须加载的某些框架库不会受到此属性的影响。

另请参阅 @(AndroidNativeLibraryNoJniPreload),它提供了更细粒度的方式来使库免于预加载机制。

AndroidIncludeWrapSh

一个布尔值,指示是否应将 Android 包装器脚本 (wrap.sh) 打包到 APK 中。 默认值为 false,因为包装器脚本可能会严重影响应用程序的启动和运行方式,并且应仅在必要时才包含该脚本,例如,当调试或以其他方式更改应用程序启动/运行时行为时。

使用 生成操作将该脚本添加到项目中, @(AndroidNativeLibrary) 生成操作,因为它与特定体系结构的本机库放在同一目录中,并且必须命名为 wrap.sh。

指定 wrap.sh 脚本路径的最简单方法是将其放在以目标体系结构命名的目录中。 如果每个体系结构只有一个 wrap.sh,则此方法适用:

<AndroidNativeLibrary Include="path/to/arm64-v8a/wrap.sh" />

但是,如果出于不同目的,项目的每个体系结构需要多个 wrap.sh,则此方法将不可行。 在这种情况下,可以使用 Link 的 AndroidNativeLibrary 元数据指定名称:

<AndroidNativeLibrary Include="/path/to/my/arm64-wrap.sh">
  <Link>lib\arm64-v8a\wrap.sh</Link>
</AndroidNativeLibrary>

如果使用 Link 元数据,则其值中指定的路径必须是相对于 APK 根目录的有效本地架构特定的库路径。 路径的格式为 lib\ARCH\wrap.sh,其中 ARCH 可以是以下内容之一:

  • arm64-v8a
  • armeabi-v7a
  • x86_64
  • x86

AndroidIncludeAssetPacksInPackage

此属性控制生成的资产包是否自动包含在最终 .aab文件中。 它默认为 true.

在某些情况下,用户可能想要发布临时版本。 在这些情况下,用户不需要更新资产包。 尤其是资产包的内容未更改时。 此属性允许用户在不需要的情况下跳过资产包。

已在 .NET 9 中添加

AndroidInstallJavaDependencies

默认值在命令行构建中为 true。 当设置为true时,在运行<InstallAndroidDependencies/>目标时启用安装Java SDK。

.NET 9 中添加了对此属性的支持。

AndroidInstrumentation

一个字符串属性,用于指定通过 启动应用程序时要使用的 Android dotnet run 运行器类名。

如果未设置此属性,dotnet run 将根据中间输出中生成的 AndroidManifest.xml 来确定要启动的内容:

  • true如果是$(AndroidUseInstrumentation),则使用第一个<instrumentation/>元素。
  • 否则,首选可启动项 <activity/> ,当应用声明无可启动活动时,将使用第一个 <instrumentation/> 元素。 这使得可以 dotnet run 唯一入口点为 Android.App.Instrumentation 子类的应用,例如 BenchmarkDotNet 主机。

如果应用两者都未声明,构建将失败,并显示 XA1043。 如果 $(AndroidUseInstrumentation) 是 true,但该应用未声明 <instrumentation/>,则生成将失败,并显示 XA1048。

启动插桩程序时,dotnet run 会运行 Instrumentation.Finish();如果插桩程序崩溃,或以 adb shell am instrument -w -r 调用 Result.Canceled,dotnet run 将以非零退出代码退出。 将 false 设置为 $(WaitForExit) 会丢弃 -w,因此 dotnet run 会在插桩启动后立即返回,并且不会报告任何结果。

位于 -- 之后的任何参数都会作为 am instrument 附加参数转发给插桩程序。 表单 KEY=VALUE 的参数变为 -e KEY VALUE,其余所有参数都联接到一 -e args "..." 个额外的参数中:

dotnet run -- --filter *MyBenchmark*

以 arguments.GetString("args") 的形式传递给 Instrumentation.OnCreate(Bundle?)。

.NET 11 中引入。

AndroidJavadocVerbosity

指定在绑定项目中导入 Javadoc 文档时,C#XML 文档注释的“详细”程度。

需要使用 @(JavaSourceJar) 生成操作。

$(AndroidJavadocVerbosity) 属性类似于枚举,其可能值为 full 或 intellisense:

默认值为 intellisense。

AndroidKeyStore

一个布尔值,指示是否应使用自定义签名信息。 默认值是 False,这意味着将使用默认的调试签名密钥来对包进行签名。

Android启动活动

要启动的 Android 活动。

AndroidLinkMode

指定应对 Android 包中包含的程序集执行的链接的类型。 仅在 Android 应用程序项目中使用。 默认值是 SdkOnly。 有效值为:

  • None:不会尝试链接。

  • SdkOnly:仅在基类库上执行链接,而不是用户程序集。

  • Full:将对基类库和用户程序集执行链接操作。

    注意

    使用“完整”这一 AndroidLinkMode 值常会导致应用损坏,尤其是使用放射时。 除非你真正知道在做什么,否则请避免。

<AndroidLinkMode>SdkOnly</AndroidLinkMode>

AndroidLinkResources

true 时,生成系统将链接所有程序集中 Resource.Designer.cs Resource 类的嵌套类型。 使用这些类型的 IL 代码将更新为直接使用值,而不是访问字段。

将嵌套类型剔除可能会对apk大小的减少产生些许影响,并且还有助于提高启动性能。 仅链接“发布”版本。

实验 仅设计用于处理代码,例如

var view = FindViewById(Resources.Ids.foo);

不支持任何其他方案(如反射)。

AndroidLinkSkip

指定不应链接的程序集名称的列表,以分号分隔 (;),且没有文件扩展名。 仅在 Android 应用程序项目中使用。

<AndroidLinkSkip>Assembly1;Assembly2</AndroidLinkSkip>

AndroidLinkTool

枚举样式的属性,有效值为 proguard 或 r8。 指示用于 Java 代码的代码压缩器。 默认值为空字符串,如果 proguard 为 $(AndroidEnableProguard),则为 True。 请参阅有关 D8 和 R8 的文档。

AndroidLintEnabled

一个布尔属性,允许开发人员在打包过程中运行 android lint 工具。

$(AndroidLintEnabled) 为 True 时,使用以下属性:

也可以使用以下生成操作:

请参阅 Lint 帮助,了解有关 Android lint 工具的详细信息。

AndroidLintEnabledIssues

一个字符串属性,是要启用的 lint 问题的逗号分隔列表。

仅在 $(AndroidLintEnabled)=True 时使用。

AndroidLintDisabledIssues

一个字符串属性,是要禁用的 lint 问题的逗号分隔列表。

仅在 $(AndroidLintEnabled)=True 时使用。

AndroidLintCheckIssues

一个字符串属性,是要检查的 lint 问题的逗号分隔列表。

仅在 $(AndroidLintEnabled)=True 时使用。

请注意:我们只会检查这些问题。

AndroidManagedSymbols

此布尔属性控制是否生成序列点,以便可以从 Release 堆栈跟踪中提取文件名和行号信息。

AndroidManifest

指定用于应用 AndroidManifest.xml 的模板的文件名。 在生成期间,将合并任何其他必要的值以生成实际的 AndroidManifest.xml。 $(AndroidManifest) 必须在 /manifest/@package 属性中包含程序包名称。

AndroidManifestMerger

指定用于合并 AndroidManifest.xml 文件的实现。 这是一个枚举样式的属性,其中 legacy 选择原始 C# 实现,manifestmerger.jar 选择 Google 的 Java 实现。

默认值当前为 manifestmerger.jar。 如果要使用旧版本,请将以下内容添加到 csproj

<AndroidManifestMerger>legacy</AndroidManifestMerger>

Google 的合并后使支持xmlns:tools="http://schemas.android.com/tools"成为可能,正如Android 文档中所述。

AndroidManifestMergerExtraArgs

一个字符串属性,用于向 Android 文档工具提供自变量。

如果需要工具的详细输出,可以将以下内容添加到 .csproj。

<AndroidManifestMergerExtraArgs>--log VERBOSE</AndroidManifestMergerExtraArgs>

AndroidManifestType

枚举样式的属性,有效值为 Xamarin 或 GoogleV2。 这控制 InstallAndroidDependencies 目标是确定哪些 Android 包及其版本可以使用和安装。

Xamarin 是 Visual Studio SDK Manager 中的“批准的列表(推荐)”存储库。

GoogleV2 是 Visual Studio SDK Manager 中的“完整列表(不支持)”存储库。

如果$(AndroidManifestType)未设置,则将使用Xamarin。

AndroidManifestSource

一个字符串属性,为以下对象使用的存储库清单指定绝对 URI 或现有本地文件路径 InstallAndroidDependencies 目标。 如果未设置此属性,将使用由 $(AndroidManifestType) 选定的默认仓库清单。

例如:

<AndroidManifestSource>https://example.com/AndroidManifestFeed.xml</AndroidManifestSource>

AndroidManifestPlaceholders

AndroidManifest.xml 的键值替换对列表,采用分号分隔,其中每个对的格式为 key=value。

例如,assemblyName=$(AssemblyName) 的属性值定义一个 ${assemblyName} 占位符,随后该占位符可以出现在 AndroidManifest.xml 中:

<application android:label="${assemblyName}"

这提供了一种将生成过程中的变量插入 AndroidManifest.xml 文件的方法。

AndroidMultiDexClassListExtraArgs

一个字符串属性,允许开发人员在生成 com.android.multidex.MainDexListBuilder 文件时将自变量传递给 multidex.keep。

具体事例:是否在 dx 编译期间发生以下错误。

com.android.dex.DexException: Too many classes in --main-dex-list, main dex capacity exceeded

如果发生此错误,可以向 .csproj 添加以下内容。

<DxExtraArguments>--force-jumbo </DxExtraArguments>
<AndroidMultiDexClassListExtraArgs>--disable-annotation-resolution-workaround</AndroidMultiDexClassListExtraArgs>

这将使 dx 步骤得以成功。

AndroidNdkDirectory

该 $(AndroidNdkDirectory) 属性指定自定义 Android NDK 安装目录。 可以在项目文件或命令行中设置路径:

dotnet build -p:AndroidNdkDirectory=/path/to/android-ndk

如果未设置此属性,.NET for Android 将从已配置的 Android 开发环境中查找 NDK。

Android包格式

枚举样式的属性,有效值为 apk 或 aab。 指示希望将 Android 应用程序打包为 APK 文件还是 Android 应用程序包。 应用程序包是一种新的格式,适用于要在 Google Play 上提交的 Release 版本。 默认值为 apk。

当 $(AndroidPackageFormat) 设置为 aab 时,系统将设置 Android 应用程序包所必需的其他 MSBuild 属性:

.net 6 将弃用此属性。 用户应切换到较新的 AndroidPackageFormats。

AndroidPackageFormats

一个分号分隔的属性,其有效值为 apk 和 aab。 指示希望将 Android 应用程序打包为 APK 文件还是 Android 应用程序包。 应用程序包是一种新的格式,适用于要在 Google Play 上提交的 Release 版本。

生成发布版本时,您可能希望生成一个 aab 和一个 apk,以便可分发到各个商店。

将 AndroidPackageFormats 设置为 aab;apk 将导致生成两者。 将 AndroidPackageFormats 设置为 aab 或 apk 将只生成一个文件。

默认值是aab;apk,仅适用于Release构建。 使用 apk 进行调试更快,但 aab 也支持需要时的快速部署(例如,在测试资产包时)。

AndroidPackageNamingPolicy

枚举样式的属性,用于指定生成的 Java 源代码的 Java 包名称。

唯一支持的值为 LowercaseCrc64。

AndroidPrepareForBuildDependsOn

一个以分号分隔的属性,可用于扩展 Android 生成过程。 添加到此属性的 MSBuild 目标会在生成早期对应用程序和库项目类型执行。 默认情况下,此属性为空。

示例:

<PropertyGroup>
  <AndroidPrepareForBuildDependsOn>MyCustomTarget</AndroidPrepareForBuildDependsOn>
</PropertyGroup>

<Target Name="MyCustomTarget" >
  <Message Text="Running target: 'MyCustomTarget'" Importance="high"  />
</Target>

AndroidProguardMappingFile

指定 r8 的 -printmapping proguard 规则。 这意味着 mapping.txt 文件将在 $(OutputPath) 文件夹中生成。 将包上传到 Google Play 应用商店时,可以使用此文件。

默认情况下,使用 AndroidLinkTool=r8 时会自动生成此文件,并将生成以下文件 $(OutputPath)mapping.txt。

如果不想生成此映射文件,则可以使用 AndroidCreateProguardMappingFile 属性停止创建它。 在项目中添加以下内容

<AndroidCreateProguardMappingFile>False</AndroidCreateProguardMappingFile>

或在命令行上使用 -p:AndroidCreateProguardMappingFile=False。

AndroidD8IgnoreWarnings(忽略警告)

指定将 --map-diagnostics warning info 传递给 d8。 默认值为 True,但可以设置为 False 以强制实施更严格的行为。 有关详细信息, 请参阅 D8 和 R8 源代码 。

在 .NET 8 中添加。

AndroidR8IgnoreWarnings

指定 r8 的 -ignorewarnings proguard 规则。 这允许 r8 继续进行 dex 编译(即使遇到特定的警告)。 默认值为 True,但可以设置为 False 以强制实施更严格的行为。 有关详细信息,请参阅 ProGuard 手册。

从 .NET 8 开始,指定 --map-diagnostics warning info。 有关详细信息, 请参阅 D8 和 R8 源代码 。

AndroidR8JarPath

指向 r8.jar 的路径,可与 r8 dex 编译器和压缩器结合使用。 默认值是.NET for Android 工作负载安装中的路径。 有关详细信息,请参阅 D8 和 R8 相关文档。

AndroidR8ObfuscationMode

一种枚举式属性,用于指定当 $(AndroidLinkTool) 为 r8 时,r8 如何混淆 Java 名称。 支持的值是:

  • private-members保留Java类、接口名称和公共或受保护的成员名称。 可以模糊处理专用成员和包专用成员,并启用 R8 优化。
  • disabled禁用模糊处理,保留所有Java名称,并使用非优化 Android R8 默认值。

此属性无法禁用 R8 代码缩减。

此属性是在 .NET 10 服务版本中引入的。 在 .NET 10 中,默认值为 disabled;在 .NET 11 及更高版本中,默认值为 private-members。

AndroidResgenExtraArgs

指定在处理 Android 资产和资源时传递给 aapt 命令的命令行选项。

AndroidResgenFile

指定要生成的资源文件的名称。 默认模板将其设置为 Resource.designer.cs。

AndroidResourceDesignerClassModifier

指定生成的中间 Resource 类的类修饰符。 有效值为 public 和 internal。

默认情况下,此值为 public.

已在 .NET 9 中添加。

AndroidSdkBuildToolsVersion

Android SDK 生成工具包提供 aapt 和 zipalign 工具等。 可以同时安装多个不同版本的生成工具包。 若要选择用于打包的生成工具包,请检查是否有“首选”生成工具版本。如果有,请使用它;如果没有“首选”版本,请使用版本最高的已安装生成工具包。

$(AndroidSdkBuildToolsVersion) MSBuild 属性包含首选的生成工具版本。 .NET for Android 生成系统在 Xamarin.Android.Common.targets 中提供默认值;如果(例如)最新版 aapt 崩溃而已知旧版 aapt 可用,可以在项目文件中覆盖默认值以选择其他生成工具版本。

Android签名密钥别名 (AndroidSigningKeyAlias)

指定密钥库中密钥的别名。 这是创建密钥存储时使用的 keytool -alias 值。

安卓签名密钥密码

指定密钥存储文件中密钥的密码。 这是在 keytool 要求“输入 $(AndroidSigningKeyAlias) 的密匙密码”时输入的值。

此属性还支持 env: 和 file: 前缀,它们可用于指定包含密码的环境变量或文件。 这些选项提供了一种防止密码显示在生成日志中的方法。

例如,使用名称为 AndroidSigningPassword 的环境变量:

<PropertyGroup>
  <AndroidSigningKeyPass>env:AndroidSigningPassword</AndroidSigningKeyPass>
</PropertyGroup>

要使用位于 C:\Users\user1\AndroidSigningPassword.txt 的文件,请按以下步骤进行:

<PropertyGroup>
  <AndroidSigningKeyPass>file:C:\Users\user1\AndroidSigningPassword.txt</AndroidSigningKeyPass>
</PropertyGroup>

注意

env: 设置为 $(AndroidPackageFormat) 时,不支持 aab 前缀。

AndroidSigningKeyStore

指定由 keytool 创建的密钥存储文件的文件名。 这对应于提供给 keytool -keystore 选项的值。

AndroidSigningStorePass

指定 $(AndroidSigningKeyStore) 的密码。 这是在创建密钥存储文件并要求“输入密钥存储密码:”keytool时为 提供的值。

此属性还支持 env: 和 file: 前缀,它们可用于指定包含密码的环境变量或文件。 这些选项提供了一种防止密码显示在生成日志中的方法。

例如,使用名称为 AndroidSigningPassword 的环境变量:

<PropertyGroup>
  <AndroidSigningStorePass>env:AndroidSigningPassword</AndroidSigningStorePass>
</PropertyGroup>

要使用位于 C:\Users\user1\AndroidSigningPassword.txt 的文件,请按以下步骤进行:

<PropertyGroup>
  <AndroidSigningStorePass>file:C:\Users\user1\AndroidSigningPassword.txt</AndroidSigningStorePass>
</PropertyGroup>

注意

env: 设置为 $(AndroidPackageFormat) 时,不支持 aab 前缀。

AndroidSigningPlatformKey

指定要用于对 apk 进行签名的密钥文件。 这仅在生成 system 应用程序时使用。

AndroidSigningPlatformCert

指定要用于对 apk 进行签名的证书文件。 这仅在生成 system 应用程序时使用。

AndroidStripILAfterAOT

一个布尔属性,指定是否会移除 AOT 编译方法的 方法主体。

默认值为false,不会删除 AOT 编译方法的方法主体。

当设置为true时,默认设置$(AndroidEnableProfiledAot)为false。 这意味着,在受支持的 .NET 8 和 .NET 9 Mono Release 构建版本中——其中 $(RunAOTCompilation) 默认是 true——会为 所有内容 启用 Mono AOT。 这可能会导致应用大小增加。 可以在项目文件中通过显式将 $(AndroidEnableProfiledAot) 设置为 true 来覆盖此行为。

.NET 8 中添加了对此属性的实验性支持,在 .NET 10 中删除。

AndroidStripNativeLibraries

一个布尔属性,指示打包过程从本机共享库(.so 文件)中去除调试符号。

默认值为 false 调试符号(如果有)将在打包时保留。

AndroidSupportedAbis

.NET 6 及更高版本中不再支持此属性。 删除它,并将 $(RuntimeIdentifier) 或 $(RuntimeIdentifiers) 与 .NET RID(而不是 Android ABI 名称)结合使用。

例如,以下.NET 11 设置包括所有受支持的 CoreCLR 体系结构:

<PropertyGroup>
  <RuntimeIdentifiers>android-arm;android-arm64;android-x64</RuntimeIdentifiers>
</PropertyGroup>

AndroidTlsProvider

此属性已过时,不应使用。

AndroidTypeMapImplementation

用于选择类型映射实现的枚举式属性。 有效值为 llvm-ir 和 trimmable。

当 $(PublishAot) 为 true 时,默认值为 trimmable;否则为 llvm-ir。

AndroidUseApkSigner

一个布尔属性,允许开发人员使用 apksigner 工具,而不是 jarsigner。

AndroidUseDefaultAotProfile

一个布尔属性,允许开发人员禁止使用默认 Mono AOT 配置文件。

当 为 时,将使用默认配置文件,除非此属性设置为 。

此属性适用于使用 Mono 的受支持的 .NET 10 及更早版本项目。 它不会为 CoreCLR 选择 MIBC 配置项或动态 PGO。

AndroidUseDesignerAssembly

用于控制构建系统是生成_Microsoft.Android.Resource.Designer.dll文件还是Resource.Designer.cs文件的布尔属性。 这一点的好处是较小的应用程序和更快的启动时间。

默认值在 true .NET 8 中。

作为 NuGet 作者,如果想要保持向后兼容性,建议提供三个版本的程序集。 一个用于 MonoAndroid,一个用于 net6.0-android,一个用于 net8.0-android。 可以使用 Xamarin.Legacy.Sdk 执行此操作。 仅当 Nuget 库项目使用 AndroidResource 项目中的项或通过依赖项时,才需要这样做。

<TargetFrameworks>monoandroid90;net6.0-android;net8.0-android</TargetFrameworks>

或者关闭此设置,直到经典版和 net7.0-android 都被弃用为止。

选择关闭此设置的 .NET 8 项目将无法使用依赖此设置的引用。 如果尝试使用在未启用此功能的项目中启用此功能的程序集,则会出现 XA1034 生成错误。

在 .NET 8 中添加。

AndroidUseInstrumentation

一个布尔属性,指示应用程序通过其 <instrumentation/> 元素而不是 <activity/> 启动,例如测试或 BenchmarkDotNet 主机。

当dotnet run$(AndroidInstrumentation)从生成的adb shell am instrument中解析出AndroidManifest.xml并使用true启动它时,即使该应用还声明了可启动的 activity,也是如此。

当 为 时,默认值为 ;否则为 。 请注意,没有可启动的 <activity/> 的应用无论此属性如何,都会通过其 <instrumentation/> 启动。

.NET 11 中引入。

AndroidUseInterpreter

一个布尔属性,该属性导致 MonoVM .apk 包含 Mono 解释器,而不是普通 JIT。 对于使用 Mono 的 Debug 版本,其默认值为 True;否则为 False。

此属性适用于使用 Mono 的受支持的 .NET 10 及更早版本项目。 它不是 CoreCLR 设置,Android 在 .NET 11 及更高版本中没有解释器。

实验

AndroidUseLegacyVersionCode

一个布尔属性,允许开发人员将 versionCode 计算还原到先前的 Xamarin.Android 8.2 旧行为。 这只能适用于在 Google Play 商店中已发布应用程序的开发人员。 强烈建议使用新 $(AndroidVersionCodePattern) 属性。

AndroidUseManagedDesignTimeResourceGenerator

一个布尔属性,将切换设计时生成以使用受管理资源分析程序,而不是 aapt。

Android使用协商身份验证

一个布尔属性,在 AndroidMessageHandler 中启用对 NTLMv2/Negotiate 身份验证的支持。 默认值为 False。

在 .NET 7 中添加。

AndroidUseSharedRuntime

此属性已过时,不应使用。

安卓版本代码

MSBuild 属性,可以用作 /manifest/@android:versionCode 文件中 AndroidManifest.xml 的替代项。 若要选择加入此功能,还必须启用 <GenerateApplicationManifest>true</GenerateApplicationManifest>。 这将是 .NET 6 中的默认设置。

如果使用 $(AndroidCreatePackagePerAbi) 和 $(AndroidVersionCodePattern),则忽略此属性。

@android:versionCode 是一个必须为每个 Google Play 版本递增的整数值。 有关的要求的详细信息,请参阅/manifest/@android:versionCode。

AndroidVersionCodePattern

一个字符串属性,允许开发人员自定义清单中的 versionCode。 有关决定 versionCode 的信息,请参阅为 APK 创建版本代码。

例如,如果 abi是 armeabi,清单中的 versionCode 为 123,则当 {abi}{versionCode} 为 True 时,1123 将生成 $(AndroidCreatePackagePerAbi) 的 versionCode,否则将生成值 123。 如果 abi 是 x86_64,则清单中的 versionCode 是 44。 当 544 为 True 时,这将生成 $(AndroidCreatePackagePerAbi),否则会生成值 44。

如果我们包含左填充格式字符串 {abi}{versionCode:0000},则会生成 50044,因为我们用 0 在左边填充 versionCode。 此外,也可以使用十进制填充(例如 ), {abi}{versionCode:D4},其作用与前面的示例相同。

由于值必须是整数,因此只支持 0 和 Dx 填充格式字符串。

预定义的键项

  • abi – 插入应用的目标 abi

    • 2 – armeabi-v7a
    • 3 – x86
    • 4 – arm64-v8a
    • 5 – x86_64
  • minSDK – 插入 AndroidManifest.xml 或 11 中支持的最小 Sdk 值(如果未定义)。

  • versionCode – 直接从 Properties\AndroidManifest.xml 使用版本代码。

你可以使用(下文中定义的)$(AndroidVersionCodeProperties) 属性定义自定义项。

默认情况下,值设置为 {abi}{versionCode:D6}。 如果开发人员要保留旧行为,可将 $(AndroidUseLegacyVersionCode) 属性设置为 true,从而替代默认值

安卓版本代码属性

一个字符串属性,允许开发人员定义要与 $(AndroidVersionCodePattern) 配合使用的自定义项。 它们采用 key=value 对的形式。 value 中的所有项都应是整数值。 例如:screen=23;target=$(_AndroidApiLevel)。 正如你所看到的,你可以使用字符串中现有或自定义的 MSBuild 属性。

ApplicationId

MSBuild 属性,可以用作 /manifest/@package 文件中 AndroidManifest.xml 的替代项。 若要选择加入此功能,还必须启用 <GenerateApplicationManifest>true</GenerateApplicationManifest>。 这将是 .NET 6 中的默认设置。

有关的要求的详细信息,请参阅/manifest/@package。

应用程序标题

MSBuild 属性,可以用作 /manifest/application/@android:label 文件中 AndroidManifest.xml 的替代项。 若要选择加入此功能,还必须启用 <GenerateApplicationManifest>true</GenerateApplicationManifest>。 这将是 .NET 6 中的默认设置。

有关的要求的详细信息,请参阅/manifest/application/@android:label。

应用版本

MSBuild 属性,可以用作 /manifest/@android:versionName 文件中 AndroidManifest.xml 的替代项。 若要选择加入此功能,还必须启用 <GenerateApplicationManifest>true</GenerateApplicationManifest>。 这将是 .NET 6 中的默认设置。

有关的要求的详细信息,请参阅/manifest/@android:versionName。

AotAssemblies

一个布尔属性,用于确定程序集是否由 Mono 进行预先(AOT)编译为本地代码并包含在应用程序中。 如果未指定,其有效值如下$(RunAOTCompilation):调试版本为 False,而在受支持的 .NET 10 及更早版本目标框架上使用 Mono 的发布版本为 True。

.NET 7 中已弃用。 对于受支持的、使用 Mono 的 .NET 10 及更早版本项目,请改用 $(RunAOTCompilation) MSBuild 属性。 指定 $(AotAssemblies)(包括将其设置为 false)会发出 XA1029 警告。 将其针对 CoreCLR 或 NativeAOT 设为 true 时,如果未设置 $(RunAOTCompilation)(或其计算结果为 ),就会导致阻止构建的 true 错误,因为默认处理逻辑会将 $(AotAssemblies) 传递给 $(RunAOTCompilation)。

对于 .NET 11 CoreCLR 项目,删除 $(AotAssemblies),不要添加 $(RunAOTCompilation)。 CoreCLR 不使用 Mono AOT 管道。

AProfUtilExtraOptions

在受支持的 .NET 10 及更早版本项目中使用旧版 Mono AOT 分析目标时,要传递给 aprofutil 的额外选项。

BeforeBuildAndroidAssetPacks

在此属性中列出的 MSBuild 目标将在构建 AssetPack 项目之前直接运行。

已在 .NET 9 中添加

BeforeGenerateAndroidManifest

此属性中列出的 MSBuild 目标将在 _GenerateJavaStubs 之前直接运行。

配置

指定要使用的构建配置,例如“调试”或“发布”。 配置属性用于确定其他属性(确定目标行为)的默认值。 其他配置可能会在 IDE 中创建。

默认情况下,Debug 配置将添加 Install 和 SignAndroidPackage 旨在创建更小的 Android 包,这种包的运行需要其他文件和包的支持。

默认 Release 配置将会导致 Install 和 SignAndroidPackage 目标创建独立的 Android 包,无需安装其他任何包或文件即可使用此包。

DebugSymbols

一个布尔值,与 $(DebugType) 属性相结合,确定 Android 包是否可调试。 可调试包包含调试符号,将 //application/@android:debuggable 属性设置为 true,并自动添加 INTERNET 权限,以便调试器可以附加到进程。 如果 DebugSymbols 是 True,并且 DebugType 是空字符串或 Full,则应用程序是可调试的。

DebugType

指定要生成的调试符号的类型作为版本的一部分,它还会影响应用程序是否可调试。 可能的值包括:

  • 完整:生成完整符号。 如果... DebugSymbols MSBuild 属性也为 True,则应用程序包是可调试的。

  • PdbOnly:生成 "PDB" 符号。 应用程序包不可调试。

如果 DebugType 未设置或为空字符串,则 DebugSymbols 属性控制应用程序是否可调试。

设备

指定使用 dotnet run --device <Device> 或与设备交互的 MSBuild 目标(例如 Run、Install 或 Uninstall)时要以哪个 Android 设备或模拟器为目标。

该值必须是返回的完整 adb devices设备序列号或标识符。 例如,如果设备串行是 emulator-5554,则必须使用 -p:Device=emulator-5554。

设置时,此属性用于用AdbTarget值初始化-s "<Device>"属性。

有关设备选择的详细信息,请参阅 .NET SDK 设备选择规范。

诊断地址

由 dotnet-dsrouter 提供的值,例如 127.0.0.1,是 $(DiagnosticConfiguration) 或 DOTNET_DiagnosticPorts 的 IP 地址组成部分。

当此属性为非空,且 $(AndroidEnableProfiler) 未显式设置为 false 时,将隐式启用 Android 诊断功能。 对于 CoreCLR,生成的 TCP 终结点通常保留在回环接口上,并由 dotnet-dsrouter 使用。 对于 Android 模拟器,使用 10.0.2.2 访问开发机器;对于物理设备,使用 127.0.0.1,并通过 dotnet-dsrouter server-server --tcp-server 127.0.0.1:9000 --forward-port Android 启用 Android 端口转发。

默认为 127.0.0.1。

DiagnosticConfiguration

由 dotnet-dsrouter 为 DOTNET_DiagnosticPorts 提供的值,例如:

  • 127.0.0.1:9000,connect,suspend
  • 127.0.0.1:9000,connect,nosuspend

在没有显式配置的情况下启用诊断时,派生的默认值为地址127.0.0.1、端口9000DiagnosticSuspend=false和DiagnosticListenMode=connect。

请注意,如果在命令行中传递给 dotnet build,,字符需要使用 %2c 转义:

dotnet build -c Release -p:DiagnosticConfiguration=127.0.0.1:9000%2cconnect%2csuspend

这会自动设置随应用程序打包的 DOTNET_DiagnosticPorts 环境变量。 在 connect 模式下,Android 运行时连接到已配置的 TCP 端点,并通过 dotnet-dsrouter 将该连接桥接到本地诊断工具。 终结点未经身份验证且未加密,因此将其保留在本地开发接口上。

如果未将 $(AndroidEnableProfiler) 显式设置为 false,则设置此属性或以下任何组件属性时,都会隐式启用 Android 诊断。

DiagnosticListenMode

由 dotnet-dsrouter提供的值,例如 connect,是 $(DiagnosticConfiguration) 或 DOTNET_DiagnosticPorts 的侦听模式组成部分。

当此属性为非空,且 $(AndroidEnableProfiler) 未显式设置为 false 时,将隐式启用 Android 诊断功能。

默认为 connect。

DiagnosticPort

由 dotnet-dsrouter 提供的值,例如 9000,是 $(DiagnosticConfiguration) 或 DOTNET_DiagnosticPorts 的端口组成部分。

当此属性为非空,且 $(AndroidEnableProfiler) 未显式设置为 false 时,将隐式启用 Android 诊断功能。

默认为 9000。

DiagnosticSuspend

由 dotnet-dsrouter 提供的布尔值,例如 true/suspend 或 false/nosuspend,是 $(DiagnosticConfiguration) 或 DOTNET_DiagnosticPorts 的组成部分。

当此属性为非空,且 $(AndroidEnableProfiler) 未显式设置为 false 时,将隐式启用 Android 诊断功能。

默认为 false。

EmbedAssembliesIntoApk (嵌入程序集到APK)

此布尔属性确定应用的程序集是否应嵌入到应用程序包中。

此属性是 $(AndroidEnableFastDeployment) 的逆。 新项目应使用 $(AndroidEnableFastDeployment) 来控制快速部署。 如果设置了这两个属性, $(EmbedAssembliesIntoApk) 则优先。

对于发行版本,该属性应为 True,对于调试版本应为 False。 如果“快速部署”不支持目标设备,则调试版本中可能必须为 True。

启用崩溃报告

一个布尔属性,用于在使用 CoreCLR 或 NativeAOT 运行时时将 DOTNET_EnableCrashReport 环境变量设置为 1。 这将在应用程序启动时启用崩溃报告生成。

此属性默认值为 False,当 True 为 $(UseMonoRuntime) 时,将忽略此属性。

EnableDiagnostics

用于为所选运行时启用诊断的 Android SDK/MSBuild 属性。 它是 Mono 应用程序的同义词 $(AndroidEnableProfiler) 。 对于 CoreCLR,它会启用 dotnet-trace 和 dotnet-gcdump 所使用的诊断端口配置。

$(EnableDiagnostics) 与 CoreCLR 运行时环境变量 DOTNET_EnableDiagnostics不同。 前者由 Android SDK/MSBuild 目标评估;后者在作为环境变量提供时由运行时读取。

该属性默认为 False。

EnableLLVM

一个布尔属性,用于确定在将程序集预先编译为本机代码时 Mono AOT 编译器是否将使用 LLVM。

必须安装 Android NDK 才能生成启用了此属性的项目。

该属性默认为 False。

此属性适用于受支持的、使用 Mono 的 .NET 10 及更早版本项目,并且仅在 $(RunAOTCompilation) 为 True 时影响编译。

将此属性设置为 true CoreCLR 或 NativeAOT 会将此属性重置为 falseXA1044 并停止生成。

EnableMSTestRunner

一个布尔属性,用于为 Android 测试项目启用 MSTest 运行程序 。 当设置为 时, 将通过 而不是 启动应用程序,从而允许通过 Android 的 Instrumentation 协议报告测试结果。

该属性默认为 False。

.NET 11 中引入。

启用Proguard

此布尔属性确定是否在打包过程中运行 proguard 以链接 Java 代码。

该属性默认为 False。

如果为 True,则 @(ProguardConfiguration) 文件将用于控制 proguard 的执行。

EventSourceSupport(事件源支持)

设置为 false 时,将禁用 .NET 的 EventSource 在已精简的 Android 应用程序中的支持。 禁用此功能会阻止 .NET 诊断工具(如 dotnet-counters 正常运行)但受益于应用程序大小减小。

默认情况下,在false模式下,设置为Release,除非$(EnableDiagnostics)或$(AndroidEnableProfiler)已启用。

生成应用程序清单

启用或禁用以下 MSBuild 属性,这些属性会在最终的 AndroidManifest.xml 文件中生成值:

默认值 $(GenerateApplicationManifest) 为 true.

JavaMaximumHeapSize(Java最大堆大小)

指定在作为打包过程一部分生成 .dex 文件时要使用的 java-Xmx 参数值。 如果未指定,则 -Xmx 选项向 java 提供的值为 1G。 我们发现与其他平台相比,Windows 常常要求这样设置。

如果 _CompileDex 目标引发 java.lang.OutOfMemoryError,则指定该属性是必需的。

通过以下更改以自定义值:

<JavaMaximumHeapSize>1G</JavaMaximumHeapSize>

JavaOptions

指定在生成 文件时传递给 .dex 的命令行选项。

Jarsigner时间戳授权证书别名

此属性允许您在密钥存储中为时间戳授权机构指定一个别名。 有关详细信息,请参阅 Java 签名时间戳支持文档。

<PropertyGroup>
    <JarsignerTimestampAuthorityCertificateAlias>Alias</JarsignerTimestampAuthorityCertificateAlias>
</PropertyGroup>

JarsignerTimestampAuthorityUrl

此属性使您能够指定时间戳认证服务的 URL。 这可确保 .apk 签名包含时间戳。 有关详细信息,请参阅 Java 签名时间戳支持文档。

<PropertyGroup>
    <JarsignerTimestampAuthorityUrl>http://example.tsa.url</JarsignerTimestampAuthorityUrl>
</PropertyGroup>

LinkerDumpDependencies

一个布尔属性,允许生成链接器依赖项文件。 可将此文件用作 illinkanalyzer 工具的输入。

名为 linker-dependencies.xml.gz 的依赖项文件已写入项目目录。 在 .NET5/6 上,它写在 obj/<Configuration>/android<ABI>/linked 目录中的链接程序集旁边。

默认值为 False。

MandroidI18n

此 MSBuild 属性已过时,不再受支持。

MauiEnableFullReadyToRun

适用于使用 CoreCLR 且在启用 ReadyToRun 的情况下以 Release 配置构建的 .NET MAUI Android 应用程序的布尔属性。 未设置此属性或将其设置为 false 时,MAUI 使用带默认 MIBC 配置文件的部分 ReadyToRun。 将此属性设置为 true 启用完整的 ReadyToRun。 当false为$(PublishReadyToRun)时,此属性无效。

Full ReadyToRun 会增加应用程序和下载大小,但可能会提高运行时性能,因为预编译了更多方法。

有关 .NET MAUI 中的 CoreCLR 和 ReadyToRun 的详细信息,请参阅 .NET MAUI 中的运行时和编译。

MetricsSupport

设置为 false 时,将禁用已剪裁的 Android 应用程序中的 .NET 指标 支持。 禁用此功能会阻止 API(如 System.Diagnostics.Metrics 正常运行),但会降低应用程序大小。

默认情况下,在false模式下,设置为Release,除非$(EnableDiagnostics)或$(AndroidEnableProfiler)已启用。

MonoAndroidAssetPrefix

通过 AndroidAsset 生成操作指定从文件名开头删除的“路径前缀”。 这是为了允许更改资源所在的位置。

默认值为 Assets。 将此项更改为 assets 以获得 Java 项目结构。

MonoAndroidResourcePrefix

通过 AndroidResource 生成操作指定从文件名开头删除的“路径前缀”。 这是为了允许更改资源所在的位置。

默认值为 Resources。 将此项更改为 res 以获得 Java 项目结构。

MonoSymbolArchive

注意

这是 Xamarin.Android 中的旧版 MSBuild 属性。 在 .NET 6+ 中不可用。

一个布尔属性,控制是否创建 .mSYM 项目供以后与 mono-symbolicate 一起使用,以从版本堆栈跟踪中提取“真实”文件名和行号信息。

对于已启用调试符号的“发布”应用,默认情况下为 True:$(EmbedAssembliesIntoApk) 为 True, $(DebugSymbols) 为 True,并且 $(Optimize) 为 True。

PublishReadyToRun

一个布尔属性,用于控制使用 CoreCLR 时程序集是否编译为 ReadyToRun 格式。 ReadyToRun 程序集包含 MSIL 和本机代码。 这可以提高应用程序启动时间,同时保持 JIT 兼容性,但会增加应用程序和下载大小。

对于使用 CoreCLR 的 Android 应用程序,在 Release 配置中,此属性的默认值为 true;在 Debug 配置中,此属性默认不启用。 使用 Mono 或 NativeAOT 时,ReadyToRun 不适用。

ReadyToRun 需要裁剪。 如果 true 不是 $(PublishTrimmed),.NET for Android 将禁用 PublishReadyToRun 和 $(PublishReadyToRunComposite),并发出警告 XA0119。

ReadyToRun 编译默认采用复合方式。 请参阅 $(PublishReadyToRunComposite)。 .NET MAUI 还使用默认的 MIBC 配置文件来实现部分 ReadyToRun。 有关如何启用完整的 ReadyToRun,请参阅 $(MauiEnableFullReadyToRun)。

有关详细信息,请参阅.NET MAUI中的运行时和编译。

PublishReadyToRunComposite

一个布尔属性,用于控制 ReadyToRun 编译是否将应用程序程序集组合成复合映像。 复合 ReadyToRun 支持跨程序集优化,但可能会增加生成时间。

对于使用 CoreCLR 的 Android 应用程序,当 $(PublishReadyToRun) 为 true 时,此属性默认为 true。 ReadyToRun(包括复合 ReadyToRun)要求将 $(PublishTrimmed) 设置为 true。

RunAOTCompilation

一个布尔属性,用于确定是否使用 Mono AOT 编译器对程序集进行预先编译,并将其包含到使用 Mono 运行时的应用程序中。 对于 Debug 生成,此属性的默认值为 False;对于在受支持的 .NET 10 及更早目标框架上使用 Mono 的 Release 生成,其默认值为 True。

此 MSBuild 属性替换 Xamarin.Android 中的 $(AotAssemblies) MSBuild 属性。 这与 Blazor WASM 使用的属性相同。

此属性未启用 ReadyToRun 或 NativeAOT。 将它设置为 true CoreCLR 或 NativeAOT 会将它重置为 falseXA1044 并停止生成。

对于 CoreCLR,将它设置为 false 也会使生成停止,并报错 XA1044,而不是默默忽略该属性。 从 .NET 11 开始,删除 $(RunAOTCompilation) 并将 $(PublishReadyToRun) 设置为 false 以禁用 ReadyToRun (R2R) AOT 编译。

对于 NativeAOT,仍允许将 $(RunAOTCompilation) 设置为 false。

UseMonoRuntime

一个布尔属性,用于控制 Android 应用程序在受支持的 .NET 10 及更早版本目标中是否使用 Mono 运行时而非 CoreCLR。 将此属性设置为 true 以使用 Mono,或设置为 false 以在这些目标平台上使用 CoreCLR。 设置为 true 时,$(PublishAot) 优先,并为受支持的发布或优化构建选择 NativeAOT。

此属性默认为 true .NET 10 及更早版本中,因此 Android 应用程序使用 Mono。 在 .NET 11 及更高版本中,其默认值为 false,因此 Android 应用程序使用 CoreCLR,并且显式指定 true 值会被拒绝,并显示 NETSDK1242。

有关详细信息,请参阅.NET MAUI中的运行时和编译。

WaitForExit

一个布尔属性,用于控制启动 Android 应用程序时的行为 dotnet run 。

当 $(WaitForExit) 不是 false (默认值)时, dotnet run 将:

  • 启动 Android 应用程序
  • 将logcat的流式输出筛选到应用程序的进程中
  • 等待应用程序退出或用户按 Ctrl+C
  • 按下 Ctrl+C 时强制停止应用程序

当 $(WaitForExit) 是 false时, dotnet run 只需启动应用程序并立即返回,而无需等待应用程序退出或流式传输任何输出。

此属性还控制当应用程序通过其-w启动时,是否会向$(AndroidInstrumentation)传递adb shell am instrument:

$(WaitForExit) 启动 <activity/> 启动 <instrumentation/>
true(默认值) adb shell am start -S -W adb shell am instrument -w -r
false adb shell am start -S adb shell am instrument -r

因为 adb shell am instrument 只会在插桩完成后报告结果,所以如果您需要插桩输出或有意义的退出代码,$(WaitForExit) 就不能是 false。 这对于运行测试或 BenchmarkDotNet 主机等方案很重要,这就是为什么 dotnet test 始终使用默认值。

.NET 11 中引入。