Migracja projektu platformy Xamarin.Android

Artykuł
10/24/2024

Projekt platformy .NET 8 dla aplikacji platformy .NET dla systemu Android jest podobny do następującego przykładu:

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

W przypadku projektu biblioteki pomiń $(OutputType) właściwość całkowicie lub określ Library jako wartość właściwości.

Pliki konfiguracji platformy .NET

Nie ma obsługi plików konfiguracji, takich jak Foo.dll.config lub Foo.exe.config na platformie .NET dla projektów systemu Android. <dllmap> Elementy konfiguracji nie są w ogóle obsługiwane na platformie .NET Core, a inne typy elementów dla pakietów zgodności, takich jak System.Configuration.ConfigurationManager , nigdy nie były obsługiwane w projektach systemu Android.

Zmiany właściwości programu MSBuild

Nie $(AndroidSupportedAbis) należy używać właściwości:

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

$(AndroidSupportedAbis) Zamiast tego należy zastąpić właściwość identyfikatorami środowiska uruchomieniowego platformy .NET:

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

Aby uzyskać więcej informacji na temat identyfikatorów środowiska uruchomieniowego, zobacz Wykaz identyfikatorów RID platformy .NET.

W poniższej tabeli przedstawiono inne właściwości programu MSBuild, które uległy zmianie na platformie .NET dla systemu Android:

Właściwości	Komentarze
`$(AndroidUseIntermediateDesignerFile)`	`True` domyślnie.
`$(AndroidBoundExceptionType)`	`System` domyślnie. Ta właściwość zmienia typy wyjątków zgłaszanych z różnych metod, aby lepiej dopasować je do semantyki platformy .NET kosztem zgodności z platformą Xamarin.Android. Aby uzyskać więcej informacji, zobacz Niektóre z nowych opakowanych wyjątków języka Java używają wyjątków BCL, które różnią się od powiązanych typów listy BCL.
`$(AndroidClassParser)`	`class-parse` domyślnie. `jar2xml` nie jest obsługiwany.
`$(AndroidDexTool)`	`d8` domyślnie. `dx` nie jest obsługiwany.
`$(AndroidCodegenTarget)`	`XAJavaInterop1` domyślnie. `XamarinAndroid` nie jest obsługiwany.
`$(AndroidManifest)`	`AndroidManifest.xml` Wartość domyślna w katalogu głównym projektów, ponieważ `Properties\AssemblyInfo.cs` nie jest już używana w projektach w stylu zestawu SDK. `Properties\AndroidManifest.xml` Program zostanie również wykryty i użyty, jeśli istnieje, aby ułatwić migrację.
`$(DebugType)`	`portable` domyślnie. `full` i `pdbonly` nie są obsługiwane.
`$(MonoSymbolArchive)`	`False`, ponieważ `mono-symbolicate` nie jest obsługiwany.

Ponadto, jeśli powiązanie języka Java jest włączone z @(InputJar)@(EmbeddedJar), lub @(LibraryProjectZip), właściwość $(AllowUnsafeBlocks) jest domyślnie ustawiona na True.

Uwaga

Odwoływanie się do projektu Android Wear z poziomu aplikacji systemu Android nie jest obsługiwane.

Zmiany w AndroidManifest.xml

W projektach <uses-sdk/> Xamarin.Android, Java i Kotlin Android element określa minimalną wersję systemu Android obsługiwaną przez aplikację, a także docelową wersję systemu Android, na podstawie których aplikacja jest kompilowana:

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

Aby uzyskać więcej informacji na temat <uses-sdk/> elementu, zobacz dokumentację systemu Android.

W aplikacjach platformy .NET 8 dla systemu Android istnieją właściwości programu MSBuild do ustawiania tych wartości. Korzystanie z właściwości programu MSBuild ma inne korzyści. W większości przypadków <uses-sdk/> element powinien zostać usunięty na rzecz wartości w pliku projektu .csproj :

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

W tym przykładzie net8.0-android skrót to net8.0-android34.0. Przyszłe wersje platformy .NET będą śledzić najnowszą wersję systemu Android dostępną w momencie wydania platformy .NET.

TargetFramework mapuje na android:targetSdkVersion. W czasie kompilacji ta wartość zostanie automatycznie uwzględniona w elemecie <uses-sdk/> . Zaletą użycia TargetFramework w ten sposób jest to, że otrzymujesz pasujące powiązanie języka C# dla interfejsu API systemu Android 34 dla programu net8.0-android34.0. Wersje systemu Android niezależnie od cyklu wydania platformy .NET, dlatego mamy elastyczność, aby zdecydować net8.0-android35.0 się, gdy powiązanie jest dostępne dla następnej wersji systemu Android.

SupportedOSPlatformVersion Podobnie mapuje wartość na android:minSdkVersion. W czasie kompilacji ta wartość zostanie automatycznie uwzględniona w elemecie <uses-sdk/> . Interfejsy API systemu Android są ozdobione funkcją SupportedOSPlatformAttribute , aby otrzymywać ostrzeżenia kompilacji dotyczące wywoływania interfejsów API, które są dostępne tylko dla niektórych wersji systemu Android, w których aplikacja może działać:

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

Aby bezpiecznie korzystać z tego interfejsu API, możesz zadeklarować wyższy SupportedOSPlatformVersion poziom w projekcie lub użyć interfejsu IsAndroidVersionAtLeast API w czasie wykonywania:

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

Domyślne dołączanie plików

Domyślne zachowanie funkcji globbing pliku powiązanego z systemem Android na platformie .NET jest definiowane w pliku AutoImport.props. To zachowanie można wyłączyć dla elementów systemu Android, ustawiając $(EnableDefaultAndroidItems) falsewartość , lub wszystkie domyślne zachowanie dołączania elementów można wyłączyć, ustawiając wartość $(EnableDefaultItems) .false Aby uzyskać więcej informacji, zobacz Pliki props obciążenia.

Zachowanie środowiska uruchomieniowego

Istnieją zmiany String.IndexOf() zachowania metody na platformie .NET 5+ na różnych platformach. Aby uzyskać więcej informacji, zobacz Globalizacja platformy .NET i ICU.

Konsolidator

Program .NET 8 ma nowe ustawienia konsolidatora:

<PublishTrimmed>true</PublishTrimmed>
<TrimMode>partial</TrimMode>, które przycina zestawy, które zdecydowały się na przycinanie.

Aby uzyskać więcej informacji, zobacz Opcje przycinania.

W projektach Debug platformy .NET dla systemu Android kompilacje nie używają konsolidatora, a Release kompilacje ustawiają PublishTrimmed=true i TrimMode=partial.

Jeśli jest używane starsze AndroidLinkMode ustawienie, zarówno, jak SdkOnly i Full domyślne do równoważnych ustawień konsolidatora:

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

W programie AndroidLinkMode=SdkOnlytylko zestawy BCL i SDK oznaczone za pomocą %(Trimmable) są połączone na poziomie elementu członkowskiego. AndroidLinkMode=Full zestawy %(TrimMode)=partial na wszystkich zestawach platformy .NET.

Napiwek

Należy przeprowadzić migrację do nowych ustawień konsolidatora, ponieważ AndroidLinkMode ustawienie zostanie ostatecznie przestarzałe.

Program .NET 9 ma nowe ustawienia konsolidatora:

<TrimMode>Full</TrimMode>, który wykonuje pełne przycinanie.

Aby uzyskać więcej informacji, zobacz Opcje przycinania.

W projektach Debug platformy .NET dla systemu Android kompilacje nie używają konsolidatora, a Release kompilacje ustawiają PublishTrimmed=true i TrimMode=partial.

Kompilacja z wyprzedzeniem czasu

$(RunAOTCompilation) to nowa właściwość MSBuild umożliwiająca kompilację Ahead-of-Time (AoT). Jest to ta sama właściwość używana dla platformy Blazor WASM. Właściwość $(AotAssemblies) włącza również funkcję AOT, aby ułatwić migrację z projektów platformy Xamarin.Android do platformy .NET dla projektów systemu Android. Jednak ta właściwość została uznana za przestarzałą na platformie .NET 7.

Kompilacje wydania są domyślne dla następujących wartości właściwości AOT:

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

Jest to zachowanie, gdy $(RunAOTCompilation) właściwości i $(AndroidEnableProfiledAot) są niezastawione, i wybiera optymalne ustawienia czasu uruchamiania i rozmiaru aplikacji.

Aby wyłączyć funkcję AOT, należy jawnie ustawić $(RunAOTCompilation) właściwości i $(AndroidEnableProfiledAot) na false:

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

Obsługiwane kodowanie

Jeśli aplikacja Xamarin.Android używa niektórych międzynarodowych zestawów kodów, należy je jawnie określić w pliku projektu przy użyciu Mandroidl18n właściwości MSBuild, aby konsolidator mógł zawierać zasoby pomocnicze. Aby uzyskać więcej informacji na temat tej właściwości kompilacji, zobacz MAndroidl18n.

Mandroidl18n Jednak właściwość MSBuild nie jest obsługiwana na platformie .NET dla aplikacji systemu Android. Zamiast tego obsługa jest zapewniana przez pakiet NuGet System.TextEncoding.CodePages . Aby uzyskać więcej informacji, zobacz CodePagesEncodingProvider.

.NET CLI

Platforma .NET dla systemu Android obsługuje używanie interfejsu wiersza polecenia platformy .NET (interfejs wiersza polecenia platformy .NET) do tworzenia, kompilowania, publikowania i uruchamiania aplikacji systemu Android.

dotnet new

dotnet new Umożliwia tworzenie nowych projektów i elementów platformy .NET dla systemu Android przy użyciu szablonów projektów i szablonów elementów, które są nazwane zgodnie z wzorcami i nazewnictwem istniejących szablonów platformy .NET:

Template	Krótka nazwa	Język	Tagi
Szablon działania systemu Android	działanie systemu android	C#	Android
Powiązanie biblioteki Java systemu Android	android-bindinglib	C#	Android
Szablon układu systemu Android	układ systemu android	C#	Android
Biblioteka klas systemu Android	androidlib	C#	Android
Aplikacja systemu Android	android	C#	Android

W poniższych przykładach pokazano użycie metody dotnet new do tworzenia różnych typów platformy .NET dla projektów systemu Android:

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

Po utworzeniu projektów platformy .NET dla systemu Android szablony elementów mogą służyć do dodawania elementów do projektów:

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

dotnet build &publish

W przypadku platformy .NET dla systemu Android dotnet build tworzy aplikację do uruchomienia. Oznacza to utworzenie .apk pliku lub .aab podczas procesu kompilacji i zmiana kolejności zadań programu MSBuild z zestawu .NET SDK w taki sposób, aby były uruchamiane podczas kompilacji. W związku z tym platforma .NET dla systemu Android wykonuje następujące czynności podczas kompilacji:

Uruchom polecenie aapt , aby wygenerować Resource.designer.cs i potencjalnie emitować błędy kompilacji w przypadku problemów w @(AndroidResource) plikach.
Skompiluj kod języka C#.
Uruchom element docelowy PROGRAMU MSBuild ILLink w celu połączenia.
Generowanie wycinków java i AndroidManifest.xml.
Skompiluj kod java za pomocą polecenia javac.
Przekonwertuj kod java na .dex za pomocą d8/r8.
Utwórz element .apk lub .aab i podpisz go.

dotnet publish jest zarezerwowana do publikowania aplikacji ze sklepu Google Play i innych mechanizmów dystrybucji, takich jak ad hoc. Podpisuje również znaki .apk lub .aab z różnymi kluczami.

Uwaga

Zachowanie w środowiskach IDE będzie się różnić. Obiekt docelowy Build nie utworzy pliku, .apk jeśli $(BuildingInsideVisualStudio) ma wartość true. Środowiska IDE będą wywoływać element docelowy Install wdrożenia, co spowoduje wygenerowanie .apk pliku. To zachowanie jest zgodne z platformą Xamarin.Android.

dotnet run

dotnet run Za pomocą argumentu można uruchamiać aplikacje na urządzeniu lub emulatorze --project :

dotnet run --project HelloAndroid.csproj

Alternatywnie można użyć docelowego programu Run MSBuild:

dotnet build HelloAndroid.csproj -t:Run

Zobacz też

Wiązanie projektów

Udostępnij za pośrednictwem