生成项控制 .NET Android 应用程序或库项目的构建方式。
它们在 MSBuild ItemGroup 中的项目文件中指定,例如 MyApp.csproj。
注意
在 .NET for Android 中,应用程序与绑定项目在技术上没有区别,因此生成项将同时在两者中工作。 在实践中,强烈建议创建单独的应用程序和绑定项目。 在 MSBuild 绑定项目项参考指南 中记录了那些主要用于绑定项目的生成项。
应用程序构件
@(ApplicationArtifact) 包含由打包、签名和发布目标生成的最终应用程序构件文件。 自定义 MSBuild 目标可以使用此项目组来发现 APK 和 Android 应用捆绑包输出,而无需重新计算最终文件名。 适用于 Android 的 .NET 会使用 Android 特有的产物填充此项组,而其他 .NET 移动平台也可以使用相同的项名称来表示其最终应用程序产物。
每个项包括以下元数据:
-
%(ApplicationId):最终合并 AndroidManifest.xml中的包名称。 -
%(ApplicationTitle):最终合并清单中的android:label值。 -
%(ApplicationName):与%(ApplicationTitle)相同的最终清单android:label值。 -
%(ApplicationDisplayVersion):最终合并清单中的android:versionName值。 -
%(ApplicationVersion):最终合并清单中的android:versionCode值。 -
%(PackageFormat):apk或aab。 -
%(Signed):包已签名时为true。 -
%(PackageId):解析后的 Android 包名称,也会以%(ApplicationId)的形式暴露。 -
%(Abi):按 ABI 生成的 APK 输出所对应的 Android ABI。 此元数据仅为每个 ABI APK 设置。
最终合并后的清单是应用程序通用元数据的权威依据。 其值优先于项目属性,例如$(ApplicationId),$(ApplicationTitle)$(ApplicationDisplayVersion)和$(ApplicationVersion)。 这也适用于将 $(GenerateApplicationManifest) 设置为 false 的自定义清单和项目。
基于资源的应用程序标签将原样返回。 例如,值为 ApplicationTitle="@string/app_name" 的 android:label 会生成 @string/app_name 和 ApplicationName="@string/app_name";构建过程不会选择或解析特定区域设置的资源值。
MSBuild 还提供每个项的已知元数据。 例如, %(Filename)%(Extension) 包文件名和 %(FullPath) 完整包路径。
当另一个目标需要直接查询应用程序构件时,请使用 GetApplicationArtifacts 目标。
追加到 $(GetApplicationArtifactsDependsOn) 的目标会在 .NET for Android 填充此项组后运行,因此它们可以在 GetApplicationArtifacts 或 Publish 返回这些项之前,使用附加元数据更新现有项。
例如:
<Target Name="WriteApplicationArtifacts" AfterTargets="Publish">
<WriteLinesToFile
File="$(PublishDir)application-artifacts.txt"
Lines="@(ApplicationArtifact->'%(FullPath)|%(Filename)%(Extension)|%(PackageFormat)|%(Signed)|%(PackageId)|%(Abi)|%(ApplicationTitle)|%(ApplicationDisplayVersion)|%(ApplicationVersion)')"
Overwrite="true" />
</Target>
AndroidAdditionalJavaManifest
<AndroidAdditionalJavaManifest>与 Java 依赖项解析结合使用,用于指定验证依赖项所需的其他 POM 文件。
通常情况下,这些是 Java 库的 POM 文件所引用的父 POM 文件或导入的 POM 文件。
<ItemGroup>
<AndroidAdditionalJavaManifest Include="mylib-parent.pom" JavaArtifact="com.example:mylib-parent" JavaVersion="1.0.0" />
</ItemGroup>
需要以下 MSBuild 元数据:
-
%(JavaArtifact):与指定 POM 文件匹配的 Java 库的组 ID 和制品 ID,格式为{GroupId}:{ArtifactId}。 -
%(JavaVersion):与指定的 POM 文件匹配的 Java 库的版本。
有关更多详细信息, 请参阅 Java 依赖项解析文档 。
.NET 9 中引入了此生成操作。
AndroidAsset
支持 Android 资产,即将包含在 Java Android 项目的 assets 文件夹中的文件。
从 .NET 9 开始,@(AndroidAsset) 生成操作还支持用于生成 资产包的其他元数据。
%(AndroidAsset.AssetPack) 元数据可用于自动生成该名称的资产包。 仅当$(AndroidPackageFormat)设置为.aab时,才支持此功能。 以下示例将movie2.mp4和movie3.mp4分别放入单独的资产包中。
<ItemGroup>
<AndroidAsset Update="Asset/movie.mp4" />
<AndroidAsset Update="Asset/movie2.mp4" AssetPack="assets1" />
<AndroidAsset Update="Asset/movie3.mp4" AssetPack="assets2" />
</ItemGroup>
此功能可用于在应用程序中包括大型文件,通常超过 Google Play 的最大包大小限制。
如果你有大量资产,则使用 base 资产包可能更有效。
在此方案中,将所有资产更新为位于单个资产包中,然后使用 AssetPack="base" 元数据声明哪些特定资产最终出现在基本 aab 文件中。 使用此通配符可将大多数资产移到资产包中。
<ItemGroup>
<AndroidAsset Update="Assets/*" AssetPack="assets1" />
<AndroidAsset Update="Assets/movie.mp4" AssetPack="base" />
<AndroidAsset Update="Assets/some.png" AssetPack="base" />
</ItemGroup>
在此示例中,movie.mp4和some.png将最终出现在base aab 文件中,而所有其他资产将最终出现在assets1资产包中。
其他元数据仅在适用于 Android 9 及更高版本的 .NET 上受支持。
Android AAR 库
AndroidAarLibrary 的构建操作应用于直接引用 .aar 文件。 Xamarin 组件最常使用此生成操作。 也就是说,要添加对 .aar 文件的引用,它们是 Google Play 和其他服务正常运行所必需。
包含此生成操作的文件的处理方式类似于库项目中嵌入的资源。
.aar 会被提取到中间目录。 然后,任何资产、资源和 .jar 文件都会被添加到相应项组中。
AndroidAotProfile
用于在使用 Mono 且受支持的 .NET 10 及更早版本的项目中为已分析的 AOT 提供 Mono AOT 配置文件。
此物品会在以下情况下消耗
$(AndroidEnableProfiledAot) 是 true。 它不是 MIBC 配置文件或动态 PGO 输入。
还可以通过在包含 Mono AOT 配置文件的文件上设置 AndroidAotProfile 生成操作,从 Visual Studio 中使用它。
AndroidAppBundleMetaDataFile
指定将作为元数据包含在 Android 应用程序包中的文件。
标记值的格式是 <bundle-path>:<physical-file>,其中 bundle-path 表示应用程序包元数据目录内的文件位置,physical-file 是包含要存储的原始数据的现有文件。
<ItemGroup>
<AndroidAppBundleMetaDataFile
Include="com.android.tools.build.obfuscation/proguard.map:$(OutputPath)mapping.txt"
/>
</ItemGroup>
有关更多详细信息,请参阅 bundletool 文档。
AndroidBoundLayout
指示在 $(AndroidGenerateLayoutBindings) 属性设置为 false 的情况下,为布局文件 生成代码隐藏。 在其他所有方面,它与AndroidResource相同。
此操作仅适用于布局文件:
<AndroidBoundLayout Include="Resources\layout\Main.axml" />
AndroidEnvironment(安卓环境)
生成操作为 AndroidEnvironment 的文件用于在过程启动期间初始化环境变量和系统属性。
AndroidEnvironment 生成操作可能会应用于多个文件,并且它们将以无特定顺序进行评估(因此,不要在不同文件中指定相同的环境变量或系统属性)。
AndroidGradleProject
<AndroidGradleProject> 可用于生成和使用在 Android Studio 或 elsewehere 中创建的 Android Gradle 项目的输出。
元数据 Include 应指向将用于生成项目的顶级 build.gradle 或 build.gradle.kts 文件。 这可在 Gradle 项目的根目录中找到,该目录还应包含 gradlew 包装器脚本。
<ItemGroup>
<AndroidGradleProject Include="path/to/project/build.gradle.kts" ModuleName="mylibrary" />
</ItemGroup>
支持以下 MSBuild 元数据:
-
%(Configuration):用于生成或组装指定的项目或项目模块的配置的名称。 默认值为Release。 -
%(ModuleName):应生成的模块或子项目的名称。 默认值为空。 -
%(OutputPath):可以设置为替代 Gradle 项目的生成输出路径。 默认值为$(IntermediateOutputPath)gradle/%(ModuleName)%(Configuration)-{Hash}。 -
%(CreateAndroidLibrary):输出 AAR 文件将作为AndroidLibrary添加到项目。 如果已设置,<AndroidLibrary>支持的元数据(如%(Bind)或%(Pack))将被转发。 默认值为true。
.NET 9 中引入了此生成操作。
AndroidJavaLibrary
生成操作为 AndroidJavaLibrary 的文件是 Java 存档(.jar 文件),它将包含在最终的 Android 程序包中。
Android忽略Java依赖
<AndroidIgnoredJavaDependency>与 Java 依赖项解析结合使用。
它用于指定应忽略的 Java 依赖项。 如果依赖项将以 Java 依赖项解析无法检测到的方式实现,则可以使用此方法。
<!-- Include format is {GroupId}:{ArtifactId} -->
<ItemGroup>
<AndroidIgnoredJavaDependency Include="com.google.errorprone:error_prone_annotations" Version="2.15.0" />
</ItemGroup>
需要以下 MSBuild 元数据:
-
%(Version):与指定%(Include)库匹配的 Java 库的版本。
有关更多详细信息, 请参阅 Java 依赖项解析文档 。
.NET 9 中引入了此生成操作。
AndroidJavaSource
生成操作为 AndroidJavaSource 的文件是 Java 源代码,将包含在最终的 Android 程序包中。
从 .NET 7 开始,项目目录中的所有 **\*.java 文件都会自动具有 AndroidJavaSource 的生成操作, 和 将在程序集生成之前绑定。 允许 C# 代码轻松使用 **\*.java 文件中存在的类型和成员。
将 %(AndroidJavaSource.Bind) 设置为 False 可禁用此行为。
AndroidLibrary
AndroidLibrary 是一种新的生成操作,用于简化 .jar 和 .aar 文件包含到项目中的方式。
任何项目都可以指定:
<ItemGroup>
<AndroidLibrary Include="foo.jar" />
<AndroidLibrary Include="bar.aar" />
</ItemGroup>
上述代码片段的结果对 Android 项目类型的每个 .NET 有不同的效果:
- 应用程序和类库项目:
-
foo.jar映射到 AndroidJavaLibrary。 -
bar.aar映射到 AndroidAarLibrary。
-
- Java 绑定项目:
-
foo.jar映射到 EmbeddedJar。 - 如果添加了元数据
foo.jar,则 映射到 EmbeddedReferenceJarBind="false"。 -
bar.aar映射到 LibraryProjectZip。
-
这种简化意味着可以在任何地方使用 AndroidLibrary。
AndroidLintConfig
应将“AndroidLintConfig”生成操作与 生成属性结合使用
$(AndroidLintEnabled) 属性。 使用此生成操作的文件将被合并并传递给 Android lint 工具。 它们应当是包含要启用和禁用的测试的信息的 XML 文件。
有关详细信息,请参阅 lint 文档。
AndroidManifestOverlay
AndroidManifestOverlay 生成操作可用于向清单合并器工具提供 AndroidManifest.xml 文件。
具有此生成操作的文件将与主 AndroidManifest.xml 文件以及引用中的清单文件一起传递到清单合并器。 然后,这些文件将合并到最终清单中。
可以使用此生成操作向应用提供更改和设置,具体取决于你的生成配置。 例如,如果仅在调试时需要具有特定权限,则可以在调试时使用覆盖来注入该权限。 例如,假设以下是叠加文件的内容:
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
<uses-permission android:name="android.permission.CAMERA" />
</manifest>
可以使用以下步骤为调试版本添加清单覆盖:
<ItemGroup>
<AndroidManifestOverlay Include="DebugPermissions.xml" Condition=" '$(Configuration)' == 'Debug' " />
</ItemGroup>
AndroidInstallModules
指定在安装应用程序包时通过 bundletool 命令安装的模块。
AndroidMavenLibrary
<AndroidMavenLibrary> 允许指定一个 Maven 构件,该构件将自动下载并添加到 .NET for Android 绑定项目中。
这有助于简化对 Maven 中托管制品的 .NET for Android 绑定的维护。
<!-- Include format is {GroupId}:{ArtifactId} -->
<ItemGroup>
<AndroidMavenLibrary Include="com.squareup.okhttp3:okhttp" Version="4.9.3" />
</ItemGroup>
支持以下 MSBuild 元数据:
-
%(Version):由%(Include)引用的 Java 库的必需版本。 -
%(Repository):要使用的可选 Maven 存储库。 支持的值为Central(默认值),Google或httpsMaven 存储库的 URL。 -
%(AllowInsecureHttp):可选的布尔值。 如果%(Repository)为http://URL,则必须将其设置为true允许不安全的连接。 默认值为false. 强烈建议使用 HTTPS 实现供应链安全性。
<AndroidMavenLibrary>项目被翻译为AndroidLibrary,因此由<AndroidLibrary>支持的任何元数据,例如%(Bind)或%(Pack),也都支持。
有关更多详细信息, 请参阅 AndroidMavenLibrary 文档 。
.NET 9 中引入了此生成操作。
AndroidNativeLibrary
通过将 本机库 的生成操作设置为 AndroidNativeLibrary,将它们添加到生成中。
请注意,由于 Android 支持多个应用程序二进制接口 (ABI),因此生成系统必须知道本机库是为哪个 ABI 生成的。 可通过两种方式指定 ABI:
- 路径“探查”。
- 使用
%(Abi)项元数据。
通过路径探查,本机库的父目录名称用于指定库的目标 ABI。 因此,如果将 lib/armeabi-v7a/libfoo.so 添加到版本中,则 ABI 将被“探查”为 armeabi-v7a。
项属性名称
Abi – 指定本地库的 ABI。
<ItemGroup>
<AndroidNativeLibrary Include="path/to/libfoo.so">
<Abi>armeabi-v7a</Abi>
</AndroidNativeLibrary>
</ItemGroup>
AndroidNativeLibraryNoJniPreload
此项目组中包含的每个本机库都将不受 JNI 库预加载机制的约束。 默认情况下,所有此类库将在应用程序启动期间早期由运行时加载,以确保其正确初始化。 但在某些情况下,这可能不是期望的行为,此项组允许逐个地从此过程中排除库。
如果此项目组中包含某些必须在应用程序启动时加载的框架库,则不会影响这些库。
另请参阅 $(AndroidIgnoreAllJniPreload)
AndroidPackagingOptionsExclude(Android 打包选项排除)
一组支持文件通配模式的项,可用于从最终包中排除项。 默认值如下所示
<ItemGroup>
<AndroidPackagingOptionsExclude Include="DebugProbesKt.bin" />
<AndroidPackagingOptionsExclude Include="$([MSBuild]::Escape('*.kotlin*'))" />
<AndroidPackagingOptionsExclude Include="$([MSBuild]::Escape('*.jar$'))" />
<AndroidPackagingOptionsExclude Include="$([MSBuild]::Escape('*.knm$'))" />
<AndroidPackagingOptionsExclude Include="$([MSBuild]::Escape('^(|root/)[^/]+Main/default/(manifest|linkdata/*)$'))" />
<AndroidPackagingOptionsExclude Include="$([MSBuild]::Escape('^(|root/)R.txt$'))" />
<AndroidPackagingOptionsExclude Include="$([MSBuild]::Escape('^(|root/)proguard.txt$'))" />
<AndroidPackagingOptionsExclude Include="$([MSBuild]::Escape('^(|root/)META-INF/kotlin-project-structure-metadata.json$'))" />
<AndroidPackagingOptionsExclude Include="$([MSBuild]::Escape('^(|root/)META-INF/proguard/*$'))" />
<AndroidPackagingOptionsExclude Include="$([MSBuild]::Escape('^(|root/)META-INF/com.android.tools/proguard/*$'))" />
<AndroidPackagingOptionsExclude Include="$([MSBuild]::Escape('^(|root/)META-INF/com.android.tools/r8*/*$'))" />
<AndroidPackagingOptionsExclude Include="$([MSBuild]::Escape('^(|root/)META-INF/com/android/build/gradle/aar-metadata.properties$'))" />
</ItemGroup>
项目可以使用文件 blob 字符作为通配符,例如 * 和 ?。
但是,这些项必须经过 URL 编码或使用 $([MSBuild]::Escape(''))。
因此,MSBuild 不会尝试将它们解释为实际的文件通配符。
例如
<ItemGroup>
<AndroidPackagingOptionsExclude Include="%2A.foo_%2A" />
<AndroidPackagingOptionsExclude Include="$([MSBuild]::Escape('*.foo')" />
</ItemGroup>
注意:*、? 和 . 将在 BuildApk 任务中替换为相应的文件通配模式。
如果默认文件通配模式限制过多,可以通过向 csproj 添加以下内容将其移除
<ItemGroup>
<AndroidPackagingOptionsExclude Remove="$([MSBuild]::Escape('*.kotlin_*')" />
</ItemGroup>
在 .NET 7 中添加。
AndroidPackagingOptionsInclude
一组支持文件通配模式的项,可用于指定最终包中要包含的项。 默认值如下所示
<ItemGroup>
<AndroidPackagingOptionsInclude Include="$([MSBuild]::Escape('*.kotlin_builtins')" />
</ItemGroup>
项目可以使用文件 blob 字符作为通配符,例如 * 和 ?。
但是,这些项必须使用 URL 编码或'$([MSBuild]::Escape(''))'。
因此,MSBuild 不会尝试将它们解释为实际的文件通配符。
例如
<ItemGroup>
<AndroidPackagingOptionsInclude Include="%2A.foo_%2A" />
<AndroidPackagingOptionsInclude Include="$([MSBuild]::Escape('*.foo')" />
</ItemGroup>
注意:*、? 和 . 将在 BuildApk 任务中替换为相应的文件通配模式。
已在 .NET 9 中添加。
AndroidResource
生成操作为 AndroidResource 的所有文件都将在生成过程中编译为 Android 资源,并可通过 $(AndroidResgenFile) 访问。
<ItemGroup>
<AndroidResource Include="Resources\values\strings.xml" />
</ItemGroup>
更高级的用户可能希望在不同的配置中使用不同的资源,但使用相同的有效路径。 为此,可以使用多个资源目录并使具有相同相对路径的文件放在这些不同的目录中,以及使用 MSBuild 条件来有条件地在不同配置中包括不同文件。 例如:
<ItemGroup Condition=" '$(Configuration)' != 'Debug' ">
<AndroidResource Include="Resources\values\strings.xml" />
</ItemGroup>
<ItemGroup Condition=" '$(Configuration)' == 'Debug' ">
<AndroidResource Include="Resources-Debug\values\strings.xml"/>
</ItemGroup>
<PropertyGroup>
<MonoAndroidResourcePrefix>Resources;Resources-Debug</MonoAndroidResourcePrefix>
</PropertyGroup>
LogicalName – 显式指定资源路径。 允许使用“aliasing”文件,以便它们可用作多个不同的资源名称。
<ItemGroup Condition="'$(Configuration)'!='Debug'">
<AndroidResource Include="Resources/values/strings.xml"/>
</ItemGroup>
<ItemGroup Condition="'$(Configuration)'=='Debug'">
<AndroidResource Include="Resources-Debug/values/strings.xml">
<LogicalName>values/strings.xml</LogicalName>
</AndroidResource>
</ItemGroup>
内容
不支持正常的 Content 生成操作(因为我们还未想出如何在没有成本可能昂贵的首次运行步骤的情况下支持它)。
尝试使用 @(Content) 生成操作将导致 XA0101 警告。
嵌入式JAR
在 .NET for Android 绑定项目中, EmbeddedJar 生成操作将 Java/Kotlin 库绑定到库,并将 .jar 该文件嵌入库中。 当 .NET for Android 应用程序项目使用库时,它将有权从 C# 访问 Java/Kotlin API,并在最终的 Android 应用程序中包括 Java/Kotlin 代码。
应改用 AndroidLibrary 生成操作作为替代方法,例如:
<Project>
<ItemGroup>
<AndroidLibrary Include="Library.jar" />
</ItemGroup>
</Project>
嵌入式本地库
在 .NET for Android 类库或 Java 绑定项目中,EmbeddedNativeLibrary 生成操作将本机库(例如 lib/armeabi-v7a/libfoo.so)打包到该库中。 当 .NET for Android 应用程序使用库时, libfoo.so 该文件将包含在最终的 Android 应用程序中。
可以使用 AndroidNativeLibrary 生成操作作为替代方法。
EmbeddedReferenceJar
在 .NET for Android 绑定项目中,EmbeddedReferenceJar 生成操作将.jar文件嵌入库中,但不会像 EmbeddedJar 那样创建 C# 绑定。 当 .NET for Android 应用程序项目使用库时,它将在最终的 Android 应用程序中包括 Java/Kotlin 代码。
你可以使用 AndroidLibrary 生成操作作为替代,例如 <AndroidLibrary Include="..." Bind="false" />:
<Project>
<ItemGroup>
<!-- A .jar file to bind & embed -->
<AndroidLibrary Include="Library.jar" />
<!-- A .jar file to only embed -->
<AndroidLibrary Include="Dependency.jar" Bind="false" />
</ItemGroup>
</Project>
JavaSourceJar
在 .NET for Android 绑定项目中, JavaSourceJar 生成操作用于 .jar 包含 Java 源代码的文件,其中包含 Javadoc 文档注释。
Javadoc 将改为在生成的绑定源代码中转换为 C# XML 文档注释。
$(AndroidJavadocVerbosity) 控制导入的 Javadoc 的“详细程度”或“完整性”。
支持以下 MSBuild 元数据:
%(CopyrightFile):包含 Javadoc 内容版权信息的文件的路径,这些信息将追加到所有导入的文档中。%(UrlPrefix):URL 前缀,用于支持链接到导入文档中的联机文档。%(UrlStyle):链接到联机文档时要生成的 URL 的“样式”。 当前仅支持一种样式:developer.android.com/reference@2020-Nov。%(DocRootUrl):用于代替导入文档中所有{@docroot}实例的 URL 前缀。
LibraryProjectZip
LibraryProjectZip 生成操作绑定 Java/Kotlin 库,并将.zip或.aar文件嵌入库中。 当 .NET for Android 应用程序项目使用库时,它将有权从 C# 访问 Java/Kotlin API,并在最终的 Android 应用程序中包括 Java/Kotlin 代码。
链接描述
生成操作为 LinkDescription 的文件用于控制链接器行为。
ProguardConfiguration
生成操作为 ProguardConfiguration 的文件包含用于控制 proguard 行为的选项。 有关此生成操作的更多信息,请参阅 ProGuard。
这些文件会被忽略,除非特定条件满足。
$(EnableProguard) MSBuild 属性为 True。
运行时环境变量
@(RuntimeEnvironmentVariable) 条目允许在运行时通过 dotnet run -e 将环境变量传递给 Android 应用程序。 例如:
dotnet run -e DOTNET_RUN_FOO=TestValue123 -e DOTNET_RUN_BAR=AnotherValue456
使用dotnet run -e NAME=VALUE时,.NET SDK 会自动填充这些项,并在生成过程中包含在生成的环境文件中。 每个项 %(Identity) 都是变量名称,也是 %(Value) 变量值。
<ItemGroup>
<RuntimeEnvironmentVariable Include="DOTNET_RUN_FOO" Value="TestValue123" />
</ItemGroup>
此功能仅适用于 Android 应用程序项目,并且需要支持项目功能的.NET SDKRuntimeEnvironmentVariableSupport。
.NET 10.0.300 SDK 和 .NET 11 中引入了此生成项。