Condividi tramite

Elementi di compilazione

  • Articolo

Gli elementi di compilazione controllano la modalità di compilazione di un progetto di libreria o applicazione .NET per Android.

AndroidAdditionalJavaManifest

<AndroidAdditionalJavaManifest> viene usato insieme alla risoluzione delle dipendenze Java.

Viene usato per specificare file POM aggiuntivi che saranno necessari per verificare le dipendenze. Si tratta spesso di file POM padre o importati a cui fa riferimento il file POM di una libreria Java.

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

Sono necessari i metadati MSBuild seguenti:

  • %(JavaArtifact): gruppo e ID artefatto della libreria Java corrispondente al file POM specificato nel formato {GroupId}:{ArtifactId}.
  • %(JavaVersion): versione della libreria Java corrispondente al file POM specificato.

Per altri dettagli, vedere la documentazione relativa alla risoluzione delle dipendenze Java.

Questa azione di compilazione è stata introdotta in .NET 9.

AndroidAsset

Supporta Gli asset Android, i file che verrebbero inclusi nella assets cartella in un progetto Android Java.

A partire da .NET 9, l'azione @(AndroidAsset) di compilazione supporta anche metadati aggiuntivi per la generazione di Pacchetti di asset. I %(AndroidAsset.AssetPack) metadati possono essere usati per generare automaticamente un asset pack di tale nome. Questa funzionalità è supportata solo quando $(AndroidPackageFormat) è impostato su .aab. Nell'esempio seguente verranno inseriti movie2.mp4 e movie3.mp4 in pacchetti di asset separati.

<ItemGroup>
   <AndroidAsset Update="Asset/movie.mp4" />
   <AndroidAsset Update="Asset/movie2.mp4" AssetPack="assets1" />
   <AndroidAsset Update="Asset/movie3.mp4" AssetPack="assets2" />
</ItemGroup>

Questa funzionalità può essere usata per includere file di grandi dimensioni nell'applicazione che normalmente superano i limiti massimi di dimensioni del pacchetto di Google Play.

Se si dispone di un numero elevato di asset, potrebbe essere più efficiente usare il base pacchetto di asset. In questo scenario si aggiornano tutti gli asset in un singolo asset pack, quindi si usano i AssetPack="base" metadati per dichiarare quali asset specifici finiscono nel file aab di base. Con questo è possibile usare i caratteri jolly per spostare la maggior parte degli asset nel pacchetto di asset.

<ItemGroup>
   <AndroidAsset Update="Assets/*" AssetPack="assets1" />
   <AndroidAsset Update="Assets/movie.mp4" AssetPack="base" />
   <AndroidAsset Update="Assets/some.png" AssetPack="base" />
</ItemGroup>

In questo esempio movie.mp4 , e some.png finirà nel base file aab, mentre tutti gli altri asset finiranno nel assets1 pacchetto di asset.

I metadati aggiuntivi sono supportati solo in .NET per Android 9 e versioni successive.

AndroidAarLibrary

L'azione Di compilazione di AndroidAarLibrary deve essere usata per fare riferimento .aar direttamente ai file. Questa azione di compilazione verrà usata più comunemente dai componenti di Xamarin, In nome di includere riferimenti ai .aar file necessari per il funzionamento di Google Play e di altri servizi.

I file con questa azione di compilazione verranno trattati in modo analogo alle risorse incorporate disponibili nei progetti di libreria. L'oggetto .aar verrà estratto nella directory intermedia. Tutti gli asset, le risorse e .jar i file verranno quindi inclusi nei gruppi di elementi appropriati.

AndroidAotProfile

Usato per fornire un profilo AOT, da usare con AOT guidato dal profilo.

Può essere usato anche da Visual Studio impostando l'azione AndroidAotProfile di compilazione su un file contenente un profilo AOT.

AndroidAppBundleMetaDataFile

Specifica un file che verrà incluso come metadati nel bundle di app Android. Il formato del valore del flag indica <bundle-path>:<physical-file> bundle-path il percorso del file all'interno della directory dei metadati del bundle dell'app ed physical-file è un file esistente contenente i dati non elaborati da archiviare.

<ItemGroup>
  <AndroidAppBundleMetaDataFile
    Include="com.android.tools.build.obfuscation/proguard.map:$(OutputPath)mapping.txt"
  />
</ItemGroup>

Per altri dettagli, vedere la documentazione di bundletool .

AndroidBoundLayout

Indica che il file di layout deve essere generato dal code-behind nel caso in cui la $(AndroidGenerateLayoutBindings) proprietà sia impostata su false. In tutti gli altri aspetti è identico a AndroidResource.

Questa azione può essere usata solo con i file di layout:

<AndroidBoundLayout Include="Resources\layout\Main.axml" />

AndroidEnvironment

I file con un'azione di compilazione AndroidEnvironment vengono usati per inizializzare le variabili di ambiente e le proprietà di sistema durante l'avvio del processo. L'azione di compilazione AndroidEnvironment può essere applicata a più file che verranno valutati in ordine casuale, quindi non specificare la stessa variabile di ambiente o proprietà di sistema in più file.

AndroidJavaLibrary

I file con un'azione di compilazione di AndroidJavaLibrary sono Archivi Java ( .jar file) che verranno inclusi nel pacchetto Android finale.

AndroidIgnoredJavaDependency

<AndroidIgnoredJavaDependency> viene usato insieme alla risoluzione delle dipendenze Java.

Viene usato per specificare una dipendenza Java che deve essere ignorata. Questa operazione può essere usata se una dipendenza verrà soddisfatta in modo che la risoluzione delle dipendenze Java non possa rilevare.

<!-- Include format is {GroupId}:{ArtifactId} -->
<ItemGroup>
  <AndroidIgnoredJavaDependency Include="com.google.errorprone:error_prone_annotations" Version="2.15.0" />
</ItemGroup>

Sono necessari i metadati MSBuild seguenti:

  • %(Version): versione della libreria Java corrispondente all'oggetto specificato %(Include).

Per altri dettagli, vedere la documentazione relativa alla risoluzione delle dipendenze Java.

Questa azione di compilazione è stata introdotta in .NET 9.

AndroidJavaSource

I file con un'azione di compilazione di AndroidJavaSource sono codice sorgente Java che verrà incluso nel pacchetto Android finale.

A partire da .NET 7, tutti i **\*.java file all'interno della directory del progetto hanno automaticamente un'azione di compilazione di AndroidJavaSourcee verranno associati prima della compilazione dell'assembly. Consente al codice C# di usare facilmente tipi e membri presenti all'interno dei **\*.java file.

Impostare %(AndroidJavaSource.Bind) su False per disabilitare questo comportamento.

AndroidLibrary

AndroidLibrary è una nuova azione di compilazione per semplificare la modalità .jar e .aar i file inclusi nei progetti.

Qualsiasi progetto può specificare:

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

Il risultato del frammento di codice precedente ha un effetto diverso per ogni tipo di progetto .NET per Android:

Questa semplificazione significa che è possibile usare AndroidLibrary ovunque.

AndroidLintConfig

L'azione di compilazione 'AndroidLintConfig' deve essere usata insieme a Proprietà $(AndroidLintEnabled). I file con questa azione di compilazione verranno uniti e passati allo strumento lint di Android. Devono essere file XML contenenti informazioni sui test per abilitare e disabilitare.

Vedere la documentazione di Lint per maggiori dettagli.

AndroidManifestOverlay

L'azione AndroidManifestOverlay di compilazione può essere usata per fornire AndroidManifest.xml file allo strumento Unione manifesto. I file con questa azione di compilazione verranno passati alla fusione del manifesto insieme ai file principali AndroidManifest.xml e ai file manifesto dei riferimenti. Questi verranno quindi uniti nel manifesto finale.

È possibile usare questa azione di compilazione per fornire modifiche e impostazioni all'app a seconda della configurazione di compilazione. Ad esempio, se è necessario disporre di un'autorizzazione specifica solo durante il debug, è possibile usare la sovrimpressione per inserire tale autorizzazione durante il debug. Ad esempio, dato il contenuto del file di sovrimpressione seguente:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
  <uses-permission android:name="android.permission.CAMERA" />
</manifest>

Per aggiungere una sovrimpressione del manifesto per una compilazione di debug, è possibile usare quanto segue:

<ItemGroup>
  <AndroidManifestOverlay Include="DebugPermissions.xml" Condition=" '$(Configuration)' == 'Debug' " />
</ItemGroup>

AndroidInstallModules

Specifica i moduli installati dal comando bundletool durante l'installazione di bundles.

AndroidMavenLibrary

<AndroidMavenLibrary> consente di specificare un artefatto Maven che verrà scaricato e aggiunto automaticamente a un progetto di associazione .NET per Android. Ciò può essere utile per semplificare la manutenzione delle associazioni .NET per Android per gli artefatti ospitati in Maven.

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

Sono supportati i metadati MSBuild seguenti:

  • %(Version): versione obbligatoria della libreria Java a cui fa %(Include)riferimento .
  • %(Repository): repository Maven facoltativo da usare. I valori supportati sono Central (impostazione predefinita), Googleo un https URL di un repository Maven.

L'elemento <AndroidMavenLibrary> viene convertito in AndroidLibrary, quindi tutti i metadati supportati da <AndroidLibrary> %(Bind) o %(Pack) sono supportati.

Per altri dettagli, vedere la documentazione di AndroidMavenLibrary.

Questa azione di compilazione è stata introdotta in .NET 9.

AndroidNativeLibrary

Le librerie native vengono aggiunte alla compilazione impostandone l'azione di compilazione su AndroidNativeLibrary.

Si noti che poiché Android supporta più interfacce binarie dell'applicazione, il sistema di compilazione deve conoscere l'interfaccia ABI per cui è compilata la libreria nativa. È possibile specificare l'interfaccia ABI in due modi:

  1. Analisi del percorso.
  2. Uso dei metadati dell'elemento %(Abi) .

Con l'analisi del percorso, il nome della directory padre della libreria nativa viene usato per specificare l'ABI di destinazione della libreria. Se quindi si aggiunge lib/armeabi-v7a/libfoo.so alla compilazione, l'ABI verrà analizzato come armeabi-v7a.

Nome dell'attributo dell'elemento

Abi : specifica l'interfaccia ABI della libreria nativa.

<ItemGroup>
  <AndroidNativeLibrary Include="path/to/libfoo.so">
    <Abi>armeabi-v7a</Abi>
  </AndroidNativeLibrary>
</ItemGroup>

AndroidPackagingOptionsExclude

Un set di elementi compatibili con file glob che consentirà di escludere gli elementi dal pacchetto finale. I valori predefiniti sono i seguenti

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

Gli elementi possono usare i caratteri BLOB di file per i caratteri jolly, ad * esempio e ?. Tuttavia, questi elementi DEVONO essere codificati con URL o usare $([MSBuild]::Escape('')). In questo modo MSBuild non tenta di interpretarli come caratteri jolly di file effettivi.

Ad esempio:

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

NOTA: *? e . verrà sostituito nell'attività BuildApk con i glob del file appropriati.

Se il file glob predefinito è troppo restrittivo, è possibile rimuoverlo aggiungendo quanto segue al file csproj

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

Aggiunta in .NET 7.

AndroidPackagingOptionsInclude

Un set di elementi compatibili con file glob che consentirà di includere gli elementi dal pacchetto finale. I valori predefiniti sono i seguenti

<ItemGroup>
	<AndroidPackagingOptionsInclude Include="$([MSBuild]::Escape('*.kotlin_builtins')" />
</ItemGroup>

Gli elementi possono usare i caratteri BLOB di file per i caratteri jolly, ad * esempio e ?. Tuttavia, questi elementi DEVONO usare la codifica URL o '$([MSBuild]::Escape(''))'. In questo modo MSBuild non tenta di interpretarli come caratteri jolly di file effettivi. Ad esempio:

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

NOTA: *? e . verrà sostituito nell'attività BuildApk con i glob del file appropriati.

Aggiunta in .NET 9.

AndroidResource

Tutti i file con un'azione di compilazione AndroidResource vengono compilati nelle risorse Android durante il processo di compilazione e resi accessibili tramite $(AndroidResgenFile).

<ItemGroup>
  <AndroidResource Include="Resources\values\strings.xml" />
</ItemGroup>

Gli utenti più avanzati potrebbero aver bisogno di usare risorse diverse a seconda della configurazione, ma con lo stesso percorso effettivo. A questo scopo, è necessario avere più directory di risorse e file con gli stessi percorsi relativi in queste directory diverse e usare condizioni MSBuild per includere in modo condizionale file diversi a seconda della configurazione. Ad esempio:

<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 : specifica il percorso della risorsa in modo esplicito. Consente i file di "aliasing" in modo che saranno disponibili come più nomi di risorse distinti.

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

Contenuto

La normale azione di compilazione Content non è supportata, perché non è stato determinato come supportarla senza un passaggio per la prima esecuzione probabilmente costoso.

Se si tenta di usare l'azione @(Content) di compilazione, verrà generato un avviso XA0101 .

EmbeddedJar

In un progetto di associazione .NET per Android, l'azione di compilazione EmbeddedJar associa la libreria Java/Kotlin e incorpora il .jar file nella libreria. Quando un progetto di applicazione .NET per Android usa la libreria, avrà accesso alle API Java/Kotlin da C# e includerà il codice Java/Kotlin nell'applicazione Android finale.

È invece consigliabile usare l'azione di compilazione AndroidLibrary come alternativa, ad esempio:

<Project>
  <ItemGroup>
    <AndroidLibrary Include="Library.jar" />
  </ItemGroup>
</Project>

EmbeddedNativeLibrary

In una libreria di classi .NET per Android o in un progetto di associazione Java, l'azione di compilazione EmbeddedNativeLibrary aggrega una libreria nativa, lib/armeabi-v7a/libfoo.so ad esempio nella libreria. Quando un'applicazione .NET per Android utilizza la libreria, il libfoo.so file verrà incluso nell'applicazione Android finale.

È possibile usare l'azione di compilazione AndroidNativeLibrary come alternativa.

EmbeddedReferenceJar

In un progetto di associazione .NET per Android, l'azione di compilazione EmbeddedReferenceJar incorpora il .jar file nella libreria, ma non crea un'associazione C# come fa EmbeddedJar. Quando un progetto di applicazione .NET per Android usa la libreria, includerà il codice Java/Kotlin nell'applicazione Android finale.

È possibile usare l'azione di compilazione AndroidLibrary come alternativa, <AndroidLibrary Include="..." Bind="false" />ad esempio :

<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

In un progetto di associazione .NET per Android, l'azione di compilazione JavaSourceJar viene usata nei .jar file che contengono codice sorgente Java che contengono commenti alla documentazione Javadoc.

Javadoc verrà invece convertito in commenti della documentazione XML C# all'interno del codice sorgente dell'associazione generato.

$(AndroidJavadocVerbosity) controlla il modo in cui è "dettagliato" o "completo" il codice Javadoc importato.

Sono supportati i metadati MSBuild seguenti:

  • %(CopyrightFile): percorso di un file che contiene informazioni sul copyright per il contenuto javadoc, che verrà aggiunto a tutta la documentazione importata.

  • %(UrlPrefix): prefisso URL per supportare il collegamento alla documentazione online all'interno della documentazione importata.

  • %(UrlStyle): lo "stile" degli URL da generare durante il collegamento alla documentazione online. Attualmente è supportato un solo stile: developer.android.com/reference@2020-Nov.

  • %(DocRootUrl): prefisso URL da usare al posto di tutte le {@docroot} istanze nella documentazione importata.

LibraryProjectZip

L'azione di compilazione LibraryProjectZip associa la libreria Java/Kotlin e incorpora il .zip file o .aar nella libreria. Quando un progetto di applicazione .NET per Android usa la libreria, avrà accesso alle API Java/Kotlin da C# e includerà il codice Java/Kotlin nell'applicazione Android finale.

LinkDescription

I file con un'azione di compilazione LinkDescription vengono usati per controllare il comportamento del linker.

ProguardConfiguration

I file con un'azione di compilazione ProguardConfiguration contengono opzioni usate per controllare il comportamento di proguard. Per altre informazioni su questa azione di compilazione, vedere ProGuard.

Questi file vengono ignorati a meno che il $(EnableProguard) La proprietà MSBuild è True.