Procedura dettagliata: Creare un componente C#/WinRT e usarlo da C++/WinRT

C#/WinRT consente agli sviluppatori che usano .NET di creare i propri componenti Windows Runtime in C# usando un progetto di libreria di classi. I componenti creati possono essere utilizzati nelle applicazioni desktop native come riferimento al pacchetto o come riferimento al progetto con alcune modifiche.

Questa procedura dettagliata illustra come creare un semplice componente Windows Runtime usando C#/WinRT, distribuire il componente come pacchetto NuGet e usare il componente da un'applicazione console C++/WinRT. Per l'esempio completo che fornisce il codice per questo articolo, vedere l'esempio di creazione di C#/WinRT. Per altre informazioni sulla creazione, vedere Creazione di componenti.

Per una procedura dettagliata sulla creazione di controlli WinUI con C#/WinRT in modo specifico per l'uso nelle applicazioni Windows App SDK, vedere l'articolo Procedura dettagliata: Creare un componente C# con controlli WinUI 3 e usarlo da un'applicazione Windows App SDK C++

Prerequisiti

Per questa procedura dettagliata sono richiesti gli strumenti e i componenti seguenti:

• Visual Studio 2022
• .NET 6.0 SDK o versione successiva
• VSIX C++/WinRT per modelli di progetto C++/WinRT

Creare un semplice componente Windows Runtime usando C#/WinRT

Per iniziare, creare un nuovo progetto in Visual Studio. Selezionare il modello di progetto Libreria di classi e denominare il progetto AuthoringDemo. È necessario apportare le aggiunte e le modifiche seguenti al progetto:

1. Aggiornare TargetFramework nel file AuthoringDemo.csproj e aggiungere gli elementi seguenti a PropertyGroup:

   <PropertyGroup>
       <TargetFramework>net6.0-windows10.0.19041.0</TargetFramework>
       <Platforms>x64</Platforms>
   </PropertyGroup>
   

   Per accedere ai tipi di Windows Runtime, è necessario impostare una versione specifica di Windows SDK in TFM. Per altre informazioni sulla versione supportata, vedere .NET 6 e versioni successive: Usare l'opzione TFM.

2. Installare il pacchetto NuGet Microsoft.Windows.CsWinRT nel progetto.

   a. In Esplora soluzioni fare clic con il pulsante destro del mouse sul nodo del progetto e selezionare Gestisci pacchetti NuGet.

   b. Cercare il pacchetto NuGet Microsoft.Windows.CsWinRT e installare la versione più recente. Questa procedura dettagliata usa C#/WinRT versione 1.4.1.

3. Aggiungere un nuovo elemento PropertyGroup che imposta la proprietà CsWinRTComponent. Specifica che il progetto è un componente Windows Runtime in modo che venga generato un file .winmd durante la compilazione del progetto.

   <PropertyGroup>   
       <CsWinRTComponent>true</CsWinRTComponent>
   </PropertyGroup>
   

   Per un elenco completo delle proprietà di progetto C#/WinRT, vedere la documentazione di NuGet C#/WinRT.

4. È possibile creare le classi di runtime usando i file di classe .cs della libreria. Fare clic con il pulsante destro del mouse sul file Class1.cs e rinominarlo come Example.cs. Aggiungere il codice seguente a questo file, in modo da aggiungere una proprietà pubblica e un metodo alla classe di runtime. Ricordarsi di contrassegnare le classi da esporre nel componente di runtime come public.

   namespace AuthoringDemo
   {
       public sealed class Example
       {
           public int SampleProperty { get; set; }
   
           public static string SayHello()
           {
               return "Hello from your C# WinRT component";
           }
       }
   }
   

5. È ora possibile compilare il progetto per generare il file .winmd per il componente. Fare clic con il pulsante destro del mouse sul progetto in Esplora soluzionie scegliere Compila. Nella cartella di output di compilazione verrà visualizzato il file AuthoringDemo.winmd generato.

Generare un pacchetto NuGet per il componente

La maggior parte degli sviluppatori vuole distribuire e condividere il componente Windows Runtime come pacchetto NuGet. Un'altra opzione consiste nell'utilizzare il componente come riferimento al progetto. I passaggi seguenti illustrano come creare un pacchetto del componente AuthoringDemo. Quando si genera il pacchetto, C#/WinRT configura il componente e ospita gli assembly nel pacchetto per abilitare l'utilizzo da applicazioni native.

Esistono diversi modi per generare il pacchetto NuGet:

• Se si vuole generare un pacchetto NuGet ogni volta che si compila il progetto, aggiungere la proprietà seguente al file di progetto AuthoringDemo e quindi ricompilare il progetto.

  <PropertyGroup>
      <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
  </PropertyGroup>
  

• In alternativa, è possibile generare un pacchetto NuGet facendo clic con il pulsante destro del mouse sul progetto AuthoringDemo in Esplora soluzioni e selezionando Crea pacchetto.

Quando si compila il pacchetto, la finestra Compilazione indica che il pacchetto NuGet AuthoringDemo.1.0.0.nupkg è stato creato correttamente. Per altre informazioni sulle proprietà dei pacchetti NuGet con l'interfaccia della riga di comando di .NET, vedere Creare un pacchetto usando l'interfaccia della riga di comando dotnet .

Utilizzare il componente da un'app C++/WinRT

I componenti Windows Runtime creati da C#/WinRT possono essere utilizzati da qualsiasi linguaggio compatibile con Windows Runtime (WinRT). I passaggi seguenti illustrano come chiamare il componente creato in precedenza in un'applicazione console C++/WinRT.

Nota

L'utilizzo di un componente C#/WinRT dalle app C#/.NET è supportato sia dal riferimento al pacchetto che dal riferimento al progetto. Questo scenario equivale a usare qualsiasi libreria di classi C# normale e non comporta l'attivazione di WinRT nella maggior parte dei casi. A partire da C#/WinRT 1.3.5, i riferimenti al progetto per i consumer C# richiedono .NET 6.

1. Aggiungere un nuovo progetto di tipo Applicazione console C++/WinRT alla soluzione. Si noti che questo progetto può anche far parte di una soluzione diversa, se si sceglie questa opzione.

   a. In Esplora soluzioni fare clic con il pulsante destro del mouse sul nodo della soluzione e scegliere Aggiungi ->Nuovo progetto.

   b. Nella finestra di dialogo Aggiungi nuovo progetto cercare il modello di progetto Applicazione console C++/WinRT. Selezionare il modello e fare clic su Avanti.

   c. Denominare il nuovo progetto CppConsoleApp e fare clic su Crea.

2. Aggiungere un riferimento al componente AuthoringDemo, come pacchetto NuGet o riferimento a un progetto.

   • Opzione 1 (riferimento al pacchetto):

     a. Fare clic con il pulsante destro del mouse sul progetto CppConsoleApp e selezionare Gestisci pacchetti NuGet. Potrebbe essere necessario configurare le origini dei pacchetti per aggiungere un riferimento al pacchetto NuGet AuthoringDemo. A tale scopo, fare clic sull'icona Impostazioni in Gestione pacchetti NuGet e aggiungere un'origine del pacchetto al percorso appropriato.

     

     b. Dopo aver configurato le origini del pacchetto, cercare il pacchetto AuthoringDemo e fare clic su Installa.

     

   • Opzione 2 (riferimento al progetto):

     a. Fare clic con il pulsante destro del mouse sul progetto CppConsoleApp e selezionare Aggiungi ->Riferimento. Nel nodo Progetti aggiungere un riferimento al progetto AuthoringDemo.

3. Per ospitare il componente, è necessario aggiungere un file manifesto per le registrazioni delle classi attivabili. Per altre informazioni sull'hosting di componenti gestiti, vedere Hosting di componenti gestiti.

   a. Per aggiungere il file manifesto, fare di nuovo clic con il pulsante destro del mouse sul progetto e scegliere Aggiungi -> Nuovo elemento. Cercare il modello File di testo e denominarlo CppConsoleApp.exe.manifest. Incollare il contenuto seguente, che specifica le classi di runtime usando voci di registrazione della classe attivabili:

   <?xml version="1.0" encoding="utf-8"?>
   <assembly manifestVersion="1.0" xmlns="urn:schemas-microsoft-com:asm.v1">
       <assemblyIdentity version="1.0.0.0" name="CppConsoleApp"/>
       <file name="WinRT.Host.dll">
           <activatableClass
               name="AuthoringDemo.Example"
               threadingModel="both"
               xmlns="urn:schemas-microsoft-com:winrt.v1" />
       </file>
   </assembly>
   

   Il file manifesto dell'applicazione è necessario per le app non in pacchetto. Per le app in pacchetto, il consumer dell'app deve registrare le classi attivabili nel file manifesto del pacchetto Package.appxmanifest, come illustrato in Procedura dettagliata: Creare un componente C# con controlli WinUI 3 e utilizzarlo da un'applicazione Windows App SDK C++.

   b. Modificare il progetto in modo da includere il file manifesto nell'output durante la distribuzione del progetto. Fare clic sul file CppConsoleApp.exe.manifest in Esplora soluzioni e impostare la proprietà Content su True. Il risultato sarà analogo all'esempio seguente.

   

4. Aprire pch.h nei file di intestazione del progetto e aggiungere la riga di codice seguente per includere il componente.

   #include <winrt/AuthoringDemo.h>
   

5. Aprire main.cpp in File di origine del progetto e sostituirlo con il contenuto seguente.

   #include "pch.h"
   #include "iostream"
   
   using namespace winrt;
   using namespace Windows::Foundation;
   
   int main()
   {
       init_apartment();
   
       AuthoringDemo::Example ex;
       ex.SampleProperty(42);
       std::wcout << ex.SampleProperty() << std::endl;
       std::wcout << ex.SayHello().c_str() << std::endl;
   }
   

6. Compilare ed eseguire il progetto CppConsoleApp. Verrà ora visualizzato l'output seguente.

   

Argomenti correlati

• Codice di esempio
• Creazione di componenti
• Hosting di componenti gestiti