ビルド項目

2024-11-11

ビルド項目は、.NET for Android アプリケーションまたはライブラリプロジェクトのビルド方法を制御します。

これらは、MSBuild ItemGroup 内で、MyApp.csproj などのプロジェクトファイル内で指定されます。

Note

.NET for Android では、技術的にはアプリケーションとバインドプロジェクトが区別されないため、ビルド項目は両方で機能します。実際には、個別のアプリケーションプロジェクトとバインドプロジェクトを作成することを強くお勧めします。バインドプロジェクトで主に使用されるビルド項目については、「 MSBuild バインドプロジェクト項目リファレンスガイド」を参照してください。

AndroidAdditionalJavaManifest

<AndroidAdditionalJavaManifest> は、依存関係の検証に必要な追加の POM ファイルを指定するために、 Java 依存関係解決と組み合わせて使用されます。これらは、多くの場合、Java ライブラリの 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

Java Android プロジェクトの assets フォルダーに含まれるファイルである Android アセットをサポートしています。

.NET 9 以降では、 @(AndroidAsset) ビルドアクションでは、 Asset Pack を生成するための追加のメタデータもサポートされています。 %(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 アセットパックを使用する方が効率的な場合があります。このシナリオでは、すべての資産を 1 つの資産パックに含まれるよう更新し、 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 アセットパックに入ります。

追加のメタデータは、.NET for Android 9 以降でのみサポートされています。

AndroidAarLibrary

.aar ファイルを直接参照するには、AndroidAarLibrary のビルドアクションを使用する必要があります。このビルドアクションは、Xamarin コンポーネントで最もよく使用されます。つまり、Google Play やその他のサービスを動作させるために必要な .aar ファイルへの参照を含めるためです。

このビルドアクションを使用するファイルは、ライブラリプロジェクトで見つかる埋め込みリソースと同様に扱われます。 .aar は、中間ディレクトリに抽出されます。次に、すべてのアセット、リソース、.jar ファイルが、適切な項目グループに含まれます。

AndroidAotProfile

ガイド付き AOT のプロファイルでの使用を目的に、AOT プロファイルを提供するために使用されます。

また、Visual Studio から、AOT プロファイルを含むファイルに AndroidAotProfile ビルドアクションを設定して使用することもできます。

AndroidAppBundleMetaDataFile

Android App Bundle にメタデータとして含めるファイルを指定します。フラグ値の形式は <bundle-path>:<physical-file> です。ここで、bundle-path は App Bundle のメタデータディレクトリ内のファイルの場所を示し、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): ビルドする module またはサブプロジェクトの名前。既定値は空です。
%(OutputPath): Gradle プロジェクトのビルド出力パスをオーバーライドするように設定できます。既定値は $(IntermediateOutputPath)gradle/%(ModuleName)%(Configuration)-{Hash} です。
%(CreateAndroidLibrary): 出力 AAR ファイルがプロジェクトに AndroidLibrary として追加されます。 %(Bind)や%(Pack)などの<AndroidLibrary>でサポートされるメタデータは、設定されている場合に転送されます。既定値は true です。

このビルドアクションは.NET 9 で導入されました。

AndroidJavaLibrary

AndroidJavaLibrary のビルドアクションを持つファイルは、最終的な Android パッケージに含まれる Java アーカイブ (.jar ファイル) です。

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 のビルドアクションを持つファイルは、最終的な Android パッケージに含まれる Java ソースコードです。

.NET 7 以降では、プロジェクトディレクトリ内のすべての **\*.java ファイルが AndroidJavaSource のビルドアクションを持ち、"かつ" Assembly ビルドの前にバインドされます。 **\*.java ファイル内に存在する型とメンバーを、C# コードが簡単に使用できるようにします。

この動作を無効にするには、%(AndroidJavaSource.Bind) を False に設定します。

AndroidLibrary

Androidlibrary は、プロジェクトへの .jar と .aar のファイルの含め方を簡略化するための新しいビルドアクションです。

どのプロジェクトでも以下を指定できます。

<ItemGroup>
  <AndroidLibrary Include="foo.jar" />
  <AndroidLibrary Include="bar.aar" />
</ItemGroup>

上記のコードスニペットの結果は、.NET for Android プロジェクトの種類ごとに異なる効果があります。

アプリケーションおよびクラスライブラリプロジェクト:
- 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 ファイルを Manifest Merger ツールに提供できます。このビルドアクションを含むファイルは、メインの AndroidManifest.xml ファイルと、参照からのマニフェストファイルと共に、Manifest Merger ツールに渡されます。これらは、最終的なマニフェストにマージされます。

このビルドアクションを使用すると、ビルド構成に応じて変更や設定をアプリに提供できます。たとえば、デバッグ中にのみ特定のアクセス許可が必要な場合は、オーバーレイを使用してデバッグ時にそのアクセス許可を挿入できます。たとえば、次のようなオーバーレイファイルのコンテンツがあるとします。

<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 アーティファクトを指定できます。Maven アーティファクトは自動的にダウンロードされ、Android 用 .NET バインドプロジェクトに追加されます。これは、Maven でホストされている成果物の Android バインド用の .NET のメンテナンスを簡略化するのに役立ちます。

<!-- Include format is {GroupId}:{ArtifactId} -->
<ItemGroup>
  <AndroidMavenLibrary Include="com.squareup.okhttp3:okhttp" Version="4.9.3" />
</ItemGroup>

次の MSBuild メタデータがサポートされています。

%(Version): %(Include)によって参照される Java ライブラリの必須バージョン。
%(Repository): 使用するオプションの Maven リポジトリ。サポートされている値は、Maven リポジトリへの Central (既定)、 Google、または https URL です。

<AndroidMavenLibrary>項目はAndroidLibraryに変換されるため、%(Bind)や%(Pack)などの<AndroidLibrary>でサポートされるメタデータもサポートされます。

詳細については、 AndroidMavenLibrary のドキュメントを参照してください。

このビルドアクションは.NET 9 で導入されました。

AndroidNativeLibrary

ネイティブライブラリは、そのビルドアクションを AndroidNativeLibrary に設定することで、ビルドに追加されます。

Android では、複数のアプリケーションバイナリインターフェイス (ABI) をサポートしているため、ビルドシステムではネイティブライブラリがどの ABI に対してビルドされているかを知る必要があります。 ABI を指定する方法は 2 つあります。

パス "スニッフィング"。
%(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 – リソースパスを明示的に指定します。ファイルの "別名定義" を許可して、複数の個別のリソース名として使用できるようにします。

<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

.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 ビルドアクションが、Javadoc ドキュメントのコメント含まれるJava ソースコードを含む.jar ファイルで使用されます。

代わりに、Javadoc は、生成されたバインディングソースコード内で C# XML ドキュメントコメントに変換されます。

インポートされた Javadoc の "verbose" または "complete" の程度は、$(AndroidJavadocVerbosity) によって制御されます。

次の MSBuild メタデータがサポートされています。

%(CopyrightFile): インポートされたすべてのドキュメントに追加される Javadoc コンテンツの著作権情報を含むファイルへのパス。
%(UrlPrefix): インポートされたドキュメント内のオンラインドキュメントへのリンクをサポートする URL プレフィックス。
%(UrlStyle): オンラインドキュメントにリンクするときに生成する URL の "スタイル"。現在サポートされているスタイルは、developer.android.com/reference@2020-Nov の 1 つだけです。
%(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

フィードバック

その他のリソース