Condividi tramite

Elementi di build

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

Vengono specificati all'interno del file di progetto, ad esempio MyApp.csproj, all'interno di un itemgroup MSBuild.

Nota

In .NET per Android non esiste tecnicamente alcuna distinzione tra un'applicazione e un progetto di associazioni, quindi gli elementi di compilazione funzioneranno in entrambi. In pratica, è consigliabile creare progetti di applicazioni e associazioni separati. Gli elementi di compilazione usati principalmente nei progetti di binding sono documentati nella guida di riferimento agli elementi del progetto di associazioni MSBuild.

AndroidAdditionalJavaManifest

<AndroidAdditionalJavaManifest> viene usato insieme alla risoluzione delle dipendenze Java 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): il gruppo e l'ID artefatto della libreria Java corrispondente al file POM specificato con il formato {GroupId}:{ArtifactId}.
  • %(JavaVersion): versione della libreria Java corrispondente al file POM specificato.

Consulta la documentazione sulla risoluzione delle dipendenze di Java per ulteriori dettagli.

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

AndroidAsset

Supporta Asset Android, file inclusi nella assets cartella in un progetto Java Android.

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 utilizzare i caratteri jolly per spostare la maggior parte degli asset nel pacchetto.

<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 finiranno nel file AAB, mentre tutti gli altri asset finiranno nel pacchetto di asset assets1.

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 direttamente ai file .aar. Questa azione di compilazione verrà usata più comunemente dai componenti di Xamarin, Per includere riferimenti ai file .aar 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 è <bundle-path>:<physical-file>, dove bundle-path denota il percorso del file all'interno della directory dei metadati del bundle dell'app, e physical-file è un file esistente contenente i dati grezzi da memorizzare.

<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 avere il code-behind generato per esso nel caso in cui la proprietà $(AndroidGenerateLayoutBindings) 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.

AndroidGradleProject

<AndroidGradleProject> può essere usato per compilare e utilizzare gli output dei progetti Android Gradle creati in Android Studio o altrove.

I Include metadati devono puntare al livello superiore build.gradle o build.gradle.kts del file che verrà usato per creare il progetto. Nella directory radice del tuo progetto Gradle, che dovrebbe contenere anche gli script wrapper gradlew, troverai questo elemento.

<ItemGroup>
  <AndroidGradleProject Include="path/to/project/build.gradle.kts" ModuleName="mylibrary" />
</ItemGroup>

Sono supportati i metadati MSBuild seguenti:

  • %(Configuration): nome della configurazione da usare per compilare o assemblare il progetto o il modulo di progetto specificato. Il valore predefinito è Release.
  • %(ModuleName): nome del modulo o del sottoprogetto che deve essere compilato. Il valore predefinito è vuoto.
  • %(OutputPath): può essere impostato per sovrascrivere il percorso di output del progetto Gradle. Il valore predefinito è $(IntermediateOutputPath)gradle/%(ModuleName)%(Configuration)-{Hash}.
  • %(CreateAndroidLibrary): i file AAR di output verranno aggiunti come oggetto AndroidLibrary al progetto. I metadati supportati da <AndroidLibrary> come %(Bind) o %(Pack) verranno inoltrati se impostati. Il valore predefinito è true.

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

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 può essere soddisfatta in un modo che la risoluzione delle dipendenze Java non può 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).

Consulta la documentazione sulla risoluzione delle dipendenze di Java per ulteriori dettagli.

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 come i file .jar e .aar sono 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 in combinazione con 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 Manifest Merger. I file con questa azione di creazione passeranno attraverso lo strumento di fusione del manifesto insieme al file principale AndroidManifest.xml e ai file manifesto delle referenze. 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): un repository Maven opzionale da utilizzare. I valori supportati sono Central (impostazione predefinita), Google o un URL verso 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'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 al build, l'ABI verrà rilevato come armeabi-v7a.

Nome attributo dell'elemento

Abi – Specifica l'ABI della libreria nativa.

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

AndroidNativeLibraryNoJniPreload

Ogni libreria nativa inclusa in questo gruppo di elementi sarà esente dal meccanismo di precaricamento della libreria JNI. Per impostazione predefinita, tutte queste librerie verranno caricate dal runtime all'inizio dell'avvio dell'applicazione per garantire la corretta inizializzazione. Tuttavia, in alcuni casi potrebbe non essere il comportamento desiderato e questo gruppo di elementi consente l'esclusione di librerie da questo processo su base individuale.

Alcune librerie framework che devono essere caricate all'avvio dell'applicazione non saranno interessate se incluse in questo gruppo di elementi.

Vedere anche $(AndroidIgnoreAllJniPreload)

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 come caratteri jolly, come * 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 . verranno sostituiti nell'attività BuildApk con i modelli di 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.

Opzioni di Confezionamento AndroidIncluse

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 utilizzare i BLOB di file come caratteri jolly, come * 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 . verranno sostituiti nell'attività BuildApk con i modelli di 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 di creare "alias" dei file, rendendoli disponibili con 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 per C# all'interno del codice sorgente generato per il binding.

$(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à applicato 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.

Descrizione del Link

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.

  • Last updated on