Xamarin.Android-Projekt-Migration

Ein .NET 8-Projekt für eine .NET für Android-App ähnelt dem folgenden Beispiel:

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

Für ein Bibliotheksprojekt lassen Sie die Eigenschaft $(OutputType) ganz weg oder geben Sie Library als Eigenschaftswert an.

.NET-Konfigurationsdateien

Konfigurationsdateien wie Foo.dll.config oder Foo.exe.config werden in .NET für Android-Projekten nicht unterstützt. <dllmap> Konfigurationselemente werden in .NET Core überhaupt nicht unterstützt, und andere Elementtypen für Kompatibilitätspakete wie System.Configuration.ConfigurationManager wurden in Android-Projekten nie unterstützt.

Änderungen an MSBuild-Eigenschaften

Die Eigenschaft $(AndroidSupportedAbis) sollte nicht verwendet werden:

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

Stattdessen sollte die Eigenschaft $(AndroidSupportedAbis) durch .NET-Laufzeitbezeichner ersetzt werden:

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

Weitere Informationen zu Laufzeitbezeichnern finden Sie unter .NET RID Catalog.

In der folgenden Tabelle sind andere MSBuild-Eigenschaften aufgeführt, die in .NET für Android geändert wurden:

Eigenschaft	Kommentare
$(AndroidUseIntermediateDesignerFile)	True standardmäßig.
$(AndroidBoundExceptionType)	System standardmäßig. Diese Eigenschaft ändert die Arten von Ausnahmen, die von verschiedenen Methoden ausgelöst werden, um eine bessere Anpassung an die .NET-Semantik zu erreichen, was auf Kosten der Kompatibilität mit Xamarin.Android geht. Weitere Informationen finden Sie unter Einige der neuen umhüllten Java-Ausnahmen verwenden BCL-Ausnahmen, die sich von den entsprechenden BCL-Typen unterscheiden.
$(AndroidClassParser)	class-parse standardmäßig. jar2xml wird nicht unterstützt.
$(AndroidDexTool)	d8 standardmäßig. dx wird nicht unterstützt.
$(AndroidCodegenTarget)	XAJavaInterop1 standardmäßig. XamarinAndroid wird nicht unterstützt.
$(AndroidManifest)	Standardmäßig wird AndroidManifest.xml im Stammverzeichnis von Projekten verwendet, da Properties\AssemblyInfo.cs in SDK-Projekten nicht mehr verwendet wird. Properties\AndroidManifest.xml wird ebenfalls erkannt und verwendet, wenn es vorhanden ist, um die Migration zu erleichtern.
$(DebugType)	portable standardmäßig. full und pdbonly werden nicht unterstützt.
$(MonoSymbolArchive)	False, da mono-symbolicate nicht unterstützt wird.

Wenn außerdem die Java-Bindung mit @(InputJar), @(EmbeddedJar) oder @(LibraryProjectZip) aktiviert ist, wird die Eigenschaft $(AllowUnsafeBlocks) standardmäßig auf True gesetzt.

Hinweis

Das Referenzieren eines Android Wear-Projekts aus einer Android-App wird nicht unterstützt.

Änderungen an AndroidManifest.xml

In Xamarin.Android-, Java- und Kotlin-Android-Projekten gibt das <uses-sdk/>-Element die minimale Android-Version an, die Ihre App unterstützt, sowie die Android-Zielversion, gegen die Ihre App kompiliert wird:

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

Weitere Informationen über das <uses-sdk/>-Element finden Sie in der Android-Dokumentation.

In .NET 8 Android-Apps gibt es MSBuild-Eigenschaften, um diese Werte festzulegen. Die Verwendung der MSBuild-Eigenschaften hat weitere Vorteile. In den meisten Fällen sollte das <uses-sdk/>-Element zugunsten von Werten in der .csproj-Datei Ihres Projekts entfernt werden:

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

In diesem Beispiel ist net8.0-android die Kurzform für net8.0-android34.0. Künftige Versionen von .NET werden die neueste Android-Version verfolgen, die zum Zeitpunkt der .NET-Veröffentlichung verfügbar ist.

TargetFramework wird android:targetSdkVersion zugeordnet. Zum Zeitpunkt der Erstellung wird dieser Wert automatisch in das <uses-sdk/>-Element aufgenommen. Der Vorteil der Verwendung von TargetFramework auf diese Weise ist, dass Sie die passende C#-Bindung für Android API 34 für net8.0-android34.0 erhalten. Android wird unabhängig vom .NET-Release-Zyklus veröffentlicht, sodass wir die Flexibilität haben, uns für net8.0-android35.0 zu entscheiden, wenn eine Bindung für die nächste Android-Version verfügbar ist.

In ähnlicher Weise wird SupportedOSPlatformVersion auf android:minSdkVersion abgebildet. Zum Zeitpunkt der Erstellung wird dieser Wert automatisch in das <uses-sdk/>-Element aufgenommen. Android-APIs werden mit SupportedOSPlatformAttribute dekoriert, sodass Sie Build-Warnungen für den Aufruf von APIs erhalten, die nur für einige der Android-Versionen verfügbar sind, auf denen Ihre App laufen kann:

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

Um diese API sicher zu verwenden, können Sie eine höhere SupportedOSPlatformVersion in Ihrem Projekt deklarieren oder die IsAndroidVersionAtLeast API zur Laufzeit verwenden:

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

Standardmäßiger Dateieinschluss

Das standardmäßige Globbingverhalten von .NET für Android-Dateien wird in AutoImport.props definiert. Dieses Verhalten kann für Android-Elemente deaktiviert werden, indem $(EnableDefaultAndroidItems) auf false festgelegt wird. Alternativ kann das gesamte standardmäßige Einschlussverhalten von Elementen deaktiviert werden, indem $(EnableDefaultItems) auf false festgelegt wird. Weitere Informationen finden Sie unter Workload Props-Dateien.

Laufzeitverhalten

In .NET 5+ gibt es auf verschiedenen Plattformen Änderungen im Verhalten der String.IndexOf()-Methode. Weitere Informationen finden Sie unter .NET-Globalisierung und ICU.

Linker

.NET 9 verfügt über neue Einstellungen für den Linker:

• <TrimMode>Full</TrimMode>, das die vollständige Kürzung ausführt.

Weitere Informationen finden Sie unter Kürzungsoptionen.

In .NET für Android-Projekten verwenden Debug-Builds standardmäßig nicht den Linker, und Release-Builds legen PublishTrimmed=true und TrimMode=partial fest.

Ahead-of-time-Kompilierung

Bei $(RunAOTCompilation) handelt es sich um die neue MSBuild-Eigenschaft zur Aktivierung der Ahead-of-Time (AoT)-Kompilierung. Dies ist die gleiche Eigenschaft, die für Blazor WASM verwendet wird. Die $(AotAssemblies)-Eigenschaft ermöglicht außerdem AOT, um die Migration von Xamarin.Android-Projekten zu .NET für Android-Projekten zu unterstützen. Diese Eigenschaft wurde jedoch in .NET 7 als veraltet markiert.

Die Release-Builds enthalten standardmäßig die folgenden AOT-Eigenschaftswerte:

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

Bei diesem Verhalten werden die $(RunAOTCompilation)- und $(AndroidEnableProfiledAot) -Eigenschaften gelöscht und die optimalen Einstellungen für Startzeit und App-Größe ausgewählt.

Um AOT zu deaktivieren, müssen Sie die $(RunAOTCompilation)- und $(AndroidEnableProfiledAot)-Eigenschaften explizit auf false festlegen:

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

Unterstützte Codierungen

Wenn Ihre Xamarin.Android-App bestimmte internationale Codesets verwendet, müssen diese explizit in Ihrer Projektdatei mit der MSBuild-Eigenschaft Mandroidl18n angegeben werden, damit der Linker die unterstützenden Ressourcen einbeziehen kann. Weitere Informationen zu dieser Build-Eigenschaft finden Sie unter MAndroidl18n.

Die MSBuild-Eigenschaft Mandroidl18n wird jedoch in .NET für Android-Apps nicht unterstützt. Sie wird stattdessen vom NuGet-Paket System.TextEncoding.CodePages unterstützt. Weitere Informationen finden Sie unter CodePagesEncodingProvider.

.NET CLI

.NET für Android unterstützt die Verwendung der .NET-Befehlszeilenschnittstelle (.NET CLI) zum Erstellen, Erstellen, Veröffentlichen und Ausführen von Android-Apps.

dotnet new

dotnet new kann verwendet werden, um neue .NET für Android-Projekte und -Elemente mithilfe von Projektvorlagen und Elementvorlagen zu erstellen, die gemäß den Mustern und der Benennung vorhandener .NET-Vorlagen benannt sind:

Vorlage	Kurzname	Sprache	Tags
Android-Aktivitätsvorlage	android-activity	C#	Android
Android Java-Bibliotheksbindung	android-bindinglib	C#	Android
Android-Layoutvorlage	android-layout	C#	Android
Android-Klassenbibliothek	androidlib	C#	Android
Android-App	Android	C#	Android

Die folgenden Beispiele zeigen die Verwendung von dotnet new zum Erstellen verschiedener .NET für Android-Projekte:

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

Nachdem .NET für Android-Projekte erstellt wurden, können Elementvorlagen zum Hinzufügen von Elementen zu den Projekten verwendet werden:

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

dotnet build & publish

Für .NET für Android erstellt dotnet build eine ausführbare App. Dies bedeutet die Erstellung einer .apk- oder .aab-Datei während des Buildprozesses und die Anordnung von MSBuild-Aufgaben aus dem .NET SDK, sodass diese während des Builds ausgeführt werden. Daher führt .NET für Android während eines Builds die folgenden Aktionen aus:

• Ausführen von aapt, um Resource.designer.cs zu generieren und potenzielle Buildfehler und Probleme in @(AndroidResource)-Dateien auszugeben.
• Kompilieren von C#-Code
• Führen Sie das MSBuild-Ziel ILLink zum Linken aus.
• Generieren Sie Java-Stubs und AndroidManifest.xml.
• Kompilieren Sie Java-Code über javac.
• Konvertieren Sie Java-Code über d8/r8 in .dex.
• Erstellen Sie .apk oder .aab und signieren Sie es.

dotnet publish ist für die Veröffentlichung einer App für Google Play und andere Vertriebsmechanismen wie Ad-hoc reserviert. Es signiert auch die .apk oder .aab mit verschiedenen Schlüsseln.

Hinweis

Das Verhalten innerhalb von IDEs wird sich unterscheiden. Das Build-Ziel wird keine .apk-Datei erzeugen, wenn $(BuildingInsideVisualStudio)true ist. IDEs rufen das Install-Ziel für die Bereitstellung auf, was die .apk-Datei erzeugt. Dieses Verhalten entspricht Xamarin.Android.

dotnet run

dotnet run kann verwendet werden, um Apps auf einem Gerät oder Emulator über das Argument --project zu starten:

dotnet run --project HelloAndroid.csproj

Alternativ können Sie auch das MSBuild-Ziel Run verwenden:

dotnet build HelloAndroid.csproj -t:Run

Weitere Informationen

• Bindungsprojekte