次の方法で共有

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 アプリケーション パッケージ プロジェクトが含まれています。

    新しいプロジェクトの作成ウィザードで [空のアプリ、パッケージ (Win UI in Desktop)] オプションが強調表示されているスクリーンショット。

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

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

    ターゲットおよび最小バージョン

  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 パッケージに組み込むためのパッケージ マニフェストも含まれます。

      Visual Studio で、ソリューション エクスプローラー ペインと、単一プロジェクト MSIX のメインの Windows XAML.CS ファイルの内容が表示されているスクリーンショット。

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

      Visual Studio で、ソリューション エクスプローラー ペインと、パッケージ アプリ x マニフェスト ファイルの内容を表示しているスクリーンショット。

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

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

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

      Note

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

      構成マネージャーで [配置] を有効にする

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

    [新しい項目の追加] ダイアログ ボックスで、[インストール済み]>[Visual C シャープの項目]>[Win U I] を選択し、[空白のページ] オプションが強調表示されているスクリーンショット。

  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 - appxmanifest ファイルが強調表示された状態で開いているソリューション エクスプローラー

  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 - C# アプリケーション デバッグ プロパティが強調表示された状態で起動ドロップダウン

      Visual Studio 2019 - ローカル Windows デバッガーのプロパティを起動するデバッガーが強調表示された C# アプリケーション プロパティ ページ

  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 スレッドモデルの再入不可能な動作が想定されている場合、コードが予測どおりに動作しない可能性があります。

関連項目