C#/WinRT

C#/WinRT は、C# 言語のWindows Runtime (WinRT) プロジェクション サポートを提供する NuGet パッケージ ツールキットです。 プロジェクション アセンブリは相互運用機能アセンブリであり、ターゲット言語に対して自然で使い慣れた方法で WinRT API をプログラミングできます。 C#/WinRT プロジェクションでは、C# インターフェイスと WinRT インターフェイス間の相互運用の詳細が隠され、文字列、URI、共通値型、ジェネリック コレクションなど、多くのWinRT 型と適切な.NETの対応へのマッピングが提供されます。

現在、C#/WinRT では、.NETで Target Framework Monikers (TFM) を使用して WinRT API を使用するためのサポートが提供されています。 特定の Windows SDK バージョンで TFM を設定すると、C#/WinRT によって生成された Windows SDK プロジェクションアセンブリとランタイム アセンブリへの参照が追加されます。

C#/WinRT NuGet パッケージを使用するとcreateとreference.NETコンシューマー用の独自の WinRT 相互運用機能アセンブリを使用できます。 最新の C#/WinRT バージョンには、C# での WinRT 型 の作成のプレビュー も含まれています。

詳細については、C#/WinRT GitHub リポジトリを参照してください。

C#/WinRT の動機

.NET (旧称 .NET Core) は、デバイス、クラウド、IoT アプリケーションの構築に使用できるオープンソースのクロスプラットフォーム ランタイムです。

以前のバージョンの .NET Framework と .NET Core には、Windows 固有のテクノロジである WinRT に関する組み込みの知識がありました。 .NET 6 以降の移植性と効率性の目標をサポートするために、WinRT プロジェクションのサポートを.NETコンパイラとランタイムから解除し、C#/WinRT ツールキットに移動しました ( WinRT の組み込みサポートは .NET)。 C#/WinRT の目的は、以前のバージョンの C# コンパイラと .NET ランタイムによって提供される組み込みの WinRT サポートと同等の機能を提供することです。 詳細については、Windows Runtime型の.NETマッピングを参照してください。

C#/WinRT では、WinUI 3 を含む Windows App SDK のコンポーネントもサポートされています。 このWindows App SDKは、Microsoft のネイティブ UI コントロールとその他のネイティブ コンポーネントをオペレーティング システムから引き上げます。 これにより、アプリ開発者は、Windows 10 バージョン 1809 以降のリリースで最新のコントロールとコンポーネントを使用できます。

最後に、C#/WinRT は一般的なツールキットであり、C# コンパイラまたは .NET ランタイムで WinRT の組み込みサポートが利用できない他のシナリオをサポートすることを目的としています。

新着情報

最新の C#/WinRT リリースは、Github リポジトリの リリース ノート ページにあります。

Usage

C#/WinRT NuGet パッケージを使用すると、WinRT コンポーネントから C# プロジェクション (相互運用アセンブリとも呼ばれます) と Authoring C#/WinRT コンポーネントの両方を生成できます。 C#/WinRT の使用シナリオの詳細については、リポジトリの usage ガイドを参照してください。

相互運用機能アセンブリを生成して配布する

WinRT API は、Windows メタデータ (WinMD) ファイルで定義されています。 C#/WinRT NuGet パッケージ (Microsoft.Windows.CsWinRT) には C#/WinRT コンパイラ cswinrt.exe が含まれており、これを使用して WinMD ファイルを処理し、.NET C# コードを生成できます。 C#/WinRT は、C++ 言語プロジェクションのヘッダーを C++/WinRT で 生成する方法と同様に、これらのソース ファイルを相互運用機能アセンブリにコンパイルします。 その後、C#/WinRT 相互運用機能アセンブリと、.NET アプリケーションが参照する実装アセンブリ (通常は NuGet パッケージ) を配布できます。

相互運用機能アセンブリを生成して配布する方法の詳細については、「C++/WinRT コンポーネントから C# プロジェクションを生成し、.NET アプリの NuGet として配布するを参照してください。

相互運用アセンブリを参照する

通常、C#/WinRT 相互運用機能アセンブリはアプリケーション プロジェクトによって参照されます。 ただし、中間相互運用機能アセンブリによって順番に参照される場合もあります。 たとえば、WinUI 相互運用機能アセンブリは、Windows SDK 相互運用機能アセンブリを参照します。

公式の相互運用機能アセンブリを使用せずにサードパーティの WinRT コンポーネントを配布する場合、アプリケーション projectは、相互運用機能アセンブリを生成して独自のプライベート プロジェクション ソースを生成する手順に従うことができます。 この方法は、プロセス内で同じ型の競合するプロジェクションを生成する可能性があるため、お勧めしません。 セマンティック バージョン管理スキームに従った NuGet パッケージは、これを防ぐために設計されています。 公式のサード パーティの相互運用機能アセンブリが推奨されます。

WinRT 型の埋め込みサポート (プレビュー)

C#/WinRT バージョン 1.4.1 以降では、.NETと .NET Standard 2.0 の両方の Windows SDK プロジェクションソースとランタイム ソースをライブラリまたはアプリの出力に埋め込むためのサポートが含まれています。 これは、Windows SDK の種類の使用が自己完結型である場合に便利です。 埋め込みサポートにより、WinRT.Runtime.dll と Microsoft.Windows.SDK.NET.dll への依存関係が削除され.NET.dllライブラリまたはアプリの出力サイズが小さくなります。 また、ライブラリ開発者はダウンレベルのサポートを提供でき、マルチターゲットの必要がなくなります。

詳細については、リポジトリの C#/WinRT 埋め込みドキュメントを参照してください。

WinRT 型のアクティブ化

C#/WinRT では、オペレーティング システムによってホストされる WinRT 型のアクティブ化と、 Win2D などのサードパーティコンポーネントがサポートされています。 デスクトップ アプリケーションでのサードパーティ コンポーネントのライセンス認証のサポートは、Windows 10 バージョン 1903 以降で利用可能な、登録無料の WinRT ライセンス認証 ( Windows Runtime コンポーネントを使用したパッケージ化されていないデスクトップ アプリ を参照) で有効になります。 ネイティブ C++ コンポーネントでは、project プロパティまたは ファイルを使用して、Windows Desktop Compatible プロパティを .vcxproj に設定する必要があります。 Microsoft.VCLibs.Desktop バイナリを参照して、使用するアプリに転送します。 それ以外の場合、コンポーネントが UWP アプリのみを対象とする場合は、アプリを使用することによって VCRT フォワーダー パッケージが必要になります。

C#/WinRT では、前述のように Windows が型のアクティブ化に失敗した場合も、アクティブ化フォールバック パスが提供されます。 この場合、C#/WinRT は完全修飾型名に基づいてネイティブ実装 DLL を検索し、要素を段階的に削除しようとします。 たとえば、フォールバック ロジックは、次のモジュールから Contoso.Controls.Widget 型を順番にアクティブ化しようとします。

1. Contoso.Controls.Widget.dll
2. Contoso.Controls.dll
3. Contoso.dll

C#/WinRT では 、LoadLibrary 代替検索順序 を使用して実装 DLL を検索します。 このフォールバック動作に依存するアプリでは、実装 DLL をアプリ モジュールと共にパッケージ化する必要があります。

一般的なエラーとトラブルシューティング

• エラー: "Windows メタデータが指定されていないか、検出されませんでした。"

  Windows メタデータは、<CsWinRTWindowsMetadata> project プロパティを使用して指定できます。次に例を示します。

  <CsWinRTWindowsMetadata>10.0.19041.0</CsWinRTWindowsMetadata>
  

  C#/WinRT バージョン 1.2.1 以降では、このプロパティの既定値は TargetPlatformVersion で、 TargetFramework プロパティで指定された Windows SDK バージョンから派生します。

• エラー CS0246: 型または名前空間名 'Windows' が見つかりませんでした (using ディレクティブまたはアセンブリ参照がありませんか?)

  このエラーに対処するには、 <TargetFramework> プロパティを編集して、特定の Windows バージョンをターゲットにします。次に例を示します。

  <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
  

  プロパティの指定の詳細については、<TargetFramework>に関するドキュメントを参照してください。

• System.InvalidCastException の理由は、属性を持つインターフェイスへのキャスト時に起こる

  ComImport属性を持つインターフェイスにオブジェクトをキャストする場合は、明示的な.As<>を使用する代わりに、演算子を使用する必要があります。 例えば次が挙げられます。

  someObject.As<SomeComImportInterface>
  

  詳細については、COM 相互運用ガイドを参照してください。

• System.Runtime.InteropServices.COMException: クラスが登録されていません (0x80040154 (REGDB_E_CLASSNOTREG))

  • C++/WinRT コンポーネントから C#/WinRT プロジェクションを使用するときにこの例外が発生する場合は、コンポーネントで、project プロパティまたは ファイルを使用して、Windows Desktop Compatible プロパティが .vcxproj に設定されていることを確認します。

.NET SDK のバージョン管理エラー

いずれかの依存関係よりも前の.NET SDK バージョンでビルドされたprojectで、次のエラーまたは警告が発生する可能性があります。

これらのエラーを修正するには、.NET SDK を最新バージョンに更新します。 これにより、アプリケーションで使用されるランタイムと Windows SDK アセンブリのバージョンが、すべての依存関係と互換性があることを確認できます。 ランタイムの修正にはアセンブリ バージョンの更新が必要になる場合があるため、これらのエラーは、.NET SDK の早期サービス/機能更新プログラムで発生する可能性があります。

既知の問題

既知の問題と重大な変更は、C#/WinRT GitHub リポジトリで確認できます。

C#/WinRT NuGet パッケージ、cswinrt.exe コンパイラ、または生成されたプロジェクション ソースで機能的な問題が発生した場合は、C#/WinRT の問題ページを使用して問題を送信してください。

その他のリソース

• C#/WinRT GitHub リポジトリ