C#/WinRT

C#/WinRT to zestaw narzędzi NuGet, który zapewnia obsługę projekcji środowiska Uruchomieniowego systemu Windows (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 zawiera mapowania wielu typów WinRT do odpowiednich odpowiedników platformy .NET, takich jak ciągi, identyfikatory URI, typowe typy wartości i kolekcje ogólne.

Język C#/WinRT obecnie zapewnia obsługę korzystania z interfejsów API WinRT za pomocą programów Target Framework Monikers (TFM) na platformie .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 języka C#/WinRT umożliwia tworzenie i odwoływanie się do własnych zestawów międzyoperacyjnych WinRT dla użytkowników platformy .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 GitHub języka C#/WinRT.

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 kompilowania aplikacji urządzeń, chmury i IoT.

Poprzednie wersje programów .NET Framework i .NET Core zawierały wbudowaną wiedzę na temat winRT — technologii specyficznej dla systemu Windows. Aby zapewnić obsługę przenośności i wydajności platformy .NET 6+, podnieśliśmy obsługę projekcji WinRT poza kompilator i środowisko uruchomieniowe platformy .NET i przenieśliśmy go do zestawu narzędzi C#/WinRT (zobacz Wbudowana obsługa winRT została usunięta z platformy .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 platformy .NET. Aby uzyskać szczegółowe informacje, zobacz Mapowania typów środowiska uruchomieniowego systemu Windows na platformie .NET.

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

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# lub środowisku uruchomieniowym platformy .NET.

Co nowego?

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

Usage

Pakiet NuGet C#/WinRT można używać zarówno do generowania projekcji C# (zwanych także zestawami międzyoperacyjnymi) ze składnikó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 użycia 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 języka C# platformy .NET. 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 platformy .NET do odwołania, zazwyczaj jako pakiet NuGet.

Aby uzyskać więcej informacji na temat generowania i dystrybucji zestawu międzyoperacyjnego, odwiedź Generowanie projekcji języka C# na podstawie składnika C++/WinRT, dystrybucja jako pakiet NuGet dla aplikacji .NET.

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 innej firmy bez oficjalnego zestawu międzyoperacyjnego, projekt aplikacji może wykonać procedurę generowania zestawu międzyoperacyjnego 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 C#/WinRT w wersji 1.4.1, obsługa obejmuje możliwość osadzania źródeł projekcji i środowiska uruchomieniowego Windows SDK zarówno dla .NET, jak i .NET Standard 2.0 w danych wyjściowych Twojej 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ę dotyczącą 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 komponentów zewnętrznych w aplikacji desktopowej jest włączona dzięki rejestracji bezpłatnej aktywacji WinRT (zobacz Ulepszanie niepakowanych aplikacji desktopowych przy użyciu składników środowiska uruchomieniowego systemu Windows), dostępnej w systemie Windows 10, wersja 1903 lub nowszej. Natywne składniki języka C++ powinny ustawić właściwość Zgodny z pulpitem z systemem Windows na True poprzez właściwości projektu lub plik .vcxproj, aby odwoływać się do plików binarnych Microsoft.VCLibs.Desktop i przekazywać je dalej do aplikacji. 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 <CsWinRTWindowsMetadata> właściwości projektu, 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>
  

  Aby uzyskać więcej informacji na temat określania właściwości, zapoznaj się z dokumentacją dotyczącą <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ędzyoperacjności modelu 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ść Zgodny z pulpitem systemu Windows na wartość True za pośrednictwem właściwości projektu lub za pośrednictwem .vcxproj pliku.

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

W projekcie utworzonym przy użyciu starszej wersji zestawu .NET SDK mogą wystąpić następujące błędy lub ostrzeżenia niż dowolna z jego zależności.

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 zestawów WINDOWS SDK na powierzchni interfejsu 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 .NET SDK 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 .NET SDK, ponieważ poprawki środowiska uruchomieniowego mogą wymagać aktualizacji naszych wersji zestawów.

Znane problemy

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

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

Dodatkowe zasoby

• Repozytorium GitHub języka C#/WinRT