Пошаговое руководство. Создание проекции .NET 5 из компонента C++/WinRT и распространение NuGetWalkthrough: Generate a .NET 5 projection from a C++/WinRT component and distribute the NuGet

В этом пошаговом руководстве показано, как использовать C#/WinRT для создания проекции .NET 5 для компонента C++/WinRT, создания связанного пакета NuGet и ссылки на пакет NuGet из консольного приложения C# для .NET 5.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.

Полный пример для этого пошагового руководства можно скачать здесь.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:

  • Visual Studio 16,8 Preview 3 (или более поздней версии) с установленной рабочей нагрузкой универсальная платформа Windows Development.Visual Studio 16.8 Preview 3 (or later) with the Universal Windows Platform development workload installed. В сведениях об установке > универсальная платформа Windows разработкеустановите флажок средства универсальная платформа Windows C++ (v14x) .In Installation Details > Universal Windows Platform development, check the C++ (v14x) Universal Windows Platform tools option.
  • Пакет SDK для .net 5,0 RC2..NET 5.0 RC2 SDK.
  • Расширение VSIX c++/WinRT для шаблонов проектов c++/WinRT.C++/WinRT VSIX extension for C++/WinRT project templates.

Создание простого компонента среды выполнения/WinRT C++Create a simple C++/WinRT Runtime component

Для выполнения этого пошагового руководства необходимо сначала создать компонент C++/WinRT, для которого создается проекция .NET 5.To follow this walkthrough, you must first have a C++/WinRT component for which to create a .NET 5 projection. В этом пошаговом руководстве используется проект симплемаскомпонент в связанном примере из GitHub отсюда.This walkthrough uses the SimpleMathComponent project in the related sample from GitHub here. Это проект Среда выполнения Windows Component (C++/WinRT) , который был создан с помощью расширения c++/WinRT VSIX.This is a Windows Runtime Component (C++/WinRT) project that was created by using the C++/WinRT VSIX extension. После копирования проекта на компьютер разработки откройте решение в предварительной версии Visual Studio 2019.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 см. в разделе Среда выполнения Windows Components with C++/WinRT.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

Если вы выполнили клонирование примера из репозитория, сначала удалите проект симплемаспрожектион , чтобы выполнить пошаговое руководство по шагам.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. В Обозреватель решенийщелкните правой кнопкой мыши узел решения и выберите команду Добавить -> Новый проект.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. Назовите новый проект симплемаспрожектион и нажмите кнопку создать.Name the new project SimpleMathProjection and click Create.
  2. Удалите пустой файл Class1.CS из проекта.Delete the empty Class1.cs file from the project.

  3. Установите пакет NuGet для C#/WinRT.Install the C#/WinRT NuGet package.

    1. В Обозреватель решенийщелкните правой кнопкой мыши проект Симплемаспрожектион и выберите Управление пакетами NuGet.In Solution Explorer, right click your SimpleMathProjection project and select Manage NuGet Packages.
    2. Найдите пакет NuGet Microsoft. Windows. ксвинрт и установите последнюю версию.Search for the Microsoft.Windows.CsWinRT NuGet package and install the latest version.
  4. Добавьте ссылку на проект в проект симплемаскомпонент .Add a project reference to the SimpleMathComponent project. В Обозреватель решенийщелкните правой кнопкой мыши узел зависимости в проекте Симплемаспрожектион , выберите Добавить ссылку на проекти выберите проект симплемаскомпонент .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: в Обозреватель решенийдважды щелкните узел симплемаспрожектион , чтобы открыть файл проекта в редакторе, добавьте в файл следующие элементы, а затем сохраните и закройте файл.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>
    

    Эти элементы устанавливают требуемую версию пакета NuGet Microsoft.NET. compilers. Toolset , который включает последний компилятор C#.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#/WinRTEdit 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. В Обозреватель решенийдважды щелкните узел симплемаспрожектион , чтобы открыть файл проекта в редакторе.In Solution Explorer, double-click the SimpleMathProjection node to open the project file in the editor.

  2. Обновите TargetFramework элемент, чтобы он ссылался на Windows SDK.Update the TargetFramework element to reference the Windows SDK. Это добавляет сборку зависимости, которая необходима для поддержки взаимодействия и проекции.This adds assembly depedencies that are necessary for the interop and projection support. В нашем примере в этом пошаговом руководстве предназначен последний выпуск Windows 10, net 5.0 — Windows 10.0.19041.0 (также известный как пакет SDK версии 2004).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 элемент, который задает несколько свойств ксвинрт .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#/Винрт.This will be fixed in a future release of C#/WinRT. Это можно указать с помощью следующих действий:This can be supplied with either:

    • Ссылка на пакет, например Microsoft. Windows. SDK. Contractsили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. Сохраните и закройте файл симплемаспрожектион. csproj .Save and close the SimpleMathProjection.csproj file.

Сборка проектов вне исходного кодаBuild projects out of source

В связанном примересборка настраивается с помощью файла Directory. Build. props .In the related sample, the build is configured with the Directory.build.props file. Созданные файлы из сборки проектов симплемаскомпонент и симплемаспрожектион отображаются в папке _build на уровне решения.The generated files from building both the SimpleMathComponent and SimpleMathProjection projects appear in the _build folder at the solution level. Чтобы настроить построение проектов для построения из источника, скопируйте файл Directory. Build. props ниже в каталог, содержащий файл решения.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. Обратите внимание, что если не построить исходный код, то симплемаскомпонент. winmd и сборка взаимодействия 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. Этот пакет будет включать сборку взаимодействия и зависимость от пакета NuGet C#/WinRT для необходимой сборки среды выполнения/WinRT C#.This package will include the interop assembly and a dependency on the C#/WinRT NuGet package for the required C#/WinRT runtime assembly. Эта сборка среды выполнения называется winrt.runtime.dll для целевых объектов .NET 5,0.This runtime assembly is named winrt.runtime.dll for .NET 5.0 targets.

  1. Добавьте файл спецификации NuGet (. nuspec) в проект симплемаспрожектион .Add a NuGet spec (.nuspec) file to the SimpleMathProjection project.

    1. В Обозреватель решенийщелкните правой кнопкой мыши узел симплемаспрожектион , выберите команду добавить -> новую папкуи присвойте папке имя NuGet.In Solution Explorer, right-click the SimpleMathProjection node, choose Add -> New Folder, and name the folder nuget.
    2. Щелкните правой кнопкой мыши папку NuGet , выберите команду Добавить -> новый элемент, выберите XML-файл и назовите его симплемаспрожектион. nuspec.Right-click the nuget folder, choose Add -> New Item, choose the XML file, and name it SimpleMathProjection.nuspec.
  2. Добавьте следующий элемент в симплемаспрожектион. csproj , чтобы автоматически создать пакет.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>
    

Создание решения для создания проекции и пакета NuGetBuild 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 симплемаскомпонент 0.1.0-RELEASE. nupkg в папке NuGet .You will also be able to see the the generated NuGet package SimpleMathComponent0.1.0-prerelease.nupkg in the nuget folder.

обозреватель решений, показывающий создание проекции

Ссылка на пакет NuGet в консольном приложении C# .NET 5,0Reference the NuGet package in a C# .NET 5.0 console application

Чтобы использовать предполагаемый симплемаскомпонент, можно просто добавить ссылку на только что созданный пакет 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. Назовите новый проект самплеконсолеапп и нажмите кнопку создать.Name the new project SampleConsoleApp and click Create. Создание этого проекта в новом решении позволяет восстановить пакет NuGet симплемаскомпонент отдельно.Creating this project in a new solution allows you to restore the SimpleMathComponent NuGet package separately.
  2. В Обозреватель решенийдважды щелкните узел самплеконсолеапп , чтобы открыть файл проекта самплеконсолеапп. csproj , и обновите моникер целевой платформы и конфигурацию платформы, как показано в следующем примере.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. Добавьте пакет NuGet симплемаскомпонент в проект самплеконсолеапп .Add the SimpleMathComponent NuGet package to the SampleConsoleApp project. Также потребуется пакет NuGet Microsoft. вкртфорвардерс. 140 , который необходим в приложениях, которые не упакованы в пакет MSIX.You will also need the Microsoft.VCRTForwarders.140 NuGet package, which is required in apps that are not packaged in an MSIX package. Чтобы восстановить симплемаскомпонент 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>
    

    Обратите внимание, что в этом пошаговом руководстве путь восстановления 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 , чтобы использовать функциональные возможности, предоставляемые симплемаскомпонент.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.

    Выходные данные NET5 консоли

РесурсыResources