Przewodnik — tworzenie składnika C#/WinRT i korzystanie z niego z języka C++/WinRT

Język C#/WinRT umożliwia deweloperom używanie platformy .NET do tworzenia własnych składników środowiska uruchomieniowego systemu Windows w języku C# przy użyciu projektu biblioteki klas. Utworzone składniki mogą być używane w aplikacjach natywnych na komputery stacjonarne jako referencję pakietową lub jako referencję projektową po wprowadzeniu kilku modyfikacji.

W tym przewodniku pokazano, jak utworzyć prosty składnik środowiska uruchomieniowego systemu Windows przy użyciu języka C#/WinRT, dystrybuować składnik jako pakiet NuGet i korzystać ze składnika z poziomu aplikacji konsolowej C++/WinRT. Pełny przykład zawierający kod tego artykułu można znaleźć w przykładzie C#/WinRT authoring sample. Aby uzyskać więcej informacji na temat tworzenia treści, zobacz Składniki autorstwa.

Aby zapoznać się z przewodnikiem dotyczącym tworzenia kontrolek WinUI za pomocą języka C#/WinRT specjalnie do użycia w aplikacjach zestawu SDK aplikacji systemu Windows, zapoznaj się z artykułem Przewodnik: Tworzenie składnika języka C# za pomocą kontrolek WinUI 3 i korzystanie z aplikacji zestawu SDK aplikacji systemu Windows C++

Wymagania wstępne

Ten przewodnik wymaga następujących narzędzi i składników:

• Visual Studio 2022
• SDK .NET 6.0 lub nowszy
• Szablony projektów C++/WinRT VSIX dla języka C++/WinRT

Tworzenie prostego składnika środowiska uruchomieniowego systemu Windows przy użyciu języka C#/WinRT

Zacznij od utworzenia nowego projektu w programie Visual Studio. Wybierz szablon projektu biblioteka klas i nadaj projektowi nazwę AuthoringDemo. Należy wprowadzić następujące dodatki i modyfikacje projektu:

1. Zaktualizuj TargetFramework w pliku AuthoringDemo.csproj i dodaj następujące elementy do PropertyGroup:

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

   Aby uzyskać dostęp do typów środowiska uruchomieniowego systemu Windows, należy ustawić określoną wersję zestawu Windows SDK w programie TFM. Aby uzyskać więcej informacji na temat obsługiwanej wersji, zobacz .NET 6 i nowsze: Użyj opcji TFM.

2. Zainstaluj pakiet NuGet Microsoft.Windows.CsWinRT w projekcie.

   a. W Eksploratorze rozwiązań kliknij prawym przyciskiem myszy węzeł projektu i wybierz polecenie Zarządzaj pakietami NuGet.

   b. Wyszukaj pakiet NuGet Microsoft.Windows.CsWinRT i zainstaluj najnowszą wersję. W tym przewodniku użyto języka C#/WinRT w wersji 1.4.1.

3. Dodaj nowy PropertyGroup element, który ustawia CsWinRTComponent właściwość . Określa to, że projekt jest składnikiem środowiska uruchomieniowego systemu Windows, tak aby .winmd plik był generowany podczas tworzenia projektu.

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

   Pełną listę właściwości projektu C#/WinRT można znaleźć w dokumentacji narzędzia NuGet języka C#/WinRT.

4. Możesz opracowywać swoje klasy środowiska uruchomieniowego używając biblioteki plików klas .cs. Kliknij prawym przyciskiem myszy Class1.cs plik i zmień jego nazwę na Example.cs. Dodaj następujący kod do tego pliku, który dodaje właściwość publiczną i metodę do klasy środowiska uruchomieniowego. Pamiętaj, aby oznaczyć wszystkie klasy, które chcesz uwidocznić w składniku środowiska uruchomieniowego jako public.

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

5. Teraz możesz skompilować projekt w celu wygenerowania .winmd pliku dla składnika. Kliknij prawym przyciskiem myszy projekt w Eksploratorze rozwiązań , a następnie wybierz Build. W folderze wyjściowym kompilacji zostanie wyświetlony wygenerowany AuthoringDemo.winmd plik.

Generowanie pakietu NuGet dla składnika

Większość deweloperów chce dystrybuować i udostępniać swój składnik środowiska uruchomieniowego systemu Windows jako pakiet NuGet. Inną opcją jest użycie składnika jako referencji do projektu. W poniższych krokach pokazano, jak spakować składnik AuthoringDemo . Podczas generowania pakietu, C#/WinRT konfiguruje składnik i zestawy hostujące w pakiecie, aby umożliwić użycie przez aplikacje natywne.

Istnieje kilka sposobów generowania pakietu NuGet:

• Jeśli chcesz wygenerować pakiet NuGet za każdym razem, gdy kompilujesz projekt, dodaj następującą właściwość do pliku projektu AuthoringDemo , a następnie ponownie skompiluj projekt.

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

• Alternatywnie możesz wygenerować pakiet NuGet, klikając prawym przyciskiem myszy projekt AuthoringDemo w Eksploratorze rozwiązań i wybierając pozycję Pakiet.

Podczas kompilowanie pakietu okno Kompilacja powinno wskazywać, że pakiet AuthoringDemo.1.0.0.nupkg NuGet został pomyślnie utworzony. Zobacz Tworzenie pakietu przy użyciu dotnet CLI, aby uzyskać więcej informacji na temat właściwości pakietu NuGet za pomocą dotnet CLI.

Użytkowanie składnika z aplikacji C++/WinRT

Składniki środowiska uruchomieniowego systemu Windows utworzone w języku C#/WinRT mogą być używane z dowolnego języka zgodnego ze środowiskiem Uruchomieniowym systemu Windows (WinRT). W poniższych krokach pokazano, jak wywołać utworzony składnik powyżej w aplikacji konsolowej C++/WinRT.

1. Dodaj nowy projekt aplikacji konsolowej C++/WinRT do rozwiązania. Należy pamiętać, że ten projekt może być również częścią innego rozwiązania, jeśli tak wybierzesz.

   a. W Eksploratorze rozwiązań kliknij prawym przyciskiem myszy na węźle rozwiązania i kliknij Dodaj —>Nowy Projekt.

   b. W oknie dialogowym Dodawanie nowego projektu wyszukaj szablon projektu C++/WinRT Console Application. Wybierz szablon i kliknij przycisk Dalej.

   c. Nadaj nazwę nowemu projektowi CppConsoleApp i kliknij Utwórz.

2. Dodaj odwołanie do składnika AuthoringDemo jako pakiet NuGet lub odwołanie do projektu.

   • Opcja 1 (referencja do pakietu):

     a. Kliknij prawym przyciskiem myszy projekt CppConsoleApp i wybierz pozycję Zarządzaj pakietami NuGet. Może być konieczne skonfigurowanie źródeł pakietów w celu dodania odwołania do pakietu NuGet AuthoringDemo. W tym celu kliknij ikonę Ustawienia w Menedżerze pakietów NuGet i dodaj źródło pakietu do odpowiedniej ścieżki.

     

     b. Po skonfigurowaniu źródeł pakietów wyszukaj pakiet AuthoringDemo i kliknij pozycję Zainstaluj.

     

   • Opcja 2 (Referencja projektu)

     a. Kliknij prawym przyciskiem myszy projekt CppConsoleApp i wybierz pozycję Dodaj —>Odwołanie. Pod węzłem Projects dodaj odwołanie do projektu AuthoringDemo.

3. Aby hostować składnik, należy dodać plik manifestu na potrzeby rejestracji aktywowanych klas. Aby uzyskać więcej informacji na temat hostingu składników zarządzanych, zobacz Hosting składników zarządzanych.

   a. Aby dodać plik manifestu, ponownie kliknij prawym przyciskiem myszy projekt i wybierz polecenie Dodaj —> nowy element. Wyszukaj szablon pliku tekstowego i nadaj mu nazwę CppConsoleApp.exe.manifest. Wklej następującą zawartość, która określa klasy środowiska uruchomieniowego poprzez wpisy rejestracyjne aktywujących klas.

   <?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>
   

   Plik manifestu aplikacji jest wymagany w przypadku aplikacji, które nie są spakowane. W przypadku spakowanych aplikacji konsument aplikacji musi zarejestrować klasy aktywowane w pliku manifestu pakietu Package.appxmanifest, jak wyjaśniono w Przewodnik: Tworzenie składnika C# za pomocą kontrolek WinUI 3 i korzystanie z aplikacji C++ Windows App SDK.

   b. Zmodyfikuj projekt, aby uwzględnić plik manifestu w danych wyjściowych podczas wdrażania projektu. Kliknij plik CppConsoleApp.exe manifestu w Eksploratorze rozwiązań i ustaw właściwość Content na wartość True. Oto przykład tego, jak to wygląda.

   

4. Otwórz pch.h w części Pliki nagłówkowe w projekcie i dodaj następujący wiersz kodu, aby dołączyć składnik.

   #include <winrt/AuthoringDemo.h>
   

5. Otwórz main.cpp w obszarze Pliki źródłowe projektu i zastąp go następującą zawartością.

   #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. Skompiluj i uruchom projekt CppConsoleApp . Teraz powinieneś widzieć dane wyjściowe poniżej.

   

Tematy pokrewne

• przykładowy kod
• komponenty autorskie
• Hosting zarządzanego komponentu