C#/WinRT

C#/WinRT to zestaw narzędzi NuGet, który zapewnia obsługę projekcji Windows Runtime (WinRT) dla języka C#. Zestaw projekcji to zestaw międzyoperacyjny, który umożliwia programowanie interfejsów API WinRT w naturalny i znany sposób dla języka docelowego. Projekcja C#/WinRT ukrywa szczegóły między interfejsami języka C# i WinRT oraz mapuje wiele typów WinRT do odpowiednich .NET odpowiedników, takich jak ciągi, identyfikatory URI, typowe typy wartości i kolekcje ogólne.

C#/WinRT obecnie oferuje wsparcie dla wykorzystywania interfejsów API WinRT za pomocą Target Framework Monikers (TFMs) w .NET. Ustawienie TFM z określoną wersją SDK systemu Windows dodaje referencje do projekcji SDK systemu Windows i bibliotek środowiska uruchomieniowego generowanych przez C#/WinRT.

Pakiet NuGet C#/WinRT umożliwia tworzenie i odnoszenie się do własnych zestawów międzyoperacyjnych WinRT dla użytkowników .NET. Najnowsza wersja języka C#/WinRT zawiera również podgląd tworzenia typów WinRT w języku C#.

Aby uzyskać dodatkowe informacje, zobacz repozytorium C#/WinRT GitHub.

Motywacja dla języka C#/WinRT

.NET (wcześniej znany jako .NET Core) to środowisko uruchomieniowe typu open source, międzyplatformowe, które może służyć do tworzenia aplikacji urządzeń, chmury i IoT.

Poprzednie wersje platformy .NET Framework i .NET Core miały wbudowaną wiedzę na temat winRT — technologii specyficznej dla systemu Windows. W celu wsparcia celów przenośności i wydajności w .NET 6 i nowszych usunięto obsługę projekcji WinRT z kompilatora i środowiska uruchomieniowego .NET i przeniesiono ją do narzędzia C#/WinRT (zobacz Obsługa wbudowanego środowiska WinRT została usunięta z .NET). Celem języka C#/WinRT jest zapewnienie parzystości z wbudowaną obsługą winRT zapewnianą przez wcześniejsze wersje kompilatora języka C# i środowiska uruchomieniowego .NET. Aby uzyskać szczegółowe informacje, zobacz .NET mapowania typów Windows Runtime.

Język C#/WinRT obsługuje również składniki w Windows App SDK, w tym WinUI 3. Windows App SDK podnosi natywne kontrolki interfejsu użytkownika firmy Microsoft i inne składniki natywne z systemu operacyjnego. Dzięki temu deweloperzy aplikacji mogą używać najnowszych kontrolek i składników w wersjach Windows 10, wersji 1809 i nowszych.

Na koniec język C#/WinRT jest ogólnym zestawem narzędzi i jest przeznaczony do obsługi innych scenariuszy, w których wbudowana obsługa winRT nie jest dostępna w kompilatorze języka C# ani w środowisku uruchomieniowym .NET.

Co nowego?

Najnowsze wersje języka C#/WinRT można znaleźć na naszej stronie release w repozytorium Github.

Usage

Pakiet NuGet C#/WinRT może być używany zarówno do generowania projekcji C# (nazywanych również zestawami międzyoperacyjnymi) z komponentów WinRT, jak i do tworzenia składników C#/WinRT. Aby uzyskać więcej informacji na temat scenariuszy użycia języka C#/WinRT, zapoznaj się z przewodnikiem usage w naszym repozytorium.

Wygeneruj i dystrybuuj zestaw międzyoperacyjny

Interfejsy API WinRT są definiowane w plikach metadanych systemu Windows (WinMD). Pakiet NuGet C#/WinRT (Microsoft.Windows.CsWinRT) zawiera kompilator C#/WinRT, cswinrt.exe którego można użyć do przetwarzania plików WinMD i generowania kodu .NET C#. pl-PL: C#/WinRT kompiluje te pliki źródłowe do zestawu międzyoperacyjnego, podobnie jak C++/WinRT generuje nagłówki dla projekcji języka C++. Następnie można dystrybuować zestaw międzyoperacyjny C#/WinRT wraz z zestawem implementacji dla aplikacji .NET do odwołania, zazwyczaj jako pakiet NuGet.

Aby uzyskać więcej informacji na temat sposobu generowania i dystrybuowania zestawu międzyoperacyjnego, zobacz Generate a C# projection from a C++/WinRT component, distribute as a NuGet for .NET apps (

Odwołanie do zestawu międzyoperacyjnego

Zazwyczaj zestawy międzyoperacyjne języka C#/WinRT są przywoływalne przez projekty aplikacji. Ale mogą być one również przywoływane przez pośrednie zestawy międzyoperacyjne. Na przykład zestaw interoperacyjny WinUI odwołuje się do zestawu interoperacyjnego Windows SDK.

Jeśli dystrybuujesz składnik WinRT od innej firmy bez oficjalnego zestawu interoperacyjnego, projekt aplikacji może wykonać procedurę generowania zestawu interoperacyjnego w celu wygenerowania własnych prywatnych źródeł projekcji. Nie zalecamy tego podejścia, ponieważ może ona generować sprzeczne projekcje tego samego typu w ramach procesu. Pakietowanie NuGet, zgodnie ze schematem wersjonowania semantycznego, ma na celu zapobieganie temu. Preferowany jest oficjalny zestaw interop stron trzecich.

Wbudowana obsługa typów WinRT (wersja zapoznawcza)

Począwszy od języka C#/WinRT w wersji 1.4.1, obsługa jest uwzględniana w celu osadzania źródeł projekcji i środowiska uruchomieniowego zestawu WINDOWS SDK zarówno dla .NET, jak i .NET Standard 2.0 do danych wyjściowych biblioteki lub aplikacji. Jest to przydatne w przypadkach, w których użycie typów zestawu Windows SDK jest zamknięte. Obsługa osadzona usuwa zależności od WinRT.Runtime.dll i Microsoft.Windows.SDK.NET.dll co zmniejsza rozmiar danych wyjściowych biblioteki lub aplikacji. Umożliwia również deweloperom bibliotek zapewnienie obsługi na niższych poziomach i usunięcie potrzeby obsługi wielu elementów docelowych.

Aby uzyskać więcej informacji, zobacz dokumentację osadzoną C#/WinRT w naszym repozytorium.

Aktywacja typu WinRT

Język C#/WinRT obsługuje aktywację typów WinRT hostowanych przez system operacyjny, a także składniki innych firm, takie jak Win2D. Obsługa aktywacji składników innych firm w aplikacji desktopowej jest włączona z bezpłatną aktywacją WinRT (zobacz Enhancing niespakowane aplikacje desktopowe przy użyciu Windows Runtime Components), dostępne w systemie Windows 10, wersja 1903 i nowsze. Natywne składniki języka C++ powinny ustawić właściwość Windows Desktop Compatible na True za pośrednictwem właściwości projektu lub pliku .vcxproj, w celu odwołania się do plików binarnych Microsoft.VCLibs.Desktop wykorzystywanych przez aplikacje. W przeciwnym razie pakiet VCRT Forwarders będzie wymagany przez aplikacje korzystające, jeśli składnik jest przeznaczony tylko dla aplikacji UWP.

Język C#/WinRT udostępnia również ścieżkę rezerwową aktywacji, jeśli system Windows nie może aktywować typu zgodnie z powyższym opisem. W takim przypadku C#/WinRT próbuje zlokalizować natywną bibliotekę DLL dla implementacji na podstawie w pełni kwalifikowanej nazwy typu, stopniowo usuwając po kolei elementy. Na przykład logika zapasowa podejmie próbę aktywowania typu Contoso.Controls.Widget z następujących modułów w kolejności:

1. Contoso.Controls.Widget.dll
2. Contoso.Controls.dll
3. Contoso.dll

Język C#/WinRT używa alternatywnej kolejności wyszukiwania LoadLibrary w celu zlokalizowania biblioteki DLL implementacji. Aplikacja wykorzystująca to zachowanie rezerwowe powinna dołączyć bibliotekę DLL implementacji wraz z modułem aplikacji.

Typowe błędy i rozwiązywanie problemów

• Błąd: "Nie podano lub wykryto metadanych systemu Windows".

  Metadane systemu Windows można określić przy użyciu właściwości <CsWinRTWindowsMetadata> project, na przykład:

  <CsWinRTWindowsMetadata>10.0.19041.0</CsWinRTWindowsMetadata>
  

  W języku C#/WinRT w wersji 1.2.1 lub nowszej ta właściwość jest domyślnie ustawiona na TargetPlatformVersion, która pochodzi z wersji zestawu Windows SDK określonej we TargetFramework właściwości .

• Błąd CS0246: Nie można odnaleźć nazwy typu lub przestrzeni nazw "Windows" (czy brakuje dyrektywy using lub odwołania do assembly?)

  Aby rozwiązać ten błąd, zmodyfikuj właściwość <TargetFramework>, aby ukierunkować na konkretną wersję systemu Windows, na przykład:

  <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
  

  Zapoznaj się z dokumentacją dotyczącą Calling Windows Runtime API aby uzyskać więcej informacji na temat określania właściwości <TargetFramework>.

• System.InvalidCastException podczas rzutowania do interfejsu, który ma atrybut ComImport

  Podczas rzutowania obiektu do interfejsu z atrybutem ComImport należy użyć .As<> operatora zamiast jawnego wyrażenia rzutowania. Przykład:

  someObject.As<SomeComImportInterface>
  

  Aby uzyskać więcej informacji, zobacz przewodnik dotyczący międzyoperacyjności COM.

• System.Runtime.InteropServices.COMException: Klasa nie została zarejestrowana (0x80040154 (REGDB_E_CLASSNOTREG))

  • Jeśli ten wyjątek występuje podczas korzystania z projekcji C#/WinRT ze składnika C++/WinRT, upewnij się, że składnik ustawił właściwość Windows Desktop Compatible na True albo za pośrednictwem właściwości projektu, albo za pośrednictwem pliku .vcxproj.

Błędy obsługi wersji zestawu SDK .NET

W projektach zbudowanych przy użyciu wcześniejszej wersji pakietu .NET SDK niż którakolwiek z jego zależności mogą wystąpić następujące błędy lub ostrzeżenia.

Komunikat o błędzie lub ostrzeżeniu	Przyczyna
Ostrzeżenie MSB3277: Znaleziono konflikty między różnymi wersjami środowiska WinRT.Runtime lub Microsoft.Windows.SDK.NET których nie można rozwiązać.	To ostrzeżenie kompilacji występuje podczas odwoływania się do biblioteki, która uwidacznia typy Windows SDK w interfejsie API.
Błąd CS1705: Zestaw "AssemblyName1" używa elementu "TypeName", który ma wyższą wersję niż przywoływany zestaw "AssemblyName2"	Ten błąd kompilatora występuje podczas odniesienia do i użytkowania udostępnionych typów zestawu Windows SDK w bibliotece.
System.IO.FileLoadException	Ten błąd środowiska uruchomieniowego może wystąpić podczas wywoływania niektórych interfejsów API w bibliotece, która nie uwidacznia typów zestawu Windows SDK.

Aby naprawić te błędy, zaktualizuj zestaw SDK .NET do najnowszej wersji. Dzięki temu środowisko uruchomieniowe i wersje zestawu Windows SDK używane przez aplikację będą zgodne ze wszystkimi zależnościami. Te błędy mogą wystąpić w przypadku wczesnych aktualizacji obsługi/funkcji zestawu SDK .NET, ponieważ poprawki środowiska uruchomieniowego mogą wymagać aktualizacji naszych wersji zestawów.

Znane problemy

Znane problemy i zmiany powodujące niezgodność są zanotowane w repozytorium C#/WinRT GitHub.

Jeśli wystąpią jakiekolwiek problemy funkcjonalne z pakietem NuGet języka C#/WinRT, kompilator cswinrt.exe lub wygenerowanymi źródłami projekcji, prześlij do nas problemy za pośrednictwem strony problemów C#/WinRT.

Dodatkowe zasoby

• C#/WinRT GitHub repozytorium