WinUI 3 (Windows App SDK) プロジェクトを初めて作成する

このトピックでは、Visual Studio を使用して、Windows UI ライブラリ (WinUI) 3 ユーザー インターフェイス (UI) を持つ C# .NET または C++ アプリ用の新しい Windows App SDK プロジェクトを作成する方法について説明します。 また、結果として得られるプロジェクトのコード、その動作、およびそのしくみについても見ていきます。

完全インストールの詳細へのリンクは、以下の手順に記載されています。 Windows App SDKの最新の安定リリースをインストールしてターゲットにすることをお勧めします (安定チャネルのリリース ノートに関する記事をご覧ください)。

ヒント

インストールしてターゲットにする Windows App SDK のバージョン (または使用する Visual Studio のバージョン) に関係なく、そのバージョンのリリース ノートで "制限事項と既知の問題" を確認することが重要です (「Windows App SDK のリリース チャネル」をご覧ください)。 Windows App SDK のお使いのバージョンに関する "制限事項と既知の問題" について知ることで、このトピックの手順に従うときに、それらが発生するのを回避できます。

他の問題が発生した場合は、WindowsAppSDK GitHub リポジトリの GitHub イシューまたは [Discussions](ディスカッション) タブで、またはオンライン検索で、情報が見つかる可能性があります。

重要

UWP アプリで作業している場合は、「UWP から Windows App SDK に移行する」を参照してください。

主要な概念

パッケージ化は、すべての Windows App SDK プロジェクトの重要な考慮事項です。 必要に応じてこのセクションをスキップし、パッケージ化されていないプロジェクトを作成できます。 ただし、後で戻ってそれについての詳細を読んでください。

  • MSIX パッケージ作成ツール。 これは、MSIX テクノロジを使用してアプリをパッケージ化するプロセスです (「MSIX とは」を参照)。 MSIX はパッケージ形式で、これによりユーザーは最新の UI を使用してアプリを簡単にインストール、アンインストール、および更新できます。 また、MSIX パッケージ作成ツールは、特定の Windows 機能 (カスタム コンテキスト メニューの拡張など) に必要なパッケージ ID をアプリに指定します。
  • スパース パッケージ作成ツール。 この方法では、アプリが、その種類、呼び出し可能な API、およびレジストリやファイル システムへのアクセスに関して制限されないように、MSIX パッケージ化をオプトアウトします。 スパース パッケージ作成ツールでも、アプリにパッケージ ID が指定されるため、上記の Windows 機能を使用できます。 通常、スパース パッケージ化されたアプリは、.exe または .msi ファイルを使用してインストールおよび更新され、カスタム インストーラー、ClickOnce、または xcopy の展開が使用されます。
  • パッケージ化なし。 上記の理由により、MSIX パッケージ化をオプトアウトするまた別の方法。 ただし、パッケージ化されていないアプリにはパッケージ ID は含まれません。 通常、パッケージ化されないアプリは、.exe または .msi ファイルを使用してインストールおよび更新され、カスタム インストーラー、ClickOnce、または xcopy の展開が使用されます。

MSIX パッケージ化: MSIX パッケージ化された C# または C++ の WinUI 3 デスクトップ アプリ用に新しいプロジェクトを作成する

  1. 開発コンピューターをセット アップするには、「Windows App SDK 用のツールをインストールする」を参照してください。

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

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

  4. プロジェクト テンプレートとして [空のアプリ、パッケージ (WinUI 3 in Desktop)] を選択し、[次へ] をクリックします。 そのテンプレートで、WinUI 3 ベースのユーザー インターフェイスを使用したデスクトップ アプリが作成されます。 生成されるプロジェクトには、パッケージ マニフェストと、アプリを MSIX パッケージにビルドするために必要なその他のサポートが構成されています (「MSIX とは」を参照してください)。 このプロジェクト テンプレートの詳細については、「単一プロジェクト MSIX を使用してアプリをパッケージ化する」を参照してください。

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

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

  6. Visual Studio によって生成されるプロジェクトには、アプリのコードが含まれます。 App.xaml ファイルと分離コード ファイルで、実行中のアプリを表す Application 派生クラスが定義されます。 MainWindow.xaml ファイルと分離コード ファイルで、アプリによって表示されるメイン ウィンドウを表す MainWindow クラスが定義されます。 これらのクラスは、WinUI 3 に用意されている Microsoft.UI.Xaml 名前空間の型から派生します。

    このプロジェクトには、アプリを 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.

  7. アプリに新しい項目を追加するには、ソリューション エクスプローラーでプロジェクト ノードを右クリックし、[追加]>[新しい項目] を選択します。 [新しい項目の追加] ダイアログ ボックスで、 [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.

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

非 MSIX パッケージ化: 非 MSIX パッケージ化された C# または C++ の WinUI 3 デスクトップ アプリ用に新しいプロジェクトを作成する

  1. 開発コンピューターをセット アップするには、「Windows App SDK 用のツールをインストールする」を参照してください。

  2. Windows App SDK 用のダウンロード」から Windows App SDK の最新のインストーラーをダウンロードします。 これにより、ターゲット デバイスで非 MSIX パッケージ化されたアプリを実行して展開するために必要なランタイム パッケージの依存関係がインストールされます (「非パッケージ アプリ用 Windows App SDK 展開ガイド」を参照)。

  3. C++。 ターゲット デバイスのアーキテクチャに適した Microsoft Visual C++ 再頒布可能パッケージ (VCRedist) をインストールします。

    • 最新バージョンの VCRedist は、最新の Visual Studio 一般提供 (GA) リリース (つまり、プレビューではありません)、そして Windows App SDK バイナリを構築するために使用できるすべてのバージョンの Visual Studio と互換性があります。
    • Visual Studio の Insider ビルドにより、新しいバージョンの VCRedist がインストールされている可能性があります。パブリック バージョンを実行すると、次のエラーで失敗しますが、これは無視できます: エラー 0x80070666: Cannot install a product when a newer version is installed. (新しいバージョンがインストールされている場合、製品をインストールすることはできません。)

    Note

    VCRedist がターゲット デバイスにインストールされていない場合、c:\windows\system32\vcruntime140.dll への動的リンクは失敗します。 このエラーは、さまざまな方法でエンドユーザーにマニフェストとして表示することができます。

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

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

  6. XAML 診断を使用するには、MSIX パッケージ プロジェクトから始める必要があります。 そのため、プロジェクト テンプレートとして [空のアプリ、パッケージ (WinUI 3 in Desktop)] を選択し、[次へ] をクリックします。 .

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

    <Project ...>
      ...
      <PropertyGroup>
        ...
        <WindowsPackageType>None</WindowsPackageType>
      </PropertyGroup> 
      ...
    </Project>
    
  8. C++。 C++ プロジェクト (.vcxproj) ファイルで、AppxPackage プロパティを false に設定します。

    <Project ...>
      ...
      <PropertyGroup>
        ...
        <AppxPackage>false</AppxPackage>
        ...
      </PropertyGroup> 
      ...
    </Project>
    
  9. C#。 Visual Studio から (デバッグありまたはデバッグなしで) C# アプリを開始するには、[スタート] ドロップダウンから "[非パッケージ]" 起動プロファイルを選択します。 "[パッケージ]" プロファイルを選択すると、Visual Studio に展開エラーが表示されます。 この手順は、コマンド ラインまたは Windows エクスプローラーからアプリケーション (.exe) を開始する場合は必要ありません。

    Visual Studio - Start drop-down with C# application unpackaged launch profile highlighted

  10. ビルドして実行します。

ブートストラップ API

<WindowsPackageType>None</WindowsPackageType> プロジェクト プロパティを設定すると、"自動初期化子" では、アプリに最も適したバージョンの Windows App SDK を見つけて読み込みます。

高度なニーズ (カスタム エラー処理や、特定のバージョンの Windows App SDK の読み込みなど) がある場合は、代わりにブートストラップ API を明示的に呼び出すことができます。 詳細については、非 MSIX パッケージ アプリ用の Windows App SDK ランタイムを使用するに関する記事と「チュートリアル - Windows App SDK を使用する MSIX パッケージ化されていないアプリでブートストラップ API を使用する」を参照してください。

ブートストラップの詳細については、フレームワーク依存のアプリ向け展開アーキテクチャと概要に関する記事を参照してください。

プロジェクト テンプレートのコードを確認する

このチュートリアルでは、[Blank App, Packaged (WinUI 3 in Desktop)](空のアプリ、パッケージ (WinUI 3 in Desktop)) プロジェクト テンプレートを使用します。これにより、WinUI 3 ベースのユーザー インターフェイスを使用してデスクトップ アプリが作成されます。 そのテンプレートに付属しているコードとその機能について見ていきましょう。 使用できる WinUI 3 プロジェクト テンプレートと項目テンプレートの詳細については、「Visual Studio での WinUI 3 テンプレート」を参照してください。

アプリのエントリ ポイント

Windows オペレーティング システム (OS) がアプリを実行すると、OS はアプリの "エントリ ポイント" で実行を開始します。 このエントリ ポイントは、Main (または C++/WinRT の場合は wWinMain) 関数の形式をとります。 通常、新しいプロジェクトでは、その関数は Visual Studio ビルド プロセスによって自動生成されるように構成されます。 既定では非表示になっているので、これを気にかける必要はありません。 ただし、詳細について "知りたい" 場合は、「Main または wWinMain での単一インスタンス化」を参照してください。

App クラス

アプリ全体は、通常単に App と呼ばれるクラスによって表されます。 このクラスは、App.xaml およびその分離コード ファイル (App.xaml.cs、または App.xaml.h および .cpp) で定義されています。 App は、WinUI 3 の Microsoft.UI.Xaml.Application クラスから派生します。

エントリ ポイントで生成されたコードは、App のインスタンスを作成し、それを実行するように設定します。

App のコンストラクターで、InitializeComponent メソッドが呼び出されていることがわかります。 このメソッドは、基本的に、XAML マークアップである App.xaml の内容を解析します。 これが重要なのは、App.xaml には、実行中のアプリが使用するための、解決してディクショナリに読み込む必要があるマージされたリソースが含まれているためです。

App のもう 1 つの興味深いメソッドは OnLaunched です。 ここでは、MainWindow クラスの新しいインスタンスを作成してアクティブ化します (以下を参照してください)。

MainWindow クラス

アプリによって表示されるメイン ウィンドウは、当然ながら MainWindow クラスによって表されます。 このクラスは、MainWindow.xaml およびその分離コード ファイル (MainWindow.xaml.cs、または MainWindow.xaml.h および .cpp) で定義されています。 MainWindow は、WinUI 3 の Microsoft.UI.Xaml.Window クラスから派生します。

MainWindow のコンストラクターは、独自の InitializeComponent メソッドを呼び出します。 ここでも、そのジョブは、MainWindow.xaml 内の XAML マークアップをユーザー インターフェイス (UI) オブジェクトのグラフに変換することです。

MainWindow.xaml に、MainWindow の基本的なレイアウトが表示されます。 レイアウト ルートには、Microsoft.UI.Xaml.Controls.StackPanel という名前の動的パネルがあります。 レイアウト パネルの詳細については、「レイアウト パネル」を参照してください。

StackPanel の内部に、Microsoft.UI.Xaml.Controls.Button があります。 その Button は、マークアップ Click="myButton_Click" を使用して、Click イベントのイベント ハンドラー メソッドを宣言的にフックします。

このメソッドは myButton_Click という名前であり、そのメソッドの実装は、MainWindow.xaml.cs または MainWindow.xaml.cpp で確認することができます。 その中では、ボタンの内容が既定の "Click Me" から "Clicked" に変更されます。

C++。 C++ プロジェクトを作成した場合は、MainWindow.idl ファイルも表示されます。 詳細については、C++/WinRT のドキュメントを参照してください。 「XAML コントロール; C++/WinRT プロパティへのバインド」は、.idl ファイルの目的と使用方法について学習を開始するのに適しています。

次のステップ

Windows App SDK を使用して開発作業を続行するには、「Windows デスクトップ アプリの開発」を参照してください。