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

  • [アーティクル]

.NET アップグレード アシスタント (「.NET アップグレード アシスタントの概要」を参照) は Visual Studio 拡張機能 (推奨) であり、かつ C# ユニバーサル Windows プラットフォーム (UWP) アプリを、Windows App SDK を使用する Windows UI ライブラリ (WinUI) 3 アプリに移行するのに役立つコマンド ライン ツールです。

.NET アップグレード アシスタントでの UWP サポートのロードマップには、さらなるツールの改善と、新機能への移行サポートの追加が含まれます。 .NET アップグレード アシスタントに関連する問題が見つかった場合は、[ヘルプ]>[フィードバックの送信]>[問題の報告] の順に選択することによって、Visual Studio 内でそれらを提出できます。

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

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

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

まとめ

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

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

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

ヒント

このツールによって生成されたすべての TODO を表示するには、Visual Studio で [タスク一覧] を確認します。

Note

ツールの実行が完了した後、必要に応じて実行することを選択できるいくつかのフォローアップ手順があります。 コードを App.xaml.old.cs から App.xaml.cs に移動できます。また、ツールによって作成されたバックアップから AssemblyInfo.cs を復元できます。

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

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

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

.NET アップグレード アシスタントの現在のリリースには次の制限事項があるため、ユーザーは、アプリを移行する前に今後のリリースを待つことを選択する可能性があります。

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

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

  • カスタム ビューはサポートされていません。 たとえば、MessageDialog を拡張し、API を誤って呼び出すカスタム ダイアログに関する警告または修正を受け取ることはありません。
  • Windows ランタイム コンポーネントはサポートされていません。
  • マルチウィンドウ アプリは正しく移行されない可能性があります。
  • 非標準のファイル構造 (App.xaml や App.xaml.cs がルート フォルダー内に存在しないなど) に従うプロジェクトは正しく移行されない可能性があります。

アップグレード アシスタント GitHub リポジトリには、トラブルシューティングのヒントや既知の問題が記載されています。 このツールの使用中に何か問題が見つかった場合は、その同じ GitHub リポジトリで報告し、それに UWP の領域タグを付けてください。 それを心よりお待ちしています。

Note

移行プロセスに関するガイダンス (さらには、UWP と Windows App SDK の間での機能や API の違い) については、「UWP から Windows App SDK への移行」を参照してください。

ヒント

使用しているツールのバージョンは、コマンド upgrade-assistant --version を発行して確認できます。

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

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

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

Note

PhotoLab サンプルが完全に手動で移行されるケース スタディは、「UWP PhotoLab サンプル アプリの Windows App SDK の移行」で確認できます。

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

ヒント

このツールを使用してアプリの移行を自動化した後、移行を完了するには、追加の手動での作業が必要になることに注意してください。

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

  2. .NET アップグレード アシスタント拡張機能をインストールしたら (このトピックの前の部分にある「.NET アップグレード アシスタントをインストールする」を参照)、ソリューション エクスプローラーでプロジェクトを右クリックし、[アップグレード] をクリックします。

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

  4. [プロジェクトのインプレース アップグレード] オプションを選択します。

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

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

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

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

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

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

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

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net6.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>win10-x86;win10-x64;win10-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>

見てわかるように、このプロジェクトは Windows App SDK、WinUI 3、.NET 6 を参照するようになりました。 これで PhotoLab が移行されたので、WinUI 3 アプリが提供する必要のあるすべての新機能を利用して、プラットフォームと共にアプリを拡張できます。

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

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

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

移行を手動で完了するために対処する必要のある TODO については、Visual Studio の [タスク一覧] ([表示]>[タスク一覧]) を参照してください。

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

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

  1. ルートの <Package> 要素に次の名前空間を追加します。
xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities"

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

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

<rescap:Capability Name="runFullTrust" />

.csproj ファイルで、プロジェクト ファイルを編集して <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 ツールに問題が発生することがあります。

ただし、その他のトラブルシューティングのヒントや既知の問題については、アップグレード アシスタント GitHub リポジトリを参照してください。