次の方法で共有

C++/WinRT の概要

 

 

C++/WinRT は、Windows ランタイム (WinRT) API 用の完全に標準的な最新の C++17 言語プロジェクションであり、ヘッダー ファイル ベースのライブラリとして実装され、最新の Windows API へのファースト クラスのアクセスを提供するように設計されています。 C++/WinRT を使用すると、標準準拠の C++17 コンパイラを使用して Windows ランタイム API を作成および使用できます。 Windows SDK には C++/WinRT が含まれています。バージョン 10.0.17134.0 (Windows 10 バージョン 1803) で導入されました。

C++/WinRT は、C++/CX 言語プロジェクションと、Windows ランタイム C++ テンプレート ライブラリ (WRL)の代わりに推奨されます。 C++/WinRT に関する トピックの完全な一覧には、C++/CX および WRL との相互運用と移植の両方に関する情報が含まれています。

Von Bedeutung

注意すべき C++/WinRT の最も重要な部分の一部については、C++/WinRT に対する SDK サポート セクションと、C++/WinRT、XAML、VSIX 拡張機能、NuGet パッケージに対する Visual Studio のサポート セクションで説明されています。

また、「C++/WinRT サンプル アプリはどこにありますか?」も参照してください。.

言語プロジェクション

Windows ランタイムは、コンポーネント オブジェクト モデル (COM) API に基づいており、言語プロジェクションを介してアクセスするように設計されています。 プロジェクションでは COM の詳細が非表示になり、特定の言語に対してより自然なプログラミング エクスペリエンスが提供されます。

Windows ランタイム API リファレンス コンテンツの C++/WinRT 言語プロジェクション

Windows ランタイム API参照している場合は、右上にある [言語] コンボ ボックスをクリックし、C++/WinRT を選択して、C++/WinRT 言語プロジェクションに表示される API 構文ブロックを表示します。

C++/WinRT、XAML、VSIX 拡張機能、NuGet パッケージに対する Visual Studio のサポート

Visual Studio のサポートには、Visual Studio 2022、Visual Studio 2019、または Visual Studio 2017 (バージョン 15.6 以上、15.7 以上をお勧めします) が必要です。 Visual Studio インストーラー内から、ユニバーサル Windows プラットフォーム開発 ワークロードをインストールします。 インストールの詳細 ユニバーサル Windows プラットフォーム開発>で、まだ行っていない場合は、C++ (v14x) ユニバーサル Windows プラットフォームツールの オプションをチェックしてください。 また、Windows の設定>プライバシーとセキュリティ (Windows 10: 更新プログラムとセキュリティ) >開発者の場合は、[ 開発者モード ] オプション ([Windows 10: サイドロード アプリ ] オプションではなく) を有効にします。

Visual Studio と Windows SDK の最新バージョンでの開発をお勧めしますが、もし Windows SDK 10.0.17763.0 (Windows 10 バージョン 1809) より前のバージョンと共に提供される C++/WinRT を使用している場合は、上記の Windows 名前空間ヘッダーを使用するために、プロジェクトの Windows SDK のターゲットバージョンを最低 10.0.17134.0 (Windows 10 バージョン 1803) に設定する必要があります。

Visual Studio 2022 には、C++/WinRT プロジェクトと項目テンプレートが組み込まれており、C++/WinRT 開発をすぐに開始できます。 また、C++/WinRT 投影型の Visual Studio ネイティブ デバッグ視覚化 (natvis) も付属しています。C# デバッグと同様のエクスペリエンスを提供します。 Natvis はデバッグ ビルドに対して自動です。 詳細については、C++/WinRTの Visual Studio ネイティブ デバッグ視覚化 参照してください。

以前のバージョンの Visual Studio では、Visual Studio Marketplaceから最新バージョンの C++/WinRT Visual Studio Extension (VSIX) をダウンロードしてインストールする必要があります。

  • VSIX 拡張機能を使用すると、Visual Studio で C++/WinRT プロジェクトテンプレートと項目テンプレートを使用できます。
  • さらに、C++/WinRT の投影型に対する Visual Studio のネイティブなデバッグ視覚化 (natvis) も提供されます。

C++/WinRT 用の Visual Studio プロジェクト テンプレートについては、以下のセクションで説明します。 最新バージョンの VSIX 拡張機能がインストールされた新しい C++/WinRT プロジェクトを作成すると、新しい C++/WinRT プロジェクトによって、Microsoft.Windows.CppWinRT NuGet パッケージが自動的にインストールされます。 Microsoft.Windows.CppWinRT NuGet パッケージは、C++/WinRT ビルド サポート (MSBuild のプロパティとターゲット) を提供し、開発マシンとビルド エージェント (VSIX 拡張機能ではなく NuGet パッケージのみがインストールされている) の間でプロジェクトを移植できるようにします。

または、Microsoft.Windows.CppWinRT NuGet パッケージを手動でインストールして、既存のプロジェクトを変換することもできます。 VSIX 拡張機能の最新バージョンをインストール (または更新) した後、Visual Studio で既存のプロジェクトを開き、[プロジェクト] >[NuGet パッケージの管理]をクリックします。>の参照、検索ボックス Microsoft.Windows.CppWinRT の入力または貼り付けを行い、検索結果の項目を選択して インストール をクリックして、そのプロジェクトのパッケージをインストールします。 パッケージを追加すると、cppwinrt.exe ツールの呼び出しなど、プロジェクトに対する C++/WinRT MSBuild のサポートが得られます。

Von Bedeutung

1.0.190128.4 より前のバージョンの VSIX 拡張機能で作成 (または使用するためにアップグレード) されたプロジェクトがある場合は、VSIX 拡張機能の以前のバージョン を参照してください。 このセクションには、プロジェクトの構成に関する重要な情報が含まれています。VSIX 拡張機能の最新バージョンを使用するには、プロジェクトをアップグレードする必要があります。

  • C++/WinRT は C++17 標準の機能を使用するため、NuGet パッケージは Visual Studio で C/C++言語C++ 言語標準ISO C++17 Standard (/std:c++17) プロジェクト プロパティを設定します。
  • また、/bigobj コンパイラ オプションも追加されます。
  • を有効にするために、コンパイラ オプション co_await を追加します。
  • C++/WinRT codegen を出力するように XAML コンパイラに指示します。
  • 準拠モード 設定することもできます:はい (/permissive-)。これは、コードを標準に準拠するようにさらに制約します。
  • 注意すべきもう 1 つのプロジェクト プロパティは、C/C++>一般>警告をエラーとして扱うことです。 この設定は 『はい』(/WX) か 『いいえ』(/WX-) にしてください。 cppwinrt.exe ツールによって生成されたソース ファイルでは、実装を追加するまで警告が生成されることがあります。

上記のようにシステムを設定すると、Visual Studio で C++/WinRT プロジェクトを作成してビルドまたは開き、デプロイすることができます。

バージョン 2.0 以降、Microsoft.Windows.CppWinRT NuGet パッケージには、cppwinrt.exe ツールが含まれています。 ツールを Windows ランタイム メタデータ () ファイルにポイントして、C++/WinRT コードから使用するためにメタデータで説明されている API プロジェクトを するヘッダー ファイル ベースの標準 C++ ライブラリを生成できます。 Windows ランタイム メタデータ (.winmd) ファイルは、Windows ランタイム API サーフェスを記述する標準的な方法を提供します。 メタデータ cppwinrt.exe をポイントすることで、サードパーティの Windows ランタイム コンポーネントに実装されているランタイム クラス、または独自のアプリケーションに実装されているランタイム クラスで使用するライブラリを生成できます。 詳細については、「C++/WinRT での API の使用」を参照してください。

C++/WinRT では、COM スタイルのプログラミングに頼ることなく、標準の C++ を使用して独自のランタイム クラスを実装することもできます。 ランタイム クラスの場合は、IDL ファイルで型を記述すると、midl.exe と cppwinrt.exe が実装の定型コードのソースファイルを生成してくれます。 または、C++/WinRT 基底クラスから派生してインターフェイスを実装することもできます。 詳細については、「C++/WinRTを使用した API の作成 」を参照してください。

cppwinrt.exe ツールのカスタマイズ オプションの一覧については、プロジェクトのプロパティを使用して設定する、Microsoft.Windows.CppWinRT NuGet パッケージ readmeを参照してください。

プロジェクト内にインストールされている Microsoft.Windows.CppWinRT NuGet パッケージが存在することで、C++/WinRT MSBuild サポートを使用するプロジェクトを特定できます。

VSIX 拡張機能によって提供される Visual Studio プロジェクト テンプレートを次に示します。

空のアプリケーション (C++/WinRT)

XAML ユーザー インターフェイスを持つユニバーサル Windows プラットフォーム (UWP) アプリのプロジェクト テンプレート。

Visual Studio では、各 XAML マークアップ ファイルの背後にあるインターフェイス定義言語 (IDL) (.idl) ファイルから実装とヘッダー スタブを生成するための XAML コンパイラのサポートが提供されています。 IDL ファイルで、アプリの XAML ページで参照するローカル ランタイム クラスを定義し、プロジェクトを 1 回ビルドして、Generated Filesで実装テンプレートを生成し、Generated Files\sourcesのスタブ型定義を生成します。 次に、これらのスタブ型定義を参照用に使用して、ローカル ランタイム クラスを実装します。 ランタイム クラスを Midl ファイル (.idl)に分解する方法に関するページを参照してください。

Visual Studio for C++/WinRT での XAML デザイン サーフェイスのサポートは、C# と同等に近い状態です。 Visual Studio では、プロパティ ウィンドウの [イベント] タブを使用して、C++/WinRT プロジェクト内にイベント ハンドラーを追加できます。 コードにイベント ハンドラーを手動で追加することもできます。詳細については、「C++/WinRT のデリゲートを使用してイベントを処理する」を参照してください。

コア アプリ (C++/WinRT)

XAML を使用しないユニバーサル Windows プラットフォーム (UWP) アプリのプロジェクト テンプレート。

代わりに、Windows.ApplicationModel.Core 名前空間に C++/WinRT Windows 名前空間ヘッダーを使用します。 ビルドして実行した後、空のスペースをクリックして色付きの正方形を追加します。それから、色付きの正方形をクリックしてドラッグします。

Windows コンソール アプリケーション (C++/WinRT)

コンソール ユーザー インターフェイスを備えた Windows Desktop 用 C++/WinRT クライアント アプリケーション用のプロジェクト テンプレート。

Windows デスクトップ アプリケーション (C++/WinRT)

Windows Desktop 用の C++/WinRT クライアント アプリケーション用のプロジェクト テンプレート。Win32 MessageBox内に Windows ランタイム Windows.Foundation.Uri が表示されます。

Windows ランタイム コンポーネント (C++/WinRT)

コンポーネントのプロジェクト テンプレート。通常は、ユニバーサル Windows プラットフォーム (UWP) から使用します。

このテンプレートは、midl.exe>cppwinrt.exe ツールチェーンを示しています。このツールチェーンでは、Windows ランタイム メタデータ (.winmd) が IDL から生成され、実装とヘッダー スタブが Windows ランタイム メタデータから生成されます。

IDL ファイルで、コンポーネント内のランタイム クラス、既定のインターフェイス、およびコンポーネントが実装するその他のインターフェイスを定義します。 プロジェクトを 1 回ビルドして、module.g.cpp、module.h.cpp、Generated Filesの実装テンプレート、および Generated Files\sourcesのスタブ型定義を生成します。 次に、これらのスタブ型定義を参照用に使用して、コンポーネントにランタイム クラスを実装します。 ランタイム クラスを Midl ファイル (.idl)に分解する方法に関するページを参照してください。

ビルドされた Windows ランタイム コンポーネントバイナリとその .winmd を、それらを使用する UWP アプリとバンドルします。

VSIX 拡張機能の以前のバージョン

VSIX 拡張機能の最新バージョンをインストール (または更新) することをお勧めします。 既定では、それ自体を更新するように構成されています。 これを行い、1.0.190128.4 より前のバージョンの VSIX 拡張機能を使用して作成されたプロジェクトがある場合、このセクションには、新しいバージョンで動作するようにこれらのプロジェクトをアップグレードする方法に関する重要な情報が含まれています。 更新しない場合でも、このセクションの情報は役に立ちます。

サポートされている Windows SDK と Visual Studio のバージョンと Visual Studio の構成に関しては、上記の C++/WinRT、XAML、VSIX 拡張機能、および NuGet パッケージ セクションの Visual Studio のサポートに関する情報は、以前のバージョンの VSIX 拡張機能に適用されます。 以下の情報では、以前のバージョンで作成 (または使用するためにアップグレード) されたプロジェクトの動作と構成に関する重要な違いについて説明します。

1.0.181002.2 より前に作成されました

プロジェクトが 1.0.181002.2 より前のバージョンの VSIX 拡張機能で作成された場合、そのバージョンの VSIX 拡張機能には C++/WinRT ビルド サポートが組み込まれています。 プロジェクトには、<CppWinRTEnabled>true</CppWinRTEnabled> ファイルに .vcxproj プロパティが設定されています。

<Project ...>
    <PropertyGroup Label="Globals">
        <CppWinRTEnabled>true</CppWinRTEnabled>
...

プロジェクトをアップグレードするには、Microsoft.Windows.CppWinRT NuGet パッケージを手動でインストールします。 VSIX 拡張機能の最新バージョンをインストール (またはアップグレード) した後、Visual Studio でプロジェクトを開き、[プロジェクト>NuGet パッケージの管理...>参照をクリックし、検索ボックス Microsoft.Windows.CppWinRT を入力または貼り付け、検索結果の項目を選択して、インストール をクリックして、プロジェクトのパッケージをインストールします。

1.0.181002.2 から 1.0.190128.3 の間で作成 (またはアップグレード)

1.0.181002.2 から 1.0.190128.3 までのバージョンの VSIX 拡張機能を使用してプロジェクトが作成された場合は、プロジェクト テンプレートによって Microsoft.Windows.CppWinRT NuGet パッケージがプロジェクトに自動的にインストールされます。 以前のプロジェクトをアップグレードして、この範囲の VSIX 拡張機能のバージョンを使用している場合もあります。 その場合、ビルド サポートはこの範囲の VSIX 拡張機能のバージョンにも存在していたため、アップグレードされたプロジェクトで、Microsoft.Windows.CppWinRT NuGet パッケージがインストールされている場合とない場合があります。

プロジェクトをアップグレードするには、前のセクションの手順に従って、プロジェクトに Microsoft.Windows.CppWinRT NuGet パッケージ がインストールされていることを確認します。

無効なアップグレード構成

VSIX 拡張機能の最新バージョンでは、<CppWinRTEnabled>true</CppWinRTEnabled> NuGet パッケージもインストールされていない場合、プロジェクトが プロパティを持つことは無効です。 この構成のプロジェクトでは、ビルド エラー メッセージ "C++/WinRT VSIX ではプロジェクトビルドのサポートが提供されなくなりました。 Microsoft.Windows.CppWinRT Nuget パッケージにプロジェクト参照を追加してください。"

前述のように、C++/WinRT プロジェクトに NuGet パッケージがインストールされている必要があります。

<CppWinRTEnabled> 要素は廃止されているため、必要に応じて .vcxprojを編集し、要素を削除できます。 厳密には必要ではありませんが、オプションです。

また、.vcxproj に <RequiredBundles>$(RequiredBundles);Microsoft.Windows.CppWinRT</RequiredBundles>が含まれている場合は、C++/WinRT VSIX 拡張機能をインストールしなくてもビルドできるように削除できます。

C++/WinRT に対する SDK のサポート

現在は互換性上の理由だけで存在しますが、バージョン 10.0.17134.0 (Windows 10 バージョン 1803) 以降、Windows SDK には、ファースト パーティの Windows API (Windows 名前空間の Windows ランタイム API) を使用するためのヘッダー ファイルベースの標準 C++ ライブラリが含まれています。 これらのヘッダーは、%WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrtフォルダー内にあります。 Windows SDK バージョン 10.0.17763.0 (Windows 10 バージョン 1809) の時点で、これらのヘッダーはプロジェクトの $(GeneratedFilesDir) フォルダー内に自動的に生成されます。

互換性のために、Windows SDK には cppwinrt.exe ツールも付属しています。 ただし、cppwinrt.exe NuGet パッケージに含まれている最新バージョンの をインストールして使用することをお勧めします。 そのパッケージと cppwinrt.exeについては、上記のセクションで説明します。

C++/WinRT プロジェクションのカスタム型

C++/WinRT プログラミングでは、標準の C++ 言語機能と、一部の C++ 標準ライブラリ データ型を含む、標準 C++ データ型と C++/WinRTを使用できます。 ただし、プロジェクションの一部のカスタム データ型を認識し、それらを使用することもできます。 たとえば、「C++/WinRTの使用を開始する」のクイック スタート コード例では、winrt::hstring を使用します。

winrt::com_array は、ある時点で使用する可能性が高い別の種類です。 しかし、winrt::array_viewなどの型を直接使用する可能性は低くなります。 または、C++ 標準ライブラリに同等の型が出現した場合に変更するコードがないように、これを使用しないことを選択することもできます。

Warnung

特定の種類は、C++/WinRT の Windows 名前空間ヘッダーを詳しく調べると見つかることがあります。 たとえば、winrt::param::hstringですが、コレクションの例もあります。 これらは、入力パラメーターのバインドを最適化するためにのみ存在し、パフォーマンスが大幅に向上し、ほとんどの呼び出しパターンが関連する標準 C++ 型とコンテナーに対して "機能" します。 これらの型は、最も価値が高い場合にのみプロジェクションによって使用されます。 これらは高度に最適化されており、一般的には使用されません。それらを自分で使用する誘惑を受けないでください。 また、winrt::impl 名前空間からは何も使用しないでください。これは実装型であるため、変更される可能性があるためです。 引き続き標準の型、または winrt 名前空間からの型を使用する必要があります。

ABI 境界にパラメーターを渡す も参照してください。

重要な API