Dela via


Xamarin.Android-projektmigrering

Ett .NET 8-projekt för en .NET för Android-app liknar följande exempel:

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

För ett biblioteksprojekt utelämnar du egenskapen $(OutputType) helt eller anger Library som egenskapsvärde.

.NET-konfigurationsfiler

Det finns inget stöd för konfigurationsfiler till exempel Foo.dll.config eller Foo.exe.config i .NET för Android-projekt. <dllmap> konfigurationselement stöds inte alls i .NET Core, och andra typer av element för kompatibilitetspaket som System.Configuration.ConfigurationManager har aldrig varit stödda i Android-projekt.

Ändringar i MSBuild-egenskaper

Egenskapen $(AndroidSupportedAbis) ska inte användas:

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

I stället bör egenskapen $(AndroidSupportedAbis) ersättas med .NET-körningsidentifierare:

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

Mer information om körningstidsidentifierare finns i .NET RID-katalog.

I följande tabell visas andra MSBuild-egenskaper som har ändrats i .NET för Android:

Egenskap Kommentarer
$(AndroidUseIntermediateDesignerFile) True som standard.
$(AndroidBoundExceptionType) System som standard. Den här egenskapen ändrar de typer av undantag som genereras från olika metoder för att bättre anpassa till .NET-semantik, på bekostnad av kompatibilitet med Xamarin.Android. Mer information finns i Några av de nya omslutna Java-undantagen använder BCL-undantag som skiljer sig från de relaterade BCL-typerna.
$(AndroidClassParser) class-parse som standard. jar2xml stöds inte.
$(AndroidDexTool) d8 som standard. dx stöds inte.
$(AndroidCodegenTarget) XAJavaInterop1 som standard. XamarinAndroid stöds inte.
$(AndroidManifest) Standardvärdet är AndroidManifest.xml i roten av projektet, eftersom Properties\AssemblyInfo.cs inte längre används i SDK-projekt. Properties\AndroidManifest.xml identifieras och används även om det finns för att underlätta migreringen.
$(DebugType) portable som standard. full och pdbonly stöds inte.
$(MonoSymbolArchive) Falseeftersom mono-symbolicate inte stöds.

Om Java-bindning dessutom är aktiverat med @(InputJar), @(EmbeddedJar)eller @(LibraryProjectZip), så har egenskapen $(AllowUnsafeBlocks) standardvärdet True.

Not

Det går inte att referera till ett Android Wear-projekt från en Android-app.

Ändringar i AndroidManifest.xml

I Xamarin.Android-, Java- och Kotlin Android-projekt anger <uses-sdk/>-elementet den lägsta Android-version som appen stöder, samt den Android-målversion som appen kompileras mot:

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

Mer information om elementet <uses-sdk/> finns i Android-dokumentationen.

I .NET 8 Android-appar finns det MSBuild-egenskaper för att ange dessa värden. Att använda MSBuild-egenskaperna har andra fördelar. I de flesta fall bör <uses-sdk/>-elementet tas bort till förmån för värden i projektets .csproj-fil:

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

I det här exemplet är net8.0-android en förkortning för net8.0-android34.0. Framtida versioner av .NET spårar den senaste Android-versionen som är tillgänglig vid tidpunkten för .NET-versionen.

TargetFramework mappar till android:targetSdkVersion. Vid bygget inkluderas det här värdet automatiskt i <uses-sdk/>-elementet åt dig. Fördelen med att använda TargetFramework på det här sättet är att du får den matchande C#-bindningen för Android API 34 för net8.0-android34.0. Android-versioner släpps oberoende av .NET-versionscykeln, så vi har möjlighet att välja net8.0-android35.0 när en bindning är tillgänglig för nästa Android-upplaga.

På samma sätt mappar SupportedOSPlatformVersion till android:minSdkVersion. Vid bygget inkluderas det här värdet automatiskt i <uses-sdk/>-elementet åt dig. Android-API:er är dekorerade med SupportedOSPlatformAttribute så att du får byggvarningar för att anropa API:er som endast är tillgängliga för vissa Av de Android-versioner som appen kan köras på:

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

Om du vill använda det här API:et på ett säkert sätt kan du deklarera en högre SupportedOSPlatformVersion i projektet eller använda IsAndroidVersionAtLeast-API:et vid körning:

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

Standardfilinkludering

Standardbeteendet för .NET gällande filmönstermatchning för Android-relaterade filer definieras i AutoImport.props. Det här beteendet kan inaktiveras för Android-objekt genom att ange $(EnableDefaultAndroidItems) till false, eller så kan alla standardbeteenden för objektinkludering inaktiveras genom att ange $(EnableDefaultItems) till false. Mer information finns i arbetsbelastningens konfigurationsfiler.

Körningsbeteende

Det finns beteendeändringar i metoden String.IndexOf() i .NET 5+ på olika plattformar. Mer information finns i .NET-globalisering och ICU-.

Linkredigerare

.NET 8 har nya inställningar för länkaren:

  • <PublishTrimmed>true</PublishTrimmed>
  • <TrimMode>partial</TrimMode>, som trimmar samlingar som har valt att delta i trimmning.

För mer information, se Trimningsalternativ.

I .NET Android-projekt används inte länkaren som standard i Debug byggningar, och i Release byggningar ställs PublishTrimmed=true och TrimMode=partialin.

Om den äldre AndroidLinkMode-inställningen används, har både SdkOnly och Full som standard motsvarande länkningsinställningar.

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

Med AndroidLinkMode=SdkOnlyär endast BCL- och SDK-sammansättningar markerade med %(Trimmable) länkade på medlemsnivå. AndroidLinkMode=Full anger %(TrimMode)=partial på alla .NET-sammansättningar.

Tips

Du bör migrera till de nya länkningsinställningarna eftersom inställningen AndroidLinkMode så småningom kommer att bli inaktuell.

.NET 9 har nya inställningar för länkaren:

  • <TrimMode>Full</TrimMode>, som utför fullständig trimning.

För mer information, se Trimningsalternativ.

I .NET för Android-projekt som standard använder Debug versioner inte länkaren och Release versioner anger PublishTrimmed=true och TrimMode=partial.

Kompilering i förväg

$(RunAOTCompilation) är den nya MSBuild-egenskapen för att aktivera AoT-kompilering (Ahead-of-Time). Det här är samma egenskap som används för Blazor WASM. Egenskapen $(AotAssemblies) aktiverar även AOT för att hjälpa till med migrering från Xamarin.Android-projekt till .NET för Android-projekt. Den här egenskapen var dock inaktuell i .NET 7.

Release-versioner använder som standard följande AOT-egenskapsvärden:

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

Det här är beteendet när egenskaperna $(RunAOTCompilation) och $(AndroidEnableProfiledAot) tas bort och väljer de optimala inställningarna för starttid och appstorlek.

Om du vill inaktivera AOT måste du uttryckligen ange egenskaperna $(RunAOTCompilation) och $(AndroidEnableProfiledAot) till false:

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

Kodningar som stöds

Om Xamarin.Android-appen använder vissa internationella koduppsättningar måste de anges uttryckligen i projektfilen med egenskapen Mandroidl18n MSBuild, så att länkaren kan innehålla stödresurser. Mer information om den här byggegenskapen finns i MAndroidl18n.

Egenskapen Mandroidl18n MSBuild stöds dock inte i .NET för Android-appar. Stöd tillhandahålls i stället av System.TextEncoding.CodePages NuGet-paketet. Mer information finns i CodePagesEncodingProvider.

.NET CLI

.NET för Android stöder användning av .NET-kommandoradsgränssnittet (.NET CLI) för att skapa, skapa, publicera och köra Android-appar.

dotnet new

dotnet new kan användas för att skapa nya .NET för Android-projekt och -objekt med hjälp av projektmallar och objektmallar som namnges enligt mönstren och namngivning av befintliga .NET-mallar:

Mall Kort namn Språk Taggar
Android-aktivitetsmall android-activity C# Android
Android Java-biblioteksbindning android-bindinglib C# Android
Mall för Android-layout android-layout C# Android
Android-klassbibliotek androidlib C# Android
Android-applikation android C# Android

Följande exempel visar hur du använder dotnet new för att skapa olika typer av .NET för Android-projekt:

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

När .NET för Android-projekt har skapats kan objektmallar användas för att lägga till objekt i projekten:

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

dotnet build & publicera

För .NET för Android skapar dotnet build en körbar app. Det innebär att skapa en .apk- eller .aab-fil under byggprocessen och ordna om MSBuild-uppgifter från .NET SDK så att de körs under bygget. Därför gör .NET för Android följande under en version:

  • Kör aapt för att generera Resource.designer.cs och potentiellt orsaka byggfel i @(AndroidResource)-filer.
  • Kompilera C#-kod.
  • Kör ILLink MSBuild-målet för länkning.
  • Generera Java-stubbar och AndroidManifest.xml.
  • Kompilera java-kod via javac.
  • Konvertera java-kod till .dex via d8/r8.
  • Skapa en .apk eller .aab och signera den.

dotnet publish är reserverad för publicering av en app för Google Play och andra distributionsmekanismer som ad hoc. Den signerar även .apk eller .aab med olika tangenter.

Not

Beteendet i IDE:er skiljer sig åt. Det Build målet skapar inte en .apk fil om $(BuildingInsideVisualStudio) är true. IDE:er anropar Install mål för distribution, vilket skapar .apk-filen. Det här beteendet matchar Xamarin.Android.

dotnet-körning

dotnet run kan användas för att starta appar på en enhet eller emulator via argumentet --project:

dotnet run --project HelloAndroid.csproj

Du kan också använda Run MSBuild-målet:

dotnet build HelloAndroid.csproj -t:Run

Se även