Migrazione del progetto Xamarin.Android

Un progetto .NET 8 per un'app .NET per Android è simile all'esempio seguente:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0-android</TargetFramework>
    <OutputType>Exe</OutputType>
  </PropertyGroup>
</Project>

Per un progetto di libreria, omettere completamente la $(OutputType) proprietà o specificare Library come valore della proprietà.

File di configurazione .NET

Non è disponibile alcun supporto per i file di configurazione, Foo.dll.config ad esempio o Foo.exe.config in .NET per i progetti Android. <dllmap> gli elementi di configurazione non sono supportati affatto in .NET Core e altri tipi di elemento per i pacchetti di compatibilità come System.Configuration.ConfigurationManager non sono mai stati supportati nei progetti Android.

Modifiche alle proprietà di MSBuild

La $(AndroidSupportedAbis) proprietà non deve essere usata:

<PropertyGroup>
  <!-- Used in Xamarin.Android projects -->
  <AndroidSupportedAbis>armeabi-v7a;arm64-v8a;x86;x86_64</AndroidSupportedAbis>
</PropertyGroup>

Al contrario, la $(AndroidSupportedAbis) proprietà deve essere sostituita con gli identificatori di runtime .NET:

<PropertyGroup>
  <!-- Used in .NET for Android projects -->
  <RuntimeIdentifiers>android-arm;android-arm64;android-x86;android-x64</RuntimeIdentifiers>
</PropertyGroup>

Per altre informazioni sugli identificatori di runtime, vedere Catalogo RID .NET.

La tabella seguente illustra altre proprietà di MSBuild modificate in .NET per Android:

Proprietà Commenti
$(AndroidUseIntermediateDesignerFile) True per impostazione predefinita.
$(AndroidBoundExceptionType) System per impostazione predefinita. Questa proprietà modifica i tipi di eccezioni generate da vari metodi per allinearsi meglio alla semantica .NET, al costo della compatibilità con Xamarin.Android. Per altre informazioni, vedere Alcune delle nuove eccezioni Java di cui è stato eseguito il wrapping usano eccezioni BCL diverse dai tipi BCL correlati.
$(AndroidClassParser) class-parse per impostazione predefinita. jar2xml non è supportata.
$(AndroidDexTool) d8 per impostazione predefinita. dx non è supportata.
$(AndroidCodegenTarget) XAJavaInterop1 per impostazione predefinita. XamarinAndroid non è supportata.
$(AndroidManifest) L'impostazione predefinita di AndroidManifest.xml è nella radice dei progetti perché Properties\AssemblyInfo.cs non viene più utilizzata nei progetti in stile SDK. Properties\AndroidManifest.xml verrà inoltre rilevato e usato se esistente per facilitare la migrazione.
$(DebugType) portable per impostazione predefinita. full e pdbonly non sono supportati.
$(MonoSymbolArchive) False, poiché mono-symbolicate non è supportato.

Inoltre, se l'associazione Java è abilitata con @(InputJar), @(EmbeddedJar)o @(LibraryProjectZip), per impostazione predefinita la $(AllowUnsafeBlocks) proprietà è True.

Nota

Il riferimento a un progetto Android Wear da un'app Android non è supportato.

Modifiche apportate a AndroidManifest.xml

Nei progetti Xamarin.Android, Java e Kotlin Android l'elemento <uses-sdk/> indica la versione minima supportata dall'app e la versione android di destinazione in cui viene compilata l'app:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    android:versionCode="1"
    android:versionName="1.0"
    package="com.companyname.myapp">
  <uses-sdk android:minSdkVersion="21" android:targetSdkVersion="33" />
  <application android:icon="@mipmap/ic_launcher" android:label="@string/app_name" android:theme="@style/AppTheme" />
</manifest>

Per altre informazioni sull'elemento <uses-sdk/> , vedere la documentazione di Android.

Nelle app Android .NET 8 sono disponibili proprietà di MSBuild per impostare questi valori. L'uso delle proprietà di MSBuild offre altri vantaggi. Nella maggior parte dei casi l'elemento <uses-sdk/> deve essere rimosso a favore dei valori nel file del .csproj progetto:

<Project>
  <PropertyGroup>
    <TargetFramework>net8.0-android</TargetFramework>
    <SupportedOSPlatformVersion>21</SupportedOSPlatformVersion>
  </PropertyGroup>
</Project>

In questo esempio, net8.0-android è una sintassi abbreviata per net8.0-android34.0. Le versioni future di .NET tengono traccia della versione più recente di Android disponibile al momento della versione .NET.

TargetFramework mappa su android:targetSdkVersion. In fase di compilazione, questo valore verrà automaticamente incluso nell'elemento <uses-sdk/> . Il vantaggio dell'uso TargetFramework in questo modo è che si ha l'associazione C# corrispondente per l'API Android 34 per net8.0-android34.0. Le versioni di Android vengono rilasciate indipendentemente dal ciclo di rilascio di .NET, quindi abbiamo la flessibilità di aderire a net8.0-android35.0 quando è disponibile un'associazione per la prossima versione di Android.

Analogamente, SupportedOSPlatformVersion mappa su android:minSdkVersion. In fase di compilazione, questo valore verrà automaticamente incluso nell'elemento <uses-sdk/> . Le API Android sono decorate con il SupportedOSPlatformAttribute in modo da ricevere avvisi di compilazione quando si chiamano le API disponibili solo per alcune delle versioni Android su cui può essere eseguita l'app.

error CA1416: This call site is reachable on 'Android' 21.0 and later. `ConnectivityManager.ActiveNetwork` is only supported on: 'Android' 23.0 and later.

Per usare in modo sicuro questa API, è possibile dichiarare un valore superiore SupportedOSPlatformVersion nel progetto o usare l'API IsAndroidVersionAtLeast in fase di esecuzione:

if (OperatingSystem.IsAndroidVersionAtLeast(23))
{
    // Use the API here
}

Inclusione predefinita dei file

Il comportamento di file globbing predefinito per .NET su Android è definito in AutoImport.props. Questo comportamento può essere disabilitato per gli elementi Android impostando $(EnableDefaultAndroidItems) su falseo è possibile disabilitare tutto il comportamento predefinito di inclusione degli elementi impostando $(EnableDefaultItems) su false. Per ulteriori informazioni, vedere File props del carico di lavoro.

Comportamento durante l'esecuzione

Esistono modifiche comportamentali al String.IndexOf() metodo in .NET 5+ su piattaforme diverse. Per altre informazioni, vedere Globalizzazione .NET e ICU.

Linker

.NET 8 include nuove impostazioni per il linker:

  • <PublishTrimmed>true</PublishTrimmed>
  • <TrimMode>partial</TrimMode>, che riduce gli assembly che hanno espressamente scelto di essere ridotti.

Per altre informazioni, vedere Opzioni di taglio.

Per impostazione predefinita nei progetti .NET per Android, le compilazioni Debug non utilizzano il linker, e le compilazioni Release impostano PublishTrimmed=true e TrimMode=partial.

Se viene usata l'impostazione legacy AndroidLinkMode , entrambe SdkOnly e Full per impostazione predefinita sono equivalenti alle impostazioni del linker:

  • <PublishTrimmed>true</PublishTrimmed>
  • <TrimMode>partial</TrimMode>

Con AndroidLinkMode=SdkOnly, solo gli assembly BCL e SDK contrassegnati con %(Trimmable) sono collegati a livello di membro. AndroidLinkMode=Full imposta %(TrimMode)=partial su tutti gli assembly .NET.

Suggerimento

È consigliabile eseguire la migrazione alle nuove impostazioni del linker, perché l'impostazione AndroidLinkMode verrà infine deprecata.

.NET 9 include nuove impostazioni per il linker:

  • <TrimMode>Full</TrimMode>, che esegue il taglio completo.

Per altre informazioni, vedere Opzioni di taglio.

In .NET per i progetti Android, per impostazione predefinita, le compilazioni Debug non usano il linker, e le compilazioni Release impostano PublishTrimmed=true e TrimMode=partial.

Compilazione anticipata

$(RunAOTCompilation) è la nuova proprietà MSBuild per abilitare la compilazione Ahead-of-Time (AoT). Questa è la stessa proprietà usata per Blazor WASM. La $(AotAssemblies) proprietà abilita anche AOT, per facilitare la migrazione da progetti Xamarin.Android a progetti .NET per Android. Tuttavia, questa proprietà è stata deprecata in .NET 7.

Per impostazione predefinita, le build di rilascio impostano i seguenti valori di proprietà AOT:

<PropertyGroup Condition="'$(Configuration)' == 'Release'">
  <RunAOTCompilation>true</RunAOTCompilation>
  <AndroidEnableProfiledAot>true</AndroidEnableProfiledAot>
</PropertyGroup>

Questo è il comportamento quando le $(RunAOTCompilation) proprietà e $(AndroidEnableProfiledAot) vengono annullate e sceglie le impostazioni ottimali per l'ora di avvio e le dimensioni dell'app.

Per disabilitare AOT, è necessario impostare in modo esplicito le $(RunAOTCompilation) proprietà e $(AndroidEnableProfiledAot) su false:

<PropertyGroup Condition="'$(Configuration)' == 'Release'">
  <RunAOTCompilation>false</RunAOTCompilation>
  <AndroidEnableProfiledAot>false</AndroidEnableProfiledAot>
</PropertyGroup>

Codifiche supportate

Se l'app Xamarin.Android usa determinati set di codici internazionali, devono essere specificati in modo esplicito nel file di progetto usando la Mandroidl18n proprietà MSBuild, in modo che il linker possa includere risorse di supporto. Per ulteriori informazioni su questa proprietà di build, vedere MAndroidl18n.

Tuttavia, la Mandroidl18n proprietà MSBuild non è supportata nelle app .NET per Android. Il supporto viene invece fornito dal pacchetto NuGet System.TextEncoding.CodePages . Per ulteriori informazioni, vedere CodePagesEncodingProvider.

CLI .NET

.NET per Android supporta l'uso dell'interfaccia della riga di comando .NET (interfaccia della riga di comando .NET) per creare, compilare, pubblicare ed eseguire app Android.

dotnet new

dotnet new può essere usato per creare nuovi progetti .NET per i progetti e gli elementi Android usando modelli di progetto e modelli di elemento denominati seguendo i modelli e la denominazione dei modelli .NET esistenti:

Modello Nome breve Lingua Tag
Modello di attività Android attività di Android C# Android
Collegamento delle librerie Android Java android-bindinglib C# Android
Modello di layout Android android-layout C# Android
Libreria di classi Android androidlib C# Android
Applicazione Android android C# Android

Gli esempi seguenti illustrano l'uso dotnet new di per creare diversi tipi di progetti .NET per Android:

dotnet new android            --output MyAndroidApp     --packageName com.mycompany.myandroidapp
dotnet new androidlib         --output MyAndroidLibrary
dotnet new android-bindinglib --output MyJavaBinding

Dopo aver creato i progetti .NET per Android, è possibile usare i modelli di elemento per aggiungere elementi ai progetti:

dotnet new android-activity --name LoginActivity --namespace MyAndroidApp
dotnet new android-layout   --name MyLayout      --output Resources/layout

dotnet build & publish

Per .NET per Android, dotnet build genera un'app eseguibile. Ciò significa creare un .apk file o .aab durante il processo di compilazione e riordinare le attività di MSBuild da .NET SDK in modo che vengano eseguite durante la compilazione. Pertanto, .NET per Android esegue le operazioni seguenti durante una compilazione:

  • Esegui aapt per generare Resource.designer.cs e potenzialmente causare errori di build a causa di problemi nei file @(AndroidResource).
  • Compilare il codice C#.
  • Eseguire la destinazione MSBuild ILLink per il collegamento.
  • Generare stub Java e AndroidManifest.xml.
  • Compilare il codice Java tramite javac.
  • Convertire il codice Java in .dex tramite d8/r8.
  • Creare un oggetto .apk o .aab e firmarlo.

dotnet publish è riservato per la pubblicazione di un'app per Google Play e altri meccanismi di distribuzione, ad esempio ad hoc. Firma anche il .apk o il .aab con chiavi diverse.

Nota

Il comportamento all'interno degli IDE sarà diverso. La Build destinazione non produrrà un .apk file se $(BuildingInsideVisualStudio) è true. Gli IDE chiameranno il target Install per la distribuzione, che genererà il file .apk. Questo comportamento corrisponde a Xamarin.Android.

dotnet run

dotnet run può essere usato per avviare le app in un dispositivo o un emulatore tramite l'argomento --project :

dotnet run --project HelloAndroid.csproj

In alternativa, è possibile usare la Run destinazione MSBuild:

dotnet build HelloAndroid.csproj -t:Run

Vedi anche

  • Last updated on