Windows App SDK のプレビュー チャネルと試験段階チャネルを使用する WinUI 3 アプリを作成する

  • [アーティクル]

Windows App SDK に含まれる WinUI 3 プロジェクト テンプレートを使用することで、WinUI ベースの完全なユーザー インターフェイスを備えたデスクトップ アプリを作成できます。 これらのプロジェクト テンプレートを使用してアプリを作成すると、アプリケーションのユーザー インターフェイス全体が、WinUI 3 で提供されるウィンドウ、コントロール、その他の種類の UI を使用して実装されます。 プロジェクト テンプレートの完全な一覧については、「Visual Studio での WinUI 3 テンプレート」を参照してください。

Windows App SDK の安定バージョンを使用する: Windows App SDK の安定バージョンを使用して WinUI 3 アプリを構築するには、「最初の WinUI 3 プロジェクトを作成する」を参照してください。

[前提条件]

この記事で説明されている WinUI 3 プロジェクト テンプレートを使用するには、開発用コンピューターを構成して、Visual Studio 用の Windows App SDK 拡張機能をインストールします。 詳細については、「Windows App SDK のプレビューおよび試験的チャネル用ツールをインストールする」を参照してください。

Note

CoreWindow、ApplicationView、CoreApplicationView、CoreDispatcher などの WinRT の特定の基本的な型およびそれらの依存関係は、デスクトップ アプリでは使用できません。 これらの型は、UWP アプリの UI シナリオ専用に設計されており、スレッド モデルや他のプラットフォームの違いにより、デスクトップ アプリでは正しく動作しません。 推奨される代替 API などの詳細については、「デスクトップ アプリでサポートされていない Windows ランタイム API」を参照してください。

WinUI 3 パッケージ化されたデスクトップ アプリの手順

MSIX パッケージ作成ツールを使用して WinUI 3 アプリケーションを作成するには、プロジェクト言語と、インストールした Windows App SDK のバージョンに応じて、次の手順のいずれかを選択してください。

Windows App SDK 1.0 Preview 3 を使用して、C# で WinUI 3 デスクトップ アプリを作成するには:

  1. Visual Studio で、[ファイル] ->[新規] ->[プロジェクト] の順に選びます。

  2. プロジェクトのドロップダウン フィルターで、 [C#] 、 [Windows] 、および [WinUI] をそれぞれ選択します。

  3. 次のプロジェクトの種類のいずれかを選択し、 [次へ] をクリックします。

    • Blank App, Packaged (WinUI 3 in Desktop) (空のアプリ、パッケージ (デスクトップの WinUI 3)) : WinUI ベースのユーザー インターフェイスを使用するデスクトップ C# .NET アプリを作成します。 生成されるプロジェクトには、パッケージ マニフェストと、アプリを MSIX パッケージにビルドするために必要なその他のサポートが構成されており、別のパッケージ プロジェクトを使用する必要はありません。 このプロジェクトの種類の詳細については、「単一プロジェクト MSIX を使用してアプリをパッケージ化する」を参照してください。

      Note

      Visual Studio 2019 と共に Windows App SDK 1.0 Preview 2 をインストールした場合、このプロジェクト テンプレートには、ビルド エラーが発生する既知の問題があります。 この問題を解決するには、Windows App SDK 1.0 Preview 2 をインストールした後に、Single-project MSIX Packaging Tools for Visual Studio 2019 VSIX 拡張機能をインストールしてください。

    • Blank App, Packaged with WAP (WinUI 3 in Desktop) (空のアプリ、WAP を使用したパッケージ (デスクトップの WinUI 3)): WinUI ベースのユーザー インターフェイスを使用するデスクトップ C# .NET アプリを作成します。 生成されるソリューションには、アプリを MSIX パッケージに組み込むよう構成されている別の Windows アプリケーション パッケージ プロジェクトが含まれています。

    Screenshot of Create a new project wizard with the Blank App Packaged (Win UI in Desktop) option highlighted.

  4. プロジェクト名を入力し、必要に応じてその他のオプションを選択して、 [作成] をクリックします。

  5. 次のダイアログ ボックスで、 [ターゲット バージョン] を Windows 10 バージョン 2004 (ビルド 19041) に、 [最小バージョン] を Windows 10 バージョン 1809 (ビルド 17763) に設定し、 [OK] をクリックします。

    Target and Min Version

  6. この時点で、Visual Studio により、1 つ以上のプロジェクトが生成されます。

    • <プロジェクト名> (デスクトップ) : このプロジェクトには、アプリのコードが格納されています。 App.xaml ファイルと App.xaml.cs 分離コード ファイルでは、アプリ インスタンスを表す Application クラスが定義されます。 MainWindow.xaml ファイルと MainWindow.xaml.cs 分離コード ファイルでは、アプリによって表示されるメイン ウィンドウを表す MainWindow クラスが定義されます。 これらのクラスは、WinUI に用意されている Microsoft.UI.Xaml 名前空間の型から派生します。

      Blank App, Packaged (WinUI 3 in Desktop) (空のアプリ、パッケージ (デスクトップの WinUI 3)) プロジェクト テンプレートを使用した場合、このプロジェクトにはアプリを MSIX パッケージに組み込むためのパッケージ マニフェストも含まれます。

      Screenshot of Visual Studio showing the Solution Explorer pane and the contents of the Main Windows X A M L dot C S file for single project M S I X.

    • プロジェクト名 (パッケージ) : このプロジェクトは、Blank App, Packaged with WAP (WinUI 3 in Desktop) (空のアプリ、WAP を使用したパッケージ (デスクトップの WinUI 3)) プロジェクト テンプレートを使用した場合にのみ生成されます。 このプロジェクトは、アプリを MSIX パッケージに組み込むように構成されている Windows アプリケーション パッケージ プロジェクトです。 このプロジェクトは、アプリのパッケージ マニフェストを格納しており、既定では、ソリューションのスタートアップ プロジェクトになります。

      Screenshot of Visual Studio showing the Solution Explorer pane and the contents of the Package app x manifest file.

  7. 構成マネージャーでプロジェクトの配置を有効にします。 これらの手順で配置を有効にしないと、開発用コンピューター上でプロジェクトを実行またはデバッグしようとすると、次のようなエラーが発生します。"The project needs to be deployed before we can debug. Please enable Deploy in the Configuration Manager" (デバッグする前にプロジェクトを配置する必要があります。構成マネージャーで配置を有効にしてください).

    1. [ビルド] ->[構成マネージャー] を選択します。

    2. 構成マネージャーで、構成とプラットフォームの組み合わせごとに [配置] チェック ボックスをクリックします (たとえば、 [デバッグ] と [x86] 、 [デバッグ] と [arm64] 、 [リリース] と [x64] など)。

      Note

      [配置] チェックボックスと同じ行にある [構成] と [プラットフォーム] のドロップダウンではなく、上部にある [アクティブ ソリューション構成] と [アクティブ ソリューション プラットフォーム] のドロップダウンを必ず使用してください。

      Enabling Deploy in Configuration Manager

  8. アプリ プロジェクトに新しい項目を追加するには、ソリューション エクスプローラーで [<プロジェクト名> (デスクトップ)] プロジェクト ノードを右クリックし、[追加] ->[新しい項目] の順に選択します。 [新しい項目の追加] ダイアログ ボックスで、 [WinUI] タブを選択し、追加する項目を選択して、 [追加] をクリックします。 使用可能な項目の詳細については、「Visual Studio での WinUI 3 テンプレート」を参照してください。

    Screenshot of the Add New Item dialog box with the Installed > Visual C sharp Items > Win U I selected and the Blank Page option highlighted.

  9. 開発用コンピューター上でソリューションをビルドして実行し、アプリがエラーなしで動作することを確認します。

WinUI デスクトップ アプリをローカライズする

WinUI デスクトップ アプリで複数の言語をサポートし、ご自分のパッケージ プロジェクトが適切にローカライズされるようにするには、適切なリソースをそのプロジェクトに追加し (「アプリ リソースとリソース管理システム」を参照)、サポート対象となる各言語をプロジェクトの package.appxmanifest ファイルで宣言します。 プロジェクトをビルドすると、指定した言語が生成されたアプリ マニフェスト (AppxManifest.xml) に追加され、対応するリソースが使用されます。

  1. テキスト エディターで .wapproj の package.appxmanifest を開き、次のセクションを探します。

    <Resources>
    <Resource Language="x-generate"/>
</Resources>

  2. <Resource Language="x-generate"> を、サポートされている各言語の <Resource /> 要素に置き換えます。 たとえば、次のマークアップにより、"en-US" および "es-ES" のローカライズされたリソースが使用可能であることが指定されます。

    <Resources>
    <Resource Language="en-US"/>
    <Resource Language="es-ES"/>
</Resources>

パッケージ化されていない WinUI 3 デスクトップ アプリの手順

Note

WinUI 3 でのパッケージ化されていないアプリのサポートは、現在はプレビュー段階であり、運用環境ではサポートされていません。 プロジェクト テンプレートを取得し、WinUI 3 を使用してパッケージ化されていないデスクトップ アプリをビルドするには、Visual Studio 用の Windows App SDK Preview 拡張機能をダウンロードする必要があります。 既知の問題の一覧については、Windows App SDK 1.0 Preview 3 リリース ノートを参照してください。

MSIX パッケージ作成ツールを使用せずに WinUI 3 アプリケーションを作成するには、プロジェクト言語と、インストールした Windows App SDK のバージョンに応じて、次の手順のいずれかを選択してください。

Windows App SDK 1.0 Preview 3 を使用して、C# で WinUI 3 デスクトップ アプリを作成するには:

  1. 単一プロジェクトの MSIX パッケージ作成ツールをインストールします。

  2. お使いの Visual Studio のバージョンに応じて、Visual Studio 2019 C# 拡張機能または Visual Studio 2022 C# 拡張機能をインストールします。

  3. Windows App SDK ランタイムと MSIX パッケージをインストールします。 これらは、アプリを実行してデプロイするために必要です。

  4. [Blank App, Packaged (WinUI 3 in Desktop)](空のアプリ、パッケージ (WinUI 3 in Desktop)) プロジェクト テンプレートを使用して新しいアプリを作成します。 パッケージ アプリから始めるには、XAML 診断を使用する必要があります。

  5. .csproj (C#) または .vcxproj (C++) ファイルのどちらかのプロジェクト ファイルに次のプロパティを追加します。

    <Project ...>
  ...
  <PropertyGroup>
    ...
    <WindowsPackageType>None</WindowsPackageType>
  </PropertyGroup> 
  ...
</Project>

  6. package.appxmanifest をプロジェクトから削除します。

    そうしないと、"プロジェクト構成が正しくありません: WindowsPackageType は [なし] に設定されていますが、AppxManifest が指定されています" というエラーが表示されます。

    Note

    このファイルをファイルシステムから手動で削除するには、Visual Studio ソリューションを閉じる必要がある場合があります。 Visual Studio 2019 - Solution explorer open with appxmanifest file highlighted

  7. Visual Studio でデバッグするには、デバッグ プロパティを 'MsixPackage' から 'Project' に変更します。 そうしないと、"プロジェクトでは、プロファイルを実行する方法が不明です ..." というエラーが表示されます。

    Note

    これは、コマンド ラインまたは Windows エクスプローラーからアプリケーション (.exe) を実行する場合は必要ありません。

    • Visual Studio 2022 の場合: launchSettings.json を開き、プロファイルの 'MsixPackage' を 'Project' に変更します。

      {
    "profiles": {
        "Preview3": {
            "commandName": "Project"
        }
    }
}

    • Visual Studio 2019 および Visual Studio 2022 の場合: Visual Studio UI を使用して起動設定を変更できます。

      デバッグ プロパティを開き、起動プロファイルを 'Project' に変更します。

      Visual Studio 2019 - Start drop down with C# application debug properties highlighted

      Visual Studio 2019 - C# Application property page with debugger to launch property of Local Windows Debugger highlighted

  8. まだ行っていない場合は、Windows App SDK ランタイムと MSIX パッケージをインストールします。これは、アプリを実行してデプロイするために必要です。

    最新のインストーラーと MSIX パッケージのダウンロード

  9. ビルドして実行します。 追加のデプロイ情報については、外部の場所でパッケージ化されたアプリおよびパッケージ化されていないアプリをデプロイするための Windows アプリ SDK チュートリアル (「チュートリアル: Windows App SDK を使用する、外部の場所でパッケージ化されたアプリまたはパッケージ化されていないアプリでブートストラップ API を使用する」) を参照してください。 そのチュートリアルでは、ブートストラップ API (「外部の場所でパッケージ化されたアプリまたはパッケージ化されていないアプリの Windows App SDK ランタイムを使用する」を参照) を使用して、アプリが Windows アプリ SDK および WinUI 3 API を使用できるように、Windows アプリ SDK ランタイムを初期化する方法について説明します。

ASTA から STA へのスレッド モデル

既存の UWP アプリから、Windows App SDK を使用する新しい WinUI 3 プロジェクトにコードを移行する場合は、新しいプロジェクトで、UWP アプリで使用されるアプリケーション STA (ASTA) スレッド モデルではなく、シングルスレッド アパートメント (STA) スレッド モデルが使用されることに注意してください。 コードで ASTA スレッドモデルの再入不可能な動作が想定されている場合、コードが予測どおりに動作しない可能性があります。

関連項目