Migrace projektu UPW pro Xamarin.Forms

Článek
05/14/2024

Pokud chcete aktualizovat projekt Xamarin.Forms UPW na projekt WinUI 3, měli byste:

Aktualizujte soubor projektu tak, aby byl ve stylu sady SDK.
Aktualizace oborů názvů
Řešení jakýchkoli změn rozhraní API
Aktualizujte nebo nahraďte nekompatibilní závislosti verzemi .NET 8.
Zkompilujte a otestujte aplikaci.

Aktualizace souboru projektu ve stylu sady SDK

Stávající projekt Xamarin.Forms UPW je možné aktualizovat na existující projekt WinUI 3 ve stylu sady SDK. Projekt ve stylu sady SDK pro aplikaci .NET MAUI WinUI 3 je podobný následujícímu příkladu:

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

Důležité

Moniker cílové architektury (TFM) označuje projekt jako použití .NET v tomto případě .NET 8. Informace o cílových architekturách v projektech ve stylu sady SDK naleznete v tématu Cílové architektury v projektech ve stylu sady SDK.

Pokud chcete povolit podporu .NET MAUI, musíte ho přidat <UseMaui>true</UseMaui> do souboru projektu. Kromě toho se ujistěte, že jste do souboru projektu přidali <EnableDefaultMauiItems>false</EnableDefaultMauiItems> . Tím přestanete dostávat chyby sestavení týkající se InitializeComponent již definované metody.

Změny vlastností nástroje MSBuild

Při upgradu projektu se doporučuje z souboru projektu odebrat následující vlastnosti NÁSTROJE MSBuild pro UPW:

WindowsXamlEnableOverview
AppxPackageSigningEnabled
GenerateAssemblyInfo

Budete také muset zajistit, aby architektury platformy v cílovém projektu byly zadány s následujícími identifikátory modulu runtime .NET:

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

Další informace o identifikátorech modulu runtime naleznete v tématu Katalog identifikátorů RID technologie .NET.

Změny oboru názvů

Existují rozdíly v názvech oborů názvů mezi UPW a WinUI 3. V mnoha případech je to stejně snadné jako změna názvu oboru názvů a pak se váš kód zkompiluje. Budete například muset nahradit Windows.UI.Xaml obor názvů oborem Microsoft.UI.Xaml názvů. Podobně budete muset obor názvů nahradit Windows.UI.Xaml.Controls oborem Microsoft.UI.Xaml.Controls názvů.

Jindy mapování trvá trochu více práce a ve výjimečných případech vyžaduje změnu přístupu. Další informace najdete v tématu Mapování rozhraní API a knihoven UPW na sadu Windows App SDK.

Změny rozhraní API

Budete muset vyřešit všechny změny rozhraní API, které můžou mít vliv na vaši aplikaci. Například některé typy, metody a vlastnosti byly přejmenovány, zastaralé nebo odebrány. Informace o tom, co je podporováno při upgradu projektu UPW na WinUI 3, najdete v tématu Co je podporováno při migraci z UPW na WinUI 3. Informace o mapování funkcí a rozhraní API upW na WinUI 3 najdete v tématu Mapování funkcí UPW na rozhraní API a mapování rozhraní API pro UPW pro Windows App SDK a knihovny pro Windows App SDK.

Projekt je možné provést kompatibilní s dřívějšími verzemi operačního systému nastavením $(SupportedOSPlatformVersion) vlastnosti v souboru projektu:

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

Tato $(SupportedOSPlatformVersion) vlastnost označuje minimální verzi operačního systému potřebnou ke spuštění aplikace nebo knihovny. Pokud ve svém projektu explicitně nezadáte tuto minimální verzi operačního systému runtime, nastaví se výchozí verze platformy z monikeru cílového rozhraní (TFM).

Pokud váš projekt cílí jenom na Windows, stačí vynechat podmínku kontroly platformy a nastavit $(SupportedOSPlatformVersion) vlastnost přímo:

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

Další informace o $(SupportedOSPlatformVersion) vlastnosti naleznete v tématu Podpora starších verzí operačního systému.

Aby aplikace fungovala správně ve starší verzi operačního systému, nemůže volat rozhraní API, která v této verzi operačního systému neexistují. Můžete ale přidat stráže kolem volání novějších rozhraní API, aby se volala pouze při spuštění na verzi operačního systému, která je podporuje. Toho lze dosáhnout pomocí IsWindowsVersionAtLeast metody:

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

Odebrání souborů

Následující soubory, které jsou přítomné v projektech Xamarin.Forms UPW, neexistují v projektech WinUI 3:

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

Proto byste tyto soubory měli odebrat, pokud jsou v projektu WinUI 3. Veškerá požadovaná obchodní logika obsažená v těchto souborech by se měla přesunout jinam.

Změny souboru Package.appxmanifest

V souboru Package.appxmanifest vašeho migrovaného projektu musí být provedeny následující změny:

Nastavte vstupní bod aplikace na $targetentrypoint$ hodnotu . Další informace naleznete v tématu Cílový vstupní bod.
runFullTrust Přidejte funkci. Další informace najdete v tématu Spuštění úplné možnosti důvěryhodnosti.
Přidejte rodiny cílovýchzařízeních Windows.UniversalWindows.Desktop Další informace najdete v tématu Řada univerzálních cílových zařízení a řada cílových zařízení pro stolní počítače.

Provedením těchto změn opravíte běžné chyby nasazení vaší aplikace ve Windows.

Příklad kompatibilního souboru Package.appxmanifest naleznete v tématu Package.appxmanifest.

Chování modulu runtime

V rozhraní .NET 5 nebo novějších na různých platformách dochází ke String.IndexOf() změnám chování metody. Další informace najdete v tématu globalizace .NET a ICU.

Další kroky

Spuštění aplikace

Sdílet prostřednictvím