Xamarin.Forms UWP プロジェクトの移行

[アーティクル]
05/14/2024

Xamarin.Forms UWP プロジェクトを WinUI 3 プロジェクトに更新するには、次の手順を実行する必要があります。

プロジェクトファイルを SDK スタイルに更新します。
名前空間を更新する
API の変更に対処する
互換性のない依存関係を .NET 8 バージョンに更新または置き換えます。
アプリをコンパイルしてテストします。

SDK スタイルのプロジェクトファイルに更新する

既存の Xamarin.Forms UWP プロジェクトは、SDK スタイルの WinUI 3 プロジェクトに更新できます。 .NET MAUI WinUI 3 アプリの SDK スタイルのプロジェクトは、次の例のようになります。

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

重要

ターゲットフレームワークモニカー (TFM) は、.NET (この場合は .NET 8) を使用するプロジェクトを表します。 SDK スタイルのプロジェクトのターゲットフレームワークの詳細については、「SDK スタイルのプロジェクトのターゲットフレームワーク」を参照してください。

.NET MAUI のサポートを有効にするには、プロジェクトファイルに追加 <UseMaui>true</UseMaui> する必要があります。さらに、プロジェクトファイルに追加 <EnableDefaultMauiItems>false</EnableDefaultMauiItems> したことを確認します。これにより、既に定義されているメソッドに関するビルドエラーが InitializeComponent 表示されなくなります。

MSBuild プロパティの変更

プロジェクトをアップグレードするときに、プロジェクトファイルから次の UWP MSBuild プロパティを削除することをお勧めします。

WindowsXamlEnableOverview
AppxPackageSigningEnabled
GenerateAssemblyInfo

また、ターゲットプロジェクトのプラットフォームアーキテクチャが、次の .NET ランタイム識別子で指定されていることを確認する必要もあります。

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

ランタイム識別子の詳細については、「.NET RID カタログ」を参照してください。

名前空間の変更

UWP と WinUI 3 の名前空間の名前には違いがあります。多くの場合、名前空間名を変更するのと同じくらい簡単で、コードがコンパイルされます。たとえば、名前空間を名前空間Microsoft.UI.Xamlに置き換えるWindows.UI.Xaml必要があります。同様に、名前空間を名前空間Microsoft.UI.Xaml.Controlsに置き換えるWindows.UI.Xaml.Controls必要があります。

マッピングに若干の追加作業が必要になり、まれにアプローチの変更が必要になることもあります。詳細については、「UWP API とライブラリをWindows アプリ SDKにマッピングする」を参照してください。

API の変更

アプリに影響する可能性がある API の変更に対処する必要があります。たとえば、一部の型、メソッド、およびプロパティの名前が変更、非推奨、または削除された可能性があります。 UWP プロジェクトを WinUI 3 にアップグレードするときにサポートされる内容については、「UWP から WinUI 3 への移行時にサポートされる内容」を参照してください。 UWP の機能と API を WinUI 3 にマッピングする方法については、「UWP 機能をWindows アプリ SDKにマッピングする」および「UWP API とライブラリをWindows アプリ SDKにマッピングする」を参照してください。

プロジェクトファイルでプロパティを設定 $(SupportedOSPlatformVersion) することで、プロジェクトを以前の OS バージョンと互換性を持つことができます。

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

$(SupportedOSPlatformVersion) プロパティにより、アプリまたはライブラリを実行するために必要な最小 OS バージョンを指定できます。プロジェクトでこの最小ランタイム OS バージョンを明示的に指定しない場合、既定ではターゲットフレームワークモニカー (TFM) のプラットフォームバージョンになります。

プロジェクトが Windows のみを対象とする場合は、プラットフォームのチェック条件を省略し、プロパティを直接設定するだけで$(SupportedOSPlatformVersion)十分です。

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

プロパティの詳細については、「以前の OS バージョンの$(SupportedOSPlatformVersion)サポート」を参照してください。

古い OS バージョンでアプリを正しく実行するには、そのバージョンの OS に存在しない API を呼び出すことはできません。ただし、新しい API の呼び出しにガードを追加して、その API がサポートされているバージョンの OS で実行する場合にのみ呼び出されるようにすることができます。これは、次の IsWindowsVersionAtLeast 方法で実現できます。

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

ファイルの削除

Xamarin.Forms UWP プロジェクトに存在する次のファイルは、WinUI 3 プロジェクトには存在しません。

MainPage.xaml と MainPage.xaml.cs
AssemblyInfo.cs
Default.rd.xml

したがって、WinUI 3 プロジェクト内にある場合は、これらのファイルを削除する必要があります。これらのファイルに含まれている必要なビジネスロジックは、他の場所に移動する必要があります。

Package.appxmanifest への変更

移行したプロジェクトの Package.appxmanifest ファイルに次の変更を加える必要があります。

アプリケーションのエントリポイントを〘に設定します $targetentrypoint$ 。詳細については、ターゲットエントリポイントを参照してください。
機能を追加します runFullTrust 。詳細については、「完全信頼機能の実行」を参照してください。
Windows.UniversalデバイスファミリとWindows.Desktopターゲットデバイスファミリを追加します。詳細については、「ユニバーサルターゲットデバイスファミリ」および「デスクトップターゲットデバイスファミリ」を参照してください。

これらの変更を行えば、Windows でのアプリの一般的な展開エラーが修正されます。

準拠している Package.appxmanifest ファイルの例については、「Package.appxmanifest」を参照してください。

ランタイムの動作

.NET 5 以降では、さまざまなプラットフォームでメソッドの動作が変更 String.IndexOf() されています。詳細については、「.NET グローバリゼーションと ICU」を参照してください。

次のステップ

アプリのブートストラップ

次の方法で共有

Xamarin.Forms UWP プロジェクトの移行

SDK スタイルのプロジェクトファイルに更新する

MSBuild プロパティの変更

名前空間の変更

API の変更

ファイルの削除

Package.appxmanifest への変更

ランタイムの動作

次のステップ

関連項目

その他のリソース

次の方法で共有

Xamarin.Forms UWP プロジェクトの移行

SDK スタイルのプロジェクト ファイルに更新する

MSBuild プロパティの変更

名前空間の変更

API の変更

ファイルの削除

Package.appxmanifest への変更

ランタイムの動作

次のステップ

関連項目

その他のリソース

SDK スタイルのプロジェクトファイルに更新する