生成项

项目
11/08/2024

生成项控制生成适用于 Android 应用程序或库项目的 .NET 的方式。

它们在 MSBuild ItemGroup 中的项目文件中指定，例如 MyApp.csproj。

注意

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

AndroidAdditionalJavaManifest

<AndroidAdditionalJavaManifest>与 Java 依赖项解析结合使用，用于指定验证依赖项所需的其他 POM 文件。这些通常是 Java 库的 POM 文件的父文件或导入的 POM 文件。

<ItemGroup>
  <AndroidAdditionalJavaManifest Include="mylib-parent.pom" JavaArtifact="com.example:mylib-parent" JavaVersion="1.0.0" />
</ItemGroup>

需要以下 MSBuild 元数据：

%(JavaArtifact)：Java 库的组和项目 ID，其格式 {GroupId}:{ArtifactId}与指定的 POM 文件匹配。
%(JavaVersion)：与指定的 POM 文件匹配的 Java 库的版本。

有关更多详细信息，请参阅 Java 依赖项解析文档。

.NET 9 中引入了此生成操作。

AndroidAsset

支持 Android 资产，即将包含在 Java Android 项目的 assets 文件夹中的文件。

从 .NET 9 开始，@(AndroidAsset)生成操作还支持生成资产包的其他元数据。元数据 %(AndroidAsset.AssetPack) 可用于自动生成该名称的资产包。仅当设置为时$(AndroidPackageFormat).aab，才支持此功能。以下示例将放置并movie3.mp4放入movie2.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最终将出现在 base aab 文件中，而所有其他资产最终将出现在资产包中assets1some.png。

其他元数据仅在适用于 Android 9 及更高版本的 .NET 上受支持。

AndroidAarLibrary

AndroidAarLibrary 生成操作应用于直接引用 .aar 文件。 Xamarin 组件最常使用此生成操作。也就是说，要添加对 .aar 文件的引用，它们是 Google Play 和其他服务正常运行所必需。

包含此生成操作的文件的处理方式类似于库项目中嵌入的资源。 .aar 会被提取到中间目录。然后，任何资产、资源和 .jar 文件都会被添加到相应项组中。

AndroidAotProfile

用于提供 AOT 配置文件，以与配置文件指导的 AOT 一起使用。

还可以通过将 AndroidAotProfile 生成操作设置为包含 AOT 配置文件的文件，在 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

指示布局文件在属性设置为false时 $(AndroidGenerateLayoutBindings)为其生成代码隐藏。在所有其他方面，它都是相同的 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 添加。类似或%(Pack)将转发的<AndroidLibrary>元数据%(Bind)（如果已设置）。默认值为 true。

.NET 9 中引入了此生成操作。

AndroidJavaLibrary

生成操作为 AndroidJavaLibrary 的文件是 Java 存档（.jar 文件），它将包含在最终的 Android 程序包中。

AndroidIgnoredJavaDependency

<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。
- 如果添加了元数据 Bind="false"，则 foo.jar 映射到 EmbeddedReferenceJar。
- 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或 https Maven 存储库的 URL。

项<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>

AndroidPackagingOptionsExclude

一组文件 glob 兼容项，允许将项目从最终包中排除。默认值如下所示

<ItemGroup>
	<AndroidPackagingOptionsExclude Include="DebugProbesKt.bin" />
	<AndroidPackagingOptionsExclude Include="$([MSBuild]::Escape('*.kotlin_*')" />
</ItemGroup>

项可以将文件 blob 字符用于通配符，例如 * 和 ?。但是，这些项必须经过 URL 编码或使用 $([MSBuild]::Escape(''))。因此，MSBuild 不会尝试将它们解释为实际的文件通配符。

例如

<ItemGroup>
	<AndroidPackagingOptionsExclude Include="%2A.foo_%2A" />
  <AndroidPackagingOptionsExclude Include="$([MSBuild]::Escape('*.foo')" />
</ItemGroup>

注意： *将在 ? . 任务中 BuildApk 替换为相应的文件 glob。

如果默认文件 glob 太严格，可以通过将以下内容添加到 csproj 来删除它

<ItemGroup>
	<AndroidPackagingOptionsExclude Remove="$([MSBuild]::Escape('*.kotlin_*')" />
</ItemGroup>

在 .NET 7 中添加。

AndroidPackagingOptionsInclude

一组文件 glob 兼容项，允许从最终包包含项目。默认值如下所示

<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 替换为相应的文件 glob。

在 .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 警告。

EmbeddedJar

在 .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>

EmbeddedNativeLibrary

在适用于 Android 类库或 Java 绑定项目的 .NET 中， 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

生成操作为 LinkDescription 的文件用于控制链接器行为。

ProguardConfiguration

生成操作为 ProguardConfiguration 的文件包含用于控制 proguard 行为的选项。有关此生成操作的更多信息，请参阅 ProGuard。

这些文件将被忽略，除非 $(EnableProguard) MSBuild 属性为 True。

通过

生成项

AndroidAdditionalJavaManifest

AndroidAsset

AndroidAarLibrary

AndroidAotProfile

AndroidAppBundleMetaDataFile

AndroidBoundLayout

AndroidEnvironment

AndroidGradleProject

AndroidJavaLibrary

AndroidIgnoredJavaDependency

AndroidJavaSource

AndroidLibrary

AndroidLintConfig

AndroidManifestOverlay

AndroidInstallModules

AndroidMavenLibrary

AndroidNativeLibrary

项属性名称

AndroidPackagingOptionsExclude

AndroidPackagingOptionsInclude

AndroidResource

内容

EmbeddedJar

EmbeddedNativeLibrary

EmbeddedReferenceJar

JavaSourceJar

LibraryProjectZip

LinkDescription

ProguardConfiguration

反馈

其他资源