Procedura dettagliata: generare una proiezione .NET 5 da un componente C++/WinRT e distribuire NuGetWalkthrough: Generate a .NET 5 projection from a C++/WinRT component and distribute the NuGet

Questa procedura dettagliata illustra come usare C#/WinRT per generare una proiezione .NET 5 per un componente/WinRT C++, creare il pacchetto NuGet associato e fare riferimento al pacchetto NuGet da un'applicazione console 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.

È possibile scaricare l'esempio completo per questa procedura dettagliata da GitHub qui.You can download the full sample for this walkthrough from GitHub here.

Nota

Questa procedura dettagliata è stata scritta per la versione di anteprima più recente di C#/WinRT (RC2).This walkthrough is written for the latest preview of C#/WinRT (RC2). Si prevede che la prossima versione 1,0 avrà ulteriori aggiornamenti e miglioramenti per l'esperienza dello sviluppatore.We expect the upcoming 1.0 release to have further updates and improvements to the developer experience.

PrerequisitiPrerequisites

In questa procedura dettagliata e nell'esempio corrispondente sono necessari gli strumenti e i componenti seguenti:This walkthrough and the corresponding sample requires the following tools and components:

  • Visual Studio 16,8 Preview 3 (o versione successiva) con il carico di lavoro di sviluppo piattaforma UWP (Universal Windows Platform) installato.Visual Studio 16.8 Preview 3 (or later) with the Universal Windows Platform development workload installed. In Dettagli installazione > piattaforma UWP (Universal Windows Platform) sviluppo, selezionare l'opzione C++ (v14x) piattaforma UWP (Universal Windows Platform) Tools .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.
  • Estensione VSIX c++/WinRT per i modelli di progetto c++/WinRT.C++/WinRT VSIX extension for C++/WinRT project templates.

Creare un semplice componente runtime C++/WinRTCreate a simple C++/WinRT Runtime component

Per seguire questa procedura dettagliata, è necessario innanzitutto disporre di un componente C++/WinRT per il quale creare una proiezione .NET 5.To follow this walkthrough, you must first have a C++/WinRT component for which to create a .NET 5 projection. Questa procedura dettagliata usa il progetto SimpleMathComponent nell'esempio correlato da GitHub qui.This walkthrough uses the SimpleMathComponent project in the related sample from GitHub here. Si tratta di un progetto Windows Runtime Component (C++/WinRT) che è stato creato usando l' estensione VSIX c++/WinRT.This is a Windows Runtime Component (C++/WinRT) project that was created by using the C++/WinRT VSIX extension. Dopo aver copiato il progetto nel computer di sviluppo, aprire la soluzione in Visual Studio 2019 Preview.After you copy the project to your development computer, open the solution in Visual Studio 2019 Preview.

Il codice in questo progetto fornisce la funzionalità per le operazioni matematiche di base illustrate nel file di intestazione riportato di seguito.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);
    };
}

Per istruzioni più dettagliate sulla creazione di un componente C++/WinRT e sulla generazione di un file con estensione WinMD, vedere Windows Runtime 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.

Nota

Se si implementa IInspectable:: GetRuntimeClassName nel componente, deve restituire un nome di classe WinRT valido.If you are implementing IInspectable::GetRuntimeClassName in your component, it must return a valid WinRT class name. Poiché C#/WinRT usa la stringa del nome della classe per l'interoperabilità, un nome di classe di runtime errato genererà un InvalidCastException.Because C#/WinRT uses the class name string for interop, an incorrect runtime class name will raise an InvalidCastException.

Aggiungere un progetto di proiezione alla soluzione componenteAdd a projection project to the component solution

Se l'esempio è stato clonato dal repository, eliminare innanzitutto il progetto SimpleMathProjection per seguire la procedura dettagliata.If you have cloned the sample from the repo, first delete the SimpleMathProjection project to follow the walkthrough step by step.

  1. Aggiungere un nuovo progetto libreria di classi (.NET Core) alla soluzione.Add a new Class Library (.NET Core) project to your solution.

    1. In Esplora soluzionifare clic con il pulsante destro del mouse sul nodo della soluzione e scegliere Aggiungi -> nuovo progetto.In Solution Explorer, right click your solution node and click Add -> New Project.
    2. Nella finestra di dialogo Aggiungi nuovo progettocercare il modello di progetto libreria di classi (.NET Core) .In the Add New Project dialog box, search for the Class Library (.NET Core) project template. Selezionare il modello e fare clic su Avanti.Select the template and click Next.
    3. Assegnare al nuovo progetto il nome SimpleMathProjection e fare clic su Crea.Name the new project SimpleMathProjection and click Create.
  2. Eliminare il file Class1.cs vuoto dal progetto.Delete the empty Class1.cs file from the project.

  3. Installare il pacchetto NuGet C#/WinRT.Install the C#/WinRT NuGet package.

    1. In Esplora soluzionifare clic con il pulsante destro del mouse sul progetto SimpleMathProjection e scegliere Gestisci pacchetti NuGet.In Solution Explorer, right click your SimpleMathProjection project and select Manage NuGet Packages.
    2. Cercare il pacchetto NuGet Microsoft. Windows. CsWinRT e installare la versione più recente.Search for the Microsoft.Windows.CsWinRT NuGet package and install the latest version.
  4. Aggiungere un riferimento al progetto SimpleMathComponent .Add a project reference to the SimpleMathComponent project. In Esplora soluzioni, fare clic con il pulsante destro del mouse sul nodo dipendenze sotto il progetto SimpleMathProjection , selezionare Aggiungi riferimento al progettoe selezionare il progetto SimpleMathComponent .In Solution Explorer, right click the Dependencies node under the SimpleMathProjection project, select Add Project Reference, and select the SimpleMathComponent project.

    Nota

    Se si usa Visual Studio 16,8 Preview 4 o versione successiva, questa sezione è stata completata dopo il completamento del passaggio 4.If you are using Visual Studio 16.8 Preview 4 or later, you are done with this section after completing step 4. Se si usa Visual Studio 16,8 Preview 3, è necessario completare anche il passaggio 5.If you are using Visual Studio 16.8 Preview 3, you must also complete step 5.

  5. Se si usa Visual Studio 16,8 Preview 3: in Esplora soluzionifare doppio clic sul nodo SimpleMathProjection per aprire il file di progetto nell'editor, aggiungere gli elementi seguenti al file, quindi salvare e chiudere il file.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>
    

    Questi elementi installano la versione richiesta del pacchetto NuGet Microsoft.NET. Compilers. Toolset , che include il compilatore C# più recente.These elements install the required version of the Microsoft.Net.Compilers.Toolset NuGet package, which includes the latest C# compiler. Questa procedura dettagliata include l'installazione di questo pacchetto NuGet tramite questi riferimenti ai file di progetto perché la versione richiesta del pacchetto potrebbe non essere disponibile nel feed NuGet pubblico predefinito.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.

Dopo questa procedura, il Esplora soluzioni dovrebbe essere simile al seguente.After these steps, your Solution Explorer should look similar to this.

Esplora soluzioni che mostra le dipendenze del progetto di proiezione

Modificare il file di progetto per eseguire C#/WinRTEdit the project file to execute C#/WinRT

Prima di poter richiamare cswinrt.exe e generare l'assembly di proiezione, è necessario modificare il file di progetto per il progetto di proiezione.Before you can invoke cswinrt.exe and generate the projection assembly, you must edit the project file for the projection project.

  1. In Esplora soluzionifare doppio clic sul nodo SimpleMathProjection per aprire il file di progetto nell'editor.In Solution Explorer, double-click the SimpleMathProjection node to open the project file in the editor.

  2. Aggiornare l' TargetFramework elemento in modo che faccia riferimento al Windows SDK.Update the TargetFramework element to reference the Windows SDK. In questo modo vengono aggiunti dipendenze di assembly necessari per il supporto dell'interoperabilità e della proiezione.This adds assembly depedencies that are necessary for the interop and projection support. L'esempio è destinato alla versione più recente di Windows 10 a partire da questa procedura dettagliata, net 5.0-Windows 10.0.19041.0 (nota anche come SDK versione 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. Aggiungere un nuovo PropertyGroup elemento che imposta diverse proprietà cswinrt .Add a new PropertyGroup element that sets several cswinrt properties.

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

    Di seguito sono riportati alcuni dettagli sulle impostazioni in questo esempio:Here are some details about the settings in this example:

    • La CsWinRTIncludes proprietà specifica gli spazi dei nomi da proiettare.The CsWinRTIncludes property specifies which namespaces to project.
    • La CsWinRTGeneratedFilesDir proprietà imposta la directory di output in cui vengono generati i file della proiezione, che è stata impostata nella sezione seguente sulla compilazione dall'origine.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. Per la versione più recente di C#/WinRT a partire da questa procedura dettagliata può essere necessario specificare i metadati di Windows.The latest C#/WinRT version as of this walkthrough may require specifying Windows Metadata. Questo problema verrà risolto in una versione futura di C#/WinRT.This will be fixed in a future release of C#/WinRT. Questa operazione può essere fornita con uno dei seguenti valori:This can be supplied with either:

    • Un riferimento al pacchetto, ad esempio a Microsoft. Windows. Sdk. Contracts, oppureA package reference, such as to Microsoft.Windows.SDK.Contracts, or

    • Valore esplicito che imposta l'oggetto con la CsWinRTWindowsMetadata proprietà:An explicit value set the with the CsWinRTWindowsMetadata property:

      <CsWinRTWindowsMetadata>10.0.19041.0</CsWinRTWindowsMetadata>
      
  5. Salvare e chiudere il file SimpleMathProjection. csproj .Save and close the SimpleMathProjection.csproj file.

Compila i progetti dall'origineBuild projects out of source

Nell' esempio correlato, la compilazione viene configurata con il file Directory. Build. props .In the related sample, the build is configured with the Directory.build.props file. I file generati dalla compilazione dei progetti SimpleMathComponent e SimpleMathProjection vengono visualizzati nella cartella _build a livello di soluzione.The generated files from building both the SimpleMathComponent and SimpleMathProjection projects appear in the _build folder at the solution level. Per configurare i progetti per la compilazione dall'origine, copiare il file Directory. Build. props riportato di seguito nella directory contenente il file della soluzione.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>

Anche se questo passaggio non è necessario per generare una proiezione, fornisce semplicità generando file di compilazione da entrambi i progetti nella stessa directory e semplificando la pulizia delle compilazioni.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. Si noti che se l'origine non viene compilata, sia SimpleMathComponent. winmd che l'assembly di interoperabilità SimpleMathComponent.dll verranno generati in directory diverse nelle rispettive cartelle di progetto.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. A questi file viene fatto riferimento in SimpleMathProjection. NuSpec , quindi i percorsi devono essere modificati di conseguenza.These files are both referenced in SimpleMathProjection.nuspec below, so the paths would have to be changed accordingly.

Creare un pacchetto NuGet dalla proiezioneCreate a NuGet package from the projection

Per distribuire e usare l'assembly di interoperabilità, è possibile creare automaticamente un pacchetto NuGet durante la compilazione della soluzione aggiungendo alcune proprietà aggiuntive del progetto.To distribute and use the interop assembly, you can automatically create a NuGet package when building the solution by adding some additional project properties. Questo pacchetto includerà l'assembly di interoperabilità e una dipendenza dal pacchetto NuGet C#/WinRT per l'assembly di runtime C#/WinRT necessario.This package will include the interop assembly and a dependency on the C#/WinRT NuGet package for the required C#/WinRT runtime assembly. Questo assembly di runtime è denominato winrt.runtime.dll per le destinazioni di .NET 5,0.This runtime assembly is named winrt.runtime.dll for .NET 5.0 targets.

  1. Aggiungere un file di specifica NuGet (con estensione NuSpec) al progetto SimpleMathProjection .Add a NuGet spec (.nuspec) file to the SimpleMathProjection project.

    1. In Esplora soluzionifare clic con il pulsante destro del mouse sul nodo SimpleMathProjection , scegliere Aggiungi -> nuova cartellae denominare la cartella NuGet.In Solution Explorer, right-click the SimpleMathProjection node, choose Add -> New Folder, and name the folder nuget.
    2. Fare clic con il pulsante destro del mouse sulla cartella NuGet , scegliere Aggiungi -> nuovo elemento, scegliere il file XML e denominarlo SimpleMathProjection. NuSpec.Right-click the nuget folder, choose Add -> New Item, choose the XML file, and name it SimpleMathProjection.nuspec.
  2. Aggiungere il codice seguente a SimpleMathProjection. csproj per generare automaticamente il pacchetto.Add the following to SimpleMathProjection.csproj to automatically generate the package. Queste proprietà specificano NuspecFile e la directory per generare il pacchetto 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>
    

Compilare la soluzione per generare la proiezione e il pacchetto NuGetBuild the solution to generate the projection and NuGet package

A questo punto è ora possibile compilare la soluzione: fare clic con il pulsante destro del mouse sul nodo della soluzione e selezionare Compila soluzione.At this point you can now build the solution: right click on your solution node and select Build Solution. Questa operazione compilerà innanzitutto il progetto componente e quindi il progetto di proiezione.This will first build the component project and then the projection project. I file e l'assembly Interop . cs verranno generati nella directory di output, oltre ai file di metadati del progetto Component.The interop .cs files and assembly will be generated in the output directory, in addition to the metadata files from the component project. Sarà anche possibile visualizzare il pacchetto NuGet generato simplemathcomponent 0.1.0-prerelease. nupkg nella cartella NuGet .You will also be able to see the the generated NuGet package SimpleMathComponent0.1.0-prerelease.nupkg in the nuget folder.

Esplora soluzioni che mostra la generazione della proiezione

Fare riferimento al pacchetto NuGet in un'applicazione console C# .NET 5,0Reference the NuGet package in a C# .NET 5.0 console application

Per utilizzare il SimpleMathComponentproiettato, è possibile aggiungere semplicemente un riferimento al pacchetto NuGet appena creato nell'applicazione.To consume the projected SimpleMathComponent, you can simply add a reference to the newly created NuGet package in your application. Nei passaggi seguenti viene illustrato come eseguire questa operazione creando una semplice app console in una soluzione separata.The following steps demonstrate how to do this by creating a simple Console app in a separate solution.

  1. Creare una nuova soluzione con un progetto di app console (.NET Core) .Create a new solution with a Console App (.NET Core) project.

    1. In Visual Studio selezionare File -> Nuovo -> Progetto.In Visual Studio, select File -> New -> Project.
    2. Nella finestra di dialogo Aggiungi nuovo progettocercare il modello di progetto app console (.NET Core) .In the Add New Project dialog box, search for the Console App (.NET Core) project template. Selezionare il modello e fare clic su Avanti.Select the template and click Next.
    3. Assegnare al nuovo progetto il nome SampleConsoleApp e fare clic su Crea.Name the new project SampleConsoleApp and click Create. La creazione di questo progetto in una nuova soluzione consente di ripristinare il pacchetto NuGet SimpleMathComponent separatamente.Creating this project in a new solution allows you to restore the SimpleMathComponent NuGet package separately.
  2. In Esplora soluzionifare doppio clic sul nodo SampleConsoleApp per aprire il file di progetto SampleConsoleApp. csproj e aggiornare il moniker del Framework di destinazione e la configurazione della piattaforma, come illustrato nell'esempio seguente.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. Aggiungere il pacchetto NuGet SimpleMathComponent al progetto SampleConsoleApp .Add the SimpleMathComponent NuGet package to the SampleConsoleApp project. Sarà inoltre necessario il pacchetto NuGet Microsoft. VCRTForwarders. 140 , necessario nelle app che non sono in pacchetto in un pacchetto MSIX.You will also need the Microsoft.VCRTForwarders.140 NuGet package, which is required in apps that are not packaged in an MSIX package. Per ripristinare SimpleMathComponent NuGet durante la compilazione del progetto, è possibile usare la RestoreSources proprietà con il percorso della cartella NuGet nella soluzione componente.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>
    

    Si noti che in questa procedura dettagliata il percorso di ripristino NuGet per SimpleMathComponent presuppone che entrambi i file di soluzione si trovino nella stessa directory.Note that for this walkthrough, the NuGet restore path for the SimpleMathComponent assumes that both solution files are in the same directory. In alternativa, è possibile aggiungere un feed di pacchetto NuGet locale alla soluzione.Alternatively, you can add a local NuGet package feed to your solution.

  4. Modificare il file Program.cs per usare la funzionalità fornita da SimpleMathComponent.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. Compilare ed eseguire l'app console.Build and run the console app. Verrà visualizzato l'output riportato di seguito.You should see the output below.

    Output NET5 console

RisorseResources