チュートリアル: C++/WinRT コンポーネントから .NET 5 プロジェクションを生成し、NuGet を配布するWalkthrough: Generate a .NET 5 projection from a C++/WinRT component and distribute the NuGet

このチュートリアルでは、 c#/winrt を使用して C++/winrt コンポーネント用の .net 5 プロジェクションを生成する方法、関連付けられた nuget パッケージを作成する方法、および .Net 5 c# コンソールアプリケーションから nuget パッケージを参照する方法について説明します。This walkthrough shows how to use C#/WinRT to generate a .NET 5 projection for a C++/WinRT component, create the associated NuGet package, and reference the NuGet package from a .NET 5 C# console application.

このチュートリアルの完全なサンプルは、GitHub から こちらからダウンロードできます。You can download the full sample for this walkthrough from GitHub here.

注意

このチュートリアルは、C#/WinRT (RC2) の最新プレビュー用に書かれています。This walkthrough is written for the latest preview of C#/WinRT (RC2). 今後の1.0 リリースでは、開発者エクスペリエンスの更新と改善が行われる予定です。We expect the upcoming 1.0 release to have further updates and improvements to the developer experience.

前提条件Prerequisites

このチュートリアルと対応するサンプルには、次のツールとコンポーネントが必要です。This walkthrough and the corresponding sample requires the following tools and components:

  • ユニバーサル Windows プラットフォーム開発ワークロードがインストールされたVisual Studio 16.8 Preview 3 (またはそれ以降)。Visual Studio 16.8 Preview 3 (or later) with the Universal Windows Platform development workload installed. [インストールの詳細 > ユニバーサル Windows プラットフォーム開発] で、[ C++ (v14x) ユニバーサル Windows プラットフォームツール] オプションをオンにします。In Installation Details > Universal Windows Platform development, check the C++ (v14x) Universal Windows Platform tools option.
  • .Net 5.0 RC2 SDK.NET 5.0 RC2 SDK.
  • C++/winrt VSIX extension for c++/winrt プロジェクトテンプレート。C++/WinRT VSIX extension for C++/WinRT project templates.

単純な C++/WinRT ランタイムコンポーネントを作成するCreate a simple C++/WinRT Runtime component

このチュートリアルを実行するには、最初に .NET 5 プロジェクションを作成する C++/WinRT コンポーネントが必要です。To follow this walkthrough, you must first have a C++/WinRT component for which to create a .NET 5 projection. このチュートリアルでは、GitHub の関連サンプルで Simplemのコンポーネント プロジェクトを 使用しますThis walkthrough uses the SimpleMathComponent project in the related sample from GitHub here. これは、 c++/WINRT VSIX 拡張機能を使用して作成されたWindows ランタイムコンポーネント (c++/winrt) プロジェクトです。This is a Windows Runtime Component (C++/WinRT) project that was created by using the C++/WinRT VSIX extension. 開発用コンピューターにプロジェクトをコピーした後、Visual Studio 2019 Preview でソリューションを開きます。After you copy the project to your development computer, open the solution in Visual Studio 2019 Preview.

このプロジェクトのコードは、次のヘッダーファイルに示されている基本的な算術演算の機能を提供します。The code in this project provides the functionality for basic math operations shown in the header file below.

// SimpleMath.h
...
namespace winrt::SimpleMathComponent::implementation
{
    struct SimpleMath: SimpleMathT<SimpleMath>
    {
        SimpleMath() = default;
        double add(double firstNumber, double secondNumber);
        double subtract(double firstNumber, double secondNumber);
        double multiply(double firstNumber, double secondNumber);
        double divide(double firstNumber, double secondNumber);
    };
}

C++/winrt コンポーネントを作成し、winmd ファイルを生成する方法の詳細については、「 c++/winrt を使用したコンポーネントの Windows ランタイム」を参照してください。For more detailed steps about creating a C++/WinRT component and generating a .winmd file, see Windows Runtime components with C++/WinRT.

注意

コンポーネントで IInspectable:: GetRuntimeClassName を実装する場合は、有効な WinRT クラス名を返す 必要があり ます。If you are implementing IInspectable::GetRuntimeClassName in your component, it must return a valid WinRT class name. C#/WinRT は相互運用にクラス名文字列を使用するため、不適切なランタイムクラス名は InvalidCastExceptionを発生させます。Because C#/WinRT uses the class name string for interop, an incorrect runtime class name will raise an InvalidCastException.

コンポーネントソリューションにプロジェクションプロジェクトを追加するAdd a projection project to the component solution

リポジトリからサンプルを複製した場合は、最初に Simplemのプロジェクション プロジェクトを削除して、チュートリアルの手順に従ってください。If you have cloned the sample from the repo, first delete the SimpleMathProjection project to follow the walkthrough step by step.

  1. ソリューションに新しい クラスライブラリ (.Net Core) プロジェクトを追加します。Add a new Class Library (.NET Core) project to your solution.

    1. ソリューションエクスプローラーで、ソリューションノードを右クリックし、 Add[ -> 新しいプロジェクトの追加] をクリックします。In Solution Explorer, right click your solution node and click Add -> New Project.
    2. [ 新しいプロジェクトの追加] ダイアログボックスで、[ クラスライブラリ (.net Core) ] プロジェクトテンプレートを検索します。In the Add New Project dialog box, search for the Class Library (.NET Core) project template. テンプレートを選択し、[ 次へ] をクリックします。Select the template and click Next.
    3. 新しいプロジェクトに「 Simplem」プロジェクション という名前を指定し、[ 作成] をクリックします。Name the new project SimpleMathProjection and click Create.
  2. 空の Class1.cs ファイルをプロジェクトから削除します。Delete the empty Class1.cs file from the project.

  3. C#/WinRT NuGet パッケージをインストールします。Install the C#/WinRT NuGet package.

    1. ソリューションエクスプローラーで、 Simplemのプロジェクションプロジェクトを右クリックし、[ NuGet パッケージの管理] を選択します。In Solution Explorer, right click your SimpleMathProjection project and select Manage NuGet Packages.
    2. Microsoft. Windows. CsWinRT NuGet パッケージを検索し、最新バージョンをインストールします。Search for the Microsoft.Windows.CsWinRT NuGet package and install the latest version.
  4. Simplemのコンポーネントプロジェクトにプロジェクト参照を追加します。Add a project reference to the SimpleMathComponent project. ソリューションエクスプローラーで、 Simplemのプロジェクションプロジェクトの下にある [依存関係] ノードを右クリックし、[プロジェクト参照の追加] を選択して、 simplemのコンポーネントプロジェクトを選択します。In Solution Explorer, right click the Dependencies node under the SimpleMathProjection project, select Add Project Reference, and select the SimpleMathComponent project.

    注意

    Visual Studio 16.8 Preview 4 以降を使用している場合は、手順 4. を完了した後でこのセクションを実行します。If you are using Visual Studio 16.8 Preview 4 or later, you are done with this section after completing step 4. Visual Studio 16.8 Preview 3 を使用している場合は、手順 5. も完了する必要があります。If you are using Visual Studio 16.8 Preview 3, you must also complete step 5.

  5. Visual Studio 16.8 Preview 3 を使用している場合: ソリューションエクスプローラーで、[ simplemのプロジェクション ] ノードをダブルクリックしてエディターでプロジェクトファイルを開き、ファイルに次の要素を追加して、ファイルを保存して閉じます。If you're using Visual Studio 16.8 Preview 3: In Solution Explorer, double-click the SimpleMathProjection node to open the project file in the editor, add the following elements to the file, and then save and close the file.

    <ItemGroup>
      <PackageReference Include="Microsoft.Net.Compilers.Toolset" Version="3.8.0-4.20472.6" />
    </ItemGroup>
    
    <PropertyGroup>
      <RestoreSources>
        https://api.nuget.org/v3/index.json;
        https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-tools/nuget/v3/index.json
      </RestoreSources>
    </PropertyGroup>
    

    これらの要素は、最新の C# コンパイラを含む、必要なバージョンの Microsoft.Net NuGet パッケージをインストールします。These elements install the required version of the Microsoft.Net.Compilers.Toolset NuGet package, which includes the latest C# compiler. このチュートリアルでは、これらのプロジェクトファイル参照を使用して、この NuGet パッケージをインストールします。これは、このパッケージの必要なバージョンが既定のパブリック NuGet フィードで利用できない可能性があるためです。This walkthrough has you install this NuGet package via these project file references because the required version of this package may not be available on the default public NuGet feed.

これらの手順を実行すると、 ソリューションエクスプローラー は次のようになります。After these steps, your Solution Explorer should look similar to this.

プロジェクションプロジェクトの依存関係を示すソリューションエクスプローラー

プロジェクトファイルを編集して C#/WinRT を実行するEdit the project file to execute C#/WinRT

cswinrt.exeを呼び出して射影アセンブリを生成する前に、射影プロジェクトのプロジェクトファイルを編集する必要があります。Before you can invoke cswinrt.exe and generate the projection assembly, you must edit the project file for the projection project.

  1. ソリューションエクスプローラーで、[ simplemのプロジェクション] ノードをダブルクリックして、エディターでプロジェクトファイルを開きます。In Solution Explorer, double-click the SimpleMathProjection node to open the project file in the editor.

  2. TargetFrameworkWindows SDK を参照するように要素を更新します。Update the TargetFramework element to reference the Windows SDK. これにより、相互運用とプロジェクションのサポートに必要なアセンブリ depedencies が追加されます。This adds assembly depedencies that are necessary for the interop and projection support. このサンプルでは、このチュートリアルの net 5.0-windows 10.0.19041.0 (SDK バージョン2004とも呼ばれます) の最新の Windows 10 リリースを対象としています。Our sample targets the latest Windows 10 release as of this walkthrough, net5.0-windows10.0.19041.0 (also known as SDK version 2004).

    <PropertyGroup>
      <TargetFramework>net5.0-windows10.0.19041.0</TargetFramework>
      <Platforms>x64</Platforms>
    </PropertyGroup>
    
  3. PropertyGroup複数のcswinrtプロパティを設定する新しい要素を追加します。Add a new PropertyGroup element that sets several cswinrt properties.

    <PropertyGroup>
      <CsWinRTIncludes>SimpleMathComponent</CsWinRTIncludes>
      <CsWinRTGeneratedFilesDir>$(OutDir)</CsWinRTGeneratedFilesDir>
    </PropertyGroup>
    

    この例の設定の詳細を次に示します。Here are some details about the settings in this example:

    • プロパティは、 CsWinRTIncludes プロジェクトに使用する名前空間を指定します。The CsWinRTIncludes property specifies which namespaces to project.
    • プロパティは、 CsWinRTGeneratedFilesDir プロジェクションからのファイルが生成される出力ディレクトリを設定します。これは、ソースからの構築に関する次のセクションで設定します。The CsWinRTGeneratedFilesDir property sets the output directory where files from the projection are generated, which we set in the following section on building out of source.
  4. このチュートリアルの最新の C#/WinRT バージョンでは、Windows メタデータの指定が必要になる場合があります。The latest C#/WinRT version as of this walkthrough may require specifying Windows Metadata. これは、C#/Winrtの今後のリリースで修正される予定です。This will be fixed in a future release of C#/WinRT. これは、次のいずれかの方法で指定できます。This can be supplied with either:

    • パッケージ参照 (たとえば、 Microsoft. Windows. SDK. contract.A package reference, such as to Microsoft.Windows.SDK.Contracts, or

    • 明示的な値は、プロパティを使用してを設定し CsWinRTWindowsMetadata ます。An explicit value set the with the CsWinRTWindowsMetadata property:

      <CsWinRTWindowsMetadata>10.0.19041.0</CsWinRTWindowsMetadata>
      
  5. Simplemの射影 .csprojファイルを保存して閉じます。Save and close the SimpleMathProjection.csproj file.

ソースからプロジェクトをビルドするBuild projects out of source

関連するサンプルでは、ビルドはディレクトリ. .. props ファイルで構成されます。In the related sample, the build is configured with the Directory.build.props file. SimplemのコンポーネントSimplemのプロジェクションプロジェクトの両方を構築するために生成されたファイルは、ソリューションレベルの _buildフォルダーに表示されます。The generated files from building both the SimpleMathComponent and SimpleMathProjection projects appear in the _build folder at the solution level. ソースからビルドするようにプロジェクトを構成するには、ソリューションファイルが格納されているディレクトリに以下の ディレクトリ をコピーします。To configure your projects to build out of source, copy the Directory.build.props file below to the directory containing your solution file.

<Project>
  <PropertyGroup>
    <BuildOutDir>$([MSBuild]::NormalizeDirectory('$(SolutionDir)_build', '$(Platform)', '$(Configuration)'))</BuildOutDir>
    <OutDir>$([MSBuild]::NormalizeDirectory('$(BuildOutDir)', '$(MSBuildProjectName)', 'bin'))</OutDir>
    <IntDir>$([MSBuild]::NormalizeDirectory('$(BuildOutDir)', '$(MSBuildProjectName)', 'obj'))</IntDir>
  </PropertyGroup>
</Project>

この手順は射影を生成するためには必要ありませんが、同じディレクトリ内の両方のプロジェクトからビルドファイルを生成し、ビルドのクリーンアップを簡単にすることによって簡単に実現できます。Although this step is not required to generate a projection, it provides simplicity by generating build files from both projects in the same directory and making build cleanup easier. ソースを使用しない場合は、各プロジェクトフォルダー内の異なるディレクトリに、 Simplemと interop assembly SimpleMathComponent.dll の両方が生成されることに注意してください。Note that if you do not build out of source, both SimpleMathComponent.winmd and the interop assembly SimpleMathComponent.dll will be generated in different directories in their respective project folders. これらのファイルは、次の nuspec で参照されます。そのため、パスはそれに応じて変更する必要があります。These files are both referenced in SimpleMathProjection.nuspec below, so the paths would have to be changed accordingly.

プロジェクションから NuGet パッケージを作成するCreate a NuGet package from the projection

相互運用機能アセンブリを配布して使用するには、追加のプロジェクトプロパティを追加して、ソリューションをビルドするときに NuGet パッケージを自動的に作成します。To distribute and use the interop assembly, you can automatically create a NuGet package when building the solution by adding some additional project properties. このパッケージには、必要な c#/Winrt ランタイムアセンブリの相互運用機能アセンブリと、c#/Winrt NuGet パッケージに対する依存関係が含まれます。This package will include the interop assembly and a dependency on the C#/WinRT NuGet package for the required C#/WinRT runtime assembly. このランタイムアセンブリには、.NET 5.0 ターゲットの winrt.runtime.dll という名前が付けられています。This runtime assembly is named winrt.runtime.dll for .NET 5.0 targets.

  1. Nuspec プロジェクトに NuGet 仕様 (...) ファイルを 追加しますAdd a NuGet spec (.nuspec) file to the SimpleMathProjection project.

    1. ソリューションエクスプローラーで、[ simplemのプロジェクション] ノードを右クリックし、[新しいフォルダーの追加] を選択 -> New Folderして、フォルダーに「 nuget」という名前を指定します。In Solution Explorer, right-click the SimpleMathProjection node, choose Add -> New Folder, and name the folder nuget.
    2. Nugetフォルダーを右クリックし、[新しい項目の追加] を選択し、 -> New ItemXML ファイルを選択して、 nuspecという名前を指定します。Right-click the nuget folder, choose Add -> New Item, choose the XML file, and name it SimpleMathProjection.nuspec.
  2. 次のを追加して、パッケージを自動的に生成するようにします。Add the following to SimpleMathProjection.csproj to automatically generate the package. これらのプロパティは、 NuspecFile NuGet パッケージを生成するディレクトリとディレクトリを指定します。These properties specify the NuspecFile and the directory to generate the NuGet package.

    <PropertyGroup>
      <GeneratedNugetDir>.\nuget\</GeneratedNugetDir>
      <NuspecFile>$(GeneratedNugetDir)SimpleMathProjection.nuspec</NuspecFile>
      <OutputPath>$(GeneratedNugetDir)</OutputPath>
      <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
    </PropertyGroup>
    
    
  3. Open the SimpleMathProjection.nuspec file to edit the package creation properties. Below is an example of a C++/WinRT component NuGet spec. Notice the dependency on CsWinRT for the net5.0 target framework moniker, as well as the target for lib\net5.0\SimpleMathProjection.dll, which points to the projection assembly SimpleMathComponent.dll instead of SimpleMathComponent.winmd. This behavior is new in .NET 5.0 and enabled by C#/WinRT.

    <?xml version="1.0" encoding="utf-8"?>
    <package xmlns="http://schemas.microsoft.com/packaging/2012/06/nuspec.xsd">
      <metadata>
        <id>SimpleMathComponent</id>
        <version>0.1.0-prerelease</version>
        <authors>Contoso Math Inc.</authors>
        <description>A simple component with basic math operations</description>
        <dependencies>
          <group targetFramework=".NETCoreApp3.0" />
          <group targetFramework="UAP10.0" />
          <group targetFramework=".NETFramework4.6" />
          <group targetFramework="net5.0">
            <dependency id="Microsoft.Windows.CsWinRT" version="0.8.0" exclude="Build,Analyzers" />
          </group>
        </dependencies>
      </metadata>
      <files>
        <!--Support net46+, netcore3, net5, uap, c++ -->
        <file src="..\..\_build\x64\Debug\SimpleMathComponent\bin\SimpleMathComponent\SimpleMathComponent.winmd" target="lib\netcoreapp3.0\SimpleMathComponent.winmd" />
        <file src="..\..\_build\x64\Debug\SimpleMathComponent\bin\SimpleMathComponent\SimpleMathComponent.winmd" target="lib\uap10.0\SimpleMathComponent.winmd" />
        <file src="..\..\_build\x64\Debug\SimpleMathComponent\bin\SimpleMathComponent\SimpleMathComponent.winmd" target="lib\net46\SimpleMathComponent.winmd" />
        <file src="..\..\_build\x64\Debug\SimpleMathProjection\bin\SimpleMathProjection.dll" target="lib\net5.0\SimpleMathProjection.dll" />
        <file src="..\..\_build\x64\Debug\SimpleMathComponent\bin\SimpleMathComponent\SimpleMathComponent.dll" target="runtimes\win10-x64\native\SimpleMathComponent.dll" />
      </files>
    </package>
    

ソリューションをビルドしてプロジェクションと NuGet パッケージを生成するBuild the solution to generate the projection and NuGet package

この時点で、ソリューションをビルドできるようになりました。ソリューションノードを右クリックし、[ ソリューションのビルド] を選択します。At this point you can now build the solution: right click on your solution node and select Build Solution. これにより、最初にコンポーネントプロジェクトがビルドされ、次に射影プロジェクトが作成されます。This will first build the component project and then the projection project. コンポーネントプロジェクトのメタデータファイルに加えて、interop .cs ファイルとアセンブリが出力ディレクトリに生成されます。The interop .cs files and assembly will be generated in the output directory, in addition to the metadata files from the component project. また、 nugetフォルダーで、生成された Nuget パッケージSimplem0.1.0 componentを確認することもできます。You will also be able to see the the generated NuGet package SimpleMathComponent0.1.0-prerelease.nupkg in the nuget folder.

投影の生成を示すソリューションエクスプローラー

C# .NET 5.0 コンソールアプリケーションで NuGet パッケージを参照するReference the NuGet package in a C# .NET 5.0 console application

投影された Simplemのコンポーネントを使用するには、アプリケーションに新しく作成された NuGet パッケージへの参照を追加するだけです。To consume the projected SimpleMathComponent, you can simply add a reference to the newly created NuGet package in your application. 次の手順では、別のソリューションで簡単なコンソールアプリを作成することによって、これを行う方法を示します。The following steps demonstrate how to do this by creating a simple Console app in a separate solution.

  1. コンソールアプリ (.Net Core) プロジェクトを使用して、新しいソリューションを作成します。Create a new solution with a Console App (.NET Core) project.

    1. Visual Studio で、 [ファイル] -> [新規] -> [プロジェクト] の順に選択します。In Visual Studio, select File -> New -> Project.
    2. [ 新しいプロジェクトの追加] ダイアログボックスで、[ コンソールアプリ (.net Core) ] プロジェクトテンプレートを検索します。In the Add New Project dialog box, search for the Console App (.NET Core) project template. テンプレートを選択し、[ 次へ] をクリックします。Select the template and click Next.
    3. 新しいプロジェクトに SampleConsoleApp という名前を指定し、[ 作成] をクリックします。Name the new project SampleConsoleApp and click Create. 新しいソリューションでこのプロジェクトを作成すると、 Simplemのコンポーネント NuGet パッケージを個別に復元することができます。Creating this project in a new solution allows you to restore the SimpleMathComponent NuGet package separately.
  2. ソリューションエクスプローラーで、[ SampleConsoleApp ] ノードをダブルクリックしてSampleConsoleAppプロジェクトファイルを開き、次の例に示すように、ターゲットフレームワークモニカーとプラットフォーム構成を更新します。In Solution Explorer, double-click the SampleConsoleApp node to open the SampleConsoleApp.csproj project file, and update the target framework moniker and platform configuration as shown in the following example.

    <PropertyGroup>
      <TargetFramework>net5.0-windows10.0.19041.0</TargetFramework>
      <Platforms>x64</Platforms>
    </PropertyGroup>
    
  3. SampleConsoleAppプロジェクトにSimplem コンポーネントNuGet パッケージを追加します。Add the SimpleMathComponent NuGet package to the SampleConsoleApp project. また、 VCRTForwarders NuGet パッケージも必要です。これは、msix パッケージにパッケージ化されていないアプリで必要になります。You will also need the Microsoft.VCRTForwarders.140 NuGet package, which is required in apps that are not packaged in an MSIX package. プロジェクトをビルドするときに Simplemのコンポーネント nuget を復元するには、 RestoreSources プロパティをコンポーネントソリューションの nuget フォルダーへのパスと共に使用します。To restore the SimpleMathComponent NuGet when building the project, you can use the RestoreSources property with the path to the nuget folder in your component solution.

    <PropertyGroup>
      <RestoreSources>
          https://api.nuget.org/v3/index.json;
          ../../CppWinRTProjectionSample/SimpleMathProjection/nuget
      </RestoreSources>
    </PropertyGroup>
    
    <ItemGroup>
        <PackageReference Include="Microsoft.VCRTForwarders.140" Version="1.0.6" />
        <PackageReference Include="SimpleMathComponent" Version="0.1.0-prerelease" />
    </ItemGroup>
    

    このチュートリアルでは、 Simplemare コンポーネント の NuGet 復元パスでは、両方のソリューションファイルが同じディレクトリにあることを前提としています。Note that for this walkthrough, the NuGet restore path for the SimpleMathComponent assumes that both solution files are in the same directory. または、 ローカルの NuGet パッケージフィード をソリューションに追加することもできます。Alternatively, you can add a local NuGet package feed to your solution.

  4. Program.csファイルを編集して、 Simplem コンポーネントによって提供される機能を使用します。Edit the Program.cs file to use the functionality provided by SimpleMathComponent.

    static void Main(string[] args)
    {
        var x = new SimpleMathComponent.SimpleMath();
        Console.WriteLine("Adding 5.5 + 6.5 ...");
        Console.WriteLine(x.add(5.5, 6.5).ToString());
    }
    
  5. コンソールアプリをビルドして実行します。Build and run the console app. 次の出力が表示されます。You should see the output below.

    Console NET5 の出力

リソースResources