.NET アップグレード アシスタントを使用して UWP からWindows App SDKに移行する

.NET アップグレード アシスタント ( .NET アップグレード アシスタントの概要) は、Visual Studio拡張機能 (推奨) であり、コマンド ライン ツールであり、C# Universal Windows Platform (UWP) アプリを WinUI 3 アプリに移行するのに役立ちます。Windows App SDK。

.NET アップグレード アシスタントでの UWP サポートのロードマップには、ツールの強化、新機能の移行サポートの追加が含まれています。 .NET アップグレード アシスタントに関連する問題が見つかる場合は、Help>Send Feedback>問題の報告を選択して、Visual Studio内で問題を報告できます。

Upgrade Assistant GitHub リポジトリも参照してください。 そこには、このツールをコマンド ラインで実行するためのオプションが記載されています。

.NET アップグレード アシスタントをインストールする

.NET アップグレード アシスタントは、Visual Studio拡張機能として、または.NETコマンドライン ツールとしてインストールできます。 詳細については、「.NET アップグレード アシスタントのインストールを参照してください。

まとめ

.NET アップグレード アシスタントを使用して UWP アプリを移行する場合、ツールが実行する移行プロセスの手順とステージの概要を次に示します。

• 必要に応じて、projectをコピーし、コピーを移行します。元のprojectはそのままにします。
• 必要に応じて、プロジェクトをその場で移行します（フォルダー名を変更せずに、同じフォルダーとファイル内）して、コピーを作成しません。
• projectを .NET Framework project 形式から最新の .NET SDK project 形式にアップグレードします。
• NuGet パッケージ参照をクリーンアップします。 アプリによって参照されるパッケージに加えて、packages.config ファイルには、これらのパッケージの依存関係への参照が含まれています。 たとえば、パッケージ B に依存するパッケージ A への参照を追加した場合は、packages.config ファイルで両方のパッケージが参照されます。 新しいproject システムでは、パッケージ A への参照のみが必要です。 そのため、この手順ではパッケージ参照を分析し、必要なくなっているものを削除します。 アプリは引き続き .NET Framework アセンブリを参照しています。 これらのアセンブリのいくつかは、NuGet パッケージとして使用できる可能性があります。 そのため、この手順ではこれらのアセンブリを分析し、適切な NuGet パッケージを参照します。
• .NET 6 とWindows App SDKをターゲットにします。
• ターゲット フレームワーク モニカー (TFM) ( SDK スタイルのプロジェクトのターゲット フレームワークを参照) を .NET Framework から推奨される SDK に変更します。 たとえば、「 net6.0-windows 」のように入力します。
• ソース固有のコード変更を実行して、UWP ソース コードを WinUI for UWP から WinUI に移行します。
• テンプレート、構成、コード ファイルをすべて追加または更新します。 たとえば、必要な発行プロファイル App.xaml.cs、MainWindow.xaml.cs、MainWindow.xaml などを追加します。
• 名前空間を更新し、MainPage ナビゲーションを追加します。
• UWP と Windows App SDK の間で異なる API の検出と修正を試み、Task List TODO を使用して、サポートされなくなった API をマークします。

また、ツールの実行時には、ツールの出力内の警告メッセージの形式で移行ガイダンスを提供し、Task List TODO をprojectのソース コード内のコメントの形式で提供することも目的としています (たとえば、UWP ソース コードの完全に自動化された移行が不可能な場合など)。 一般的な [タスク一覧] TODO には、この移行ドキュメント内のトピックへのリンクが含まれます。 開発者は、常に移行プロセスを制御できます。

このツールでサポートされる機能

.NET アップグレード アシスタントのこのリリースは現在プレビュー段階であり、頻繁に更新プログラムを受け取る予定です。 このツールは現在、C# プログラミング言語のみをサポートしており、C++ はサポートされません。 また、ほとんどの場合、このリリースに伴い移行を完了するためには、あなたのプロジェクトに対して追加の作業が必要になります。

このツールは、プロジェクトとコードを移行してコンパイルできるようにすることを目的としています。 ただし、一部の機能では、それらを調査して修正する必要があります ([タスク一覧] TODO を使用)。 移行前の考慮事項の詳細については、「 UWP から WinUI に移行するときにサポートされる内容」を参照してください。

.NET アップグレード アシスタントの現在のリリースでは次の制限があるため、アプリを移行する前に将来のリリースを待つ場合があります。

• ApplicationView API からの移行はサポートされていません。
• AppWindow 関連の API からの移行はサポートされていません。

可能な場合、このツールは警告を生成しようと試み、意図的に、ユーザーによって変更されるまでコードがコンパイルされないようにします。

• カスタム ビューはサポートされていません。 たとえば、MessageDialog を拡張し、API を誤って呼び出すカスタム ダイアログに関する警告または修正を受け取ることはありません。
• Windows Runtime コンポーネントはサポートされていません。

• マルチウィンドウ アプリは正しく移行されない可能性があります。
• 標準外のファイル構造 (App.xaml や App.xaml.cs などがルートフォルダーにない) に従うプロジェクトは、正しく移行されない可能性があります。

Upgrade Assistant GitHub リポジトリには、トラブルシューティングのヒントと既知の問題が記載されています。 ツールの使用中に問題が見つかる場合は、同じGitHub リポジトリで報告し、UWP のエリア タグでタグ付けしてください。 それを心よりお待ちしています。

UWP PhotoLab サンプルを使用してツールを体験する

.NET アップグレード アシスタントを試してみましょう。

ソース 資料として、UWP PhotoLab サンプル アプリケーションを移行します。 PhotoLab は、画像ファイルを表示および編集するためのサンプル アプリです。 これにより、XAML レイアウト、データ バインディング、UI カスタマイズなどの機能が示されます。

1. まず、PhotoLab サンプル ソース コードを上のリンクから複製またはダウンロードします。

1. Visual Studioで PhotoLab ソリューションを開きます。

2. .NET アップグレード アシスタント拡張機能（このトピックの前半にある「.NET アップグレード アシスタントをインストールする」を参照）をインストールしたら、Solution Explorerでプロジェクトを右クリックし、Upgrade をクリックします。

3. プロジェクトを新しい .NET バージョンにアップグレードする オプションを選択します。

4. In-place project upgrade オプションを選択します。

5. ターゲット フレームワークを選択します。

6. [アップグレードの選択] をクリックします。

7. .NET アップグレード アシスタントが実行され、Visual Studio Output ウィンドウを使用して、情報と状態がそのまま出力されます。

アップグレード操作が完了するまで、進行状況バーを監視できます。

PhotoLab サンプル アプリのコード移行には、次のものが含まれます。

• コンテンツ ダイアログおよびファイル保存ピッカー API に対する変更。
• アニメーション パッケージの XAML 更新。
• タスクリスト TODO を 、DetailPage.xaml、DetailPage.xaml.cs、MainPage.xaml.cs に追加し、カスタムの戻るボタンに対する警告メッセージを表示する。
• XAML ボタンをカスタマイズするための戻るボタン機能の実装と [タスク一覧] TODO の追加。
• 戻るボタンの実装の詳細を確認するために使用できるドキュメントへのリンクが提供されます。

結果として得られる .csproj 内のバージョン番号は少し異なりますが、基本的には次のようになります (簡潔にするために、ビルド構成プロパティ グループの一部が削除されています)。

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
    <Platform Condition=" '$(Platform)' == '' ">x86</Platform>
    <OutputType>WinExe</OutputType>
    <DefaultLanguage>en-US</DefaultLanguage>
    <TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>
    <RuntimeIdentifiers>win-x86;win-x64;win-arm64</RuntimeIdentifiers>
    <UseWinUI>true</UseWinUI>
    <ApplicationManifest>app.manifest</ApplicationManifest>
    <EnableMsixTooling>true</EnableMsixTooling>
    <Platforms>x86;x64;arm64</Platforms>
    <PublishProfile>win10-$(Platform).pubxml</PublishProfile>
  </PropertyGroup>
  <ItemGroup>
    <AppxManifest Include="Package.appxmanifest">
      <SubType>Designer</SubType>
    </AppxManifest>
  </ItemGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.WindowsAppSDK" Version="1.1.0" />
    <PackageReference Include="Microsoft.Graphics.Win2D" Version="1.0.0.30" />
    <PackageReference Include="Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers" Version="0.4.346201">
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
    <PackageReference Include="Microsoft.Windows.Compatibility" Version="6.0.0" />
    <PackageReference Include="CommunityToolkit.WinUI.UI.Animations" Version="7.1.2" />
  </ItemGroup>
  <ItemGroup>
    <Compile Remove="App.xaml.old.cs" />
  </ItemGroup>
  <ItemGroup>
    <None Include="App.xaml.old.cs" />
  </ItemGroup>
</Project>

ご覧のように、projectは Windows App SDK、WinUI、.NET 6 を参照しています。 PhotoLab が移行されたので、WinUI アプリが提供する必要があるすべての新機能を利用し、プラットフォームを使用してアプリを拡張できます。

また、.NET アップグレード アシスタントは、アップグレード プロセスの続行に役立つアナライザーをprojectに追加します。 たとえば、Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers NuGet パッケージがあります。

フォローアップの手動での移行

この時点で、移行された PhotoLab ソリューションまたはprojectを開き、ソース コードで行われた変更を確認できます。 プロジェクトでは、WinUI バージョンがビルドされ、実行され、UWP バージョンと同様に動作するようにするために、接続作業を完了するためのもう少しの作業が必要です。

移行を手動で完了するためにアクションを実行する必要がある TODO については、Visual Studio (ViewTask List) の Task List を参照してください。

アプリの UWP (.NET Framework) バージョンに、projectが実際に使用していないライブラリ参照が含まれている可能性があります。 各参照を分析し、それが必要かどうかを判定する必要があります。 また、このツールによって、NuGet パッケージ参照が間違ったバージョンに追加またはアップグレードされた可能性もあります。

アップグレード アシスタントでは Package.appxmanifest が編集されないため、アプリを起動するには、次のいくつかの編集が必要になります。

1. ルートの <Package> 要素に次の名前空間を追加します。

xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities"

2. <Application> 要素を EntryPoint="appnamehere.App" から EntryPoint="$targetentrypoint$" に編集します。

3. 指定された Capability を次の内容に置き換えます。

<rescap:Capability Name="runFullTrust" />

.csproj ファイルでは、project ファイルを編集して、<OutputType>WinExe</OutputType> と <UseMaui>False</UseMaui> を設定することが必要な場合があります。

XAML コントロールの多くを使用するには、次の例のように、app.xaml ファイルに <XamlControlsResources> が含まれていることを確認してください。

<Application.Resources>
    <ResourceDictionary>
        <ResourceDictionary.MergedDictionaries>
            <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />
            <!-- Other merged dictionaries here -->
        </ResourceDictionary.MergedDictionaries>
        <!-- Other app resources here -->
    </ResourceDictionary>
</Application.Resources>

トラブルシューティングのヒント

.NET アップグレード アシスタントの使用時に発生する可能性がある既知の問題がいくつかあります。 場合によっては、.NET アップグレード アシスタントが内部で使用する try-convert ツールに関する問題があります。

ただし、トラブルシューティングのヒントや既知の問題については、Upgrade Assistant GitHub リポジトリを参照してください。

参照

• Windows App SDKおよびサポートされている Windows リリース