Migracja projektu platformy UWP platformy Xamarin.Forms

Artykuł
05/14/2024

Aby zaktualizować projekt platformy UWP platformy Xamarin.Forms do projektu WinUI 3, należy wykonać:

Zaktualizuj plik projektu tak, aby był w stylu zestawu SDK.
Aktualizowanie przestrzeni nazw
Rozwiązywanie wszelkich zmian interfejsu API
Zaktualizuj lub zastąp niezgodne zależności wersjami platformy .NET 8.
Skompiluj i przetestuj aplikację.

Aktualizowanie pliku projektu w stylu zestawu SDK

Istniejący projekt platformy UWP platformy Xamarin.Forms można zaktualizować do istniejącego projektu WinUI 3 w stylu zestawu SDK. Projekt w stylu zestawu SDK dla aplikacji WinUI WinUI 3 dla platformy .NET jest podobny do następującego przykładu:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType> <!-- in Xamarin.Forms this was AppContainerExe -->
    <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
    <TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>
    <RootNamespace>YOUR_NAMESPACE_HERE.WinUI</RootNamespace>
    <ApplicationManifest>app.manifest</ApplicationManifest>
    <Platforms>x86;x64;ARM64</Platforms>
    <RuntimeIdentifiers>win10-x86;win10-x64;win10-arm64</RuntimeIdentifiers>
    <UseWinUI>true</UseWinUI>
    <EnableMsixTooling>true</EnableMsixTooling>
    <UseMaui>true</UseMaui>
    <!-- We do not want XAML files to be processed as .NET MAUI XAML -->
    <EnableDefaultMauiItems>false</EnableDefaultMauiItems>
  </PropertyGroup>
  ...
</Project>

Ważne

Docelowy pseudonim platformy (TFM) określa projekt jako korzystający z platformy .NET, w tym przypadku .NET 8. Aby uzyskać informacje o platformach docelowych w projektach w stylu zestawu SDK, zobacz Platformy docelowe w projektach w stylu zestawu SDK.

Aby włączyć obsługę interfejsu MAUI platformy .NET, należy dodać <UseMaui>true</UseMaui> plik projektu. Ponadto upewnij się, że dodano <EnableDefaultMauiItems>false</EnableDefaultMauiItems> cię do pliku projektu. Spowoduje to zatrzymanie otrzymywania błędów kompilacji dotyczących już zdefiniowanej InitializeComponent metody.

Zmiany właściwości programu MSBuild

Podczas uaktualniania projektu zaleca się usunięcie następujących właściwości programu MSBuild platformy UWP z pliku projektu:

WindowsXamlEnableOverview
AppxPackageSigningEnabled
GenerateAssemblyInfo

Należy również upewnić się, że architektury platformy w projekcie docelowym są określone przy użyciu następujących identyfikatorów środowiska uruchomieniowego platformy .NET:

<PropertyGroup>
   <!-- Used in .NET MAUI WinUI projects -->
   <Platforms>x86;x64;ARM64</Platforms>
</PropertyGroup>

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

Zmiany przestrzeni nazw

Istnieją różnice w nazwach przestrzeni nazw między platformami UWP i WinUI 3. W wielu przypadkach jest to tak proste, jak zmiana nazwy przestrzeni nazw, a następnie skompilowanie kodu. Na przykład należy zastąpić Windows.UI.Xaml przestrzeń nazw przestrzenią Microsoft.UI.Xaml nazw przestrzenią nazw. Podobnie należy zastąpić Windows.UI.Xaml.Controls przestrzeń nazw Microsoft.UI.Xaml.Controls przestrzenią nazw przestrzenią nazw.

Innym razem mapowanie trwa nieco więcej pracy, a w rzadkich przypadkach wymaga zmiany podejścia. Aby uzyskać więcej informacji, zobacz Mapowanie interfejsów API i bibliotek platformy UWP na zestaw SDK aplikacji systemu Windows.

Zmiany w interfejsie API

Musisz rozwiązać wszelkie zmiany interfejsu API, które mogą mieć wpływ na aplikację. Na przykład niektóre typy, metody i właściwości mogły zostać zmienione, przestarzałe lub usunięte. Aby uzyskać informacje na temat tego, co jest obsługiwane podczas uaktualniania projektu platformy UWP do systemu WinUI 3, zobacz Co jest obsługiwane podczas migracji z platformy UWP do systemu WinUI 3. Aby uzyskać informacje o mapowaniu funkcji i interfejsów API platformy UWP na interfejsy WinUI 3, zobacz Mapowanie funkcji platformy UWP na zestaw SDK aplikacji systemu Windows i mapowanie interfejsów API platformy UWP na zestaw SDK aplikacji systemu Windows.

Projekt może być zgodny z wcześniejszymi wersjami systemu operacyjnego, ustawiając $(SupportedOSPlatformVersion) właściwość w pliku projektu:

<PropertyGroup>
   <SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'windows'">10.0.19041.0</SupportedOSPlatformVersion>
</PropertyGroup>

Właściwość $(SupportedOSPlatformVersion) wskazuje minimalną wersję systemu operacyjnego wymaganą do uruchomienia aplikacji lub biblioteki. Jeśli nie określisz jawnie tej minimalnej wersji systemu operacyjnego środowiska uruchomieniowego w projekcie, zostanie ona domyślnie ustawiona na wersję platformy z programu Target Framework Moniker (TFM).

Jeśli projekt jest przeznaczony tylko dla systemu Windows, wystarczy pominąć warunek sprawdzania platformy i ustawić $(SupportedOSPlatformVersion) właściwość bezpośrednio:

<PropertyGroup>
   <SupportedOSPlatformVersion>10.0.19041.0</SupportedOSPlatformVersion>
</PropertyGroup>

Aby uzyskać więcej informacji na temat właściwości, zobacz Obsługa $(SupportedOSPlatformVersion) starszych wersji systemu operacyjnego.

Aby aplikacja mogła działać poprawnie w starszej wersji systemu operacyjnego, nie może wywołać interfejsów API, które nie istnieją w tej wersji systemu operacyjnego. Można jednak dodać osłony wokół wywołań do nowszych interfejsów API, aby były wywoływane tylko w przypadku uruchamiania w wersji systemu operacyjnego, która je obsługuje. Można to osiągnąć za IsWindowsVersionAtLeast pomocą metody :

if (OperatingSystem.IsWindowsVersionAtLeast(10))
{
    // Use the API here
}

Usuwanie plików

Następujące pliki, które znajdują się w projektach platformy UWP platformy Xamarin.Forms, nie istnieją w projektach WinUI 3:

MainPage.xaml i MainPage.xaml.cs
Assemblyinfo.cs
Default.rd.xml

W związku z tym należy usunąć te pliki, jeśli są one w projekcie WinUI 3. Każda wymagana logika biznesowa zawarta w tych plikach powinna zostać przeniesiona w innym miejscu.

Zmiany w pliku Package.appxmanifest

Należy wprowadzić następujące zmiany w pliku Package.appxmanifest zmigrowanego projektu:

Ustaw punkt wejścia aplikacji na $targetentrypoint$ . Aby uzyskać więcej informacji, zobacz Docelowy punkt wejścia.
runFullTrust Dodaj możliwość. Aby uzyskać więcej informacji, zobacz Uruchamianie możliwości pełnego zaufania.
Windows.Universal Dodaj rodziny urządzeń docelowych i .Windows.Desktop Aby uzyskać więcej informacji, zobacz Uniwersalna rodzina urządzeń docelowych i Rodzina urządzeń docelowych pulpitu.

Wprowadzenie tych zmian naprawia typowe błędy wdrażania aplikacji w systemie Windows.

Aby zapoznać się z przykładem zgodnego pliku Package.appxmanifest, zobacz Package.appxmanifest.

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.

Następne kroki

Uruchamianie aplikacji

Udostępnij za pośrednictwem