C#/WinRT

C#/WinRT to zestaw narzędzi NuGet, który zapewnia obsługę projekcji środowisko wykonawcze 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 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 obsługuje konsumpcję interfejsów API WinRT poprzez użycie Target Framework Monikers (TFMs) w .NET. Ustawienie programu TFM z określoną wersją zestawu SDK Windows powoduje dodanie odwołań do projekcji zestawu SDK Windows i zestawów środowiska uruchomieniowego generowanych przez język C#/WinRT.

Pakiet NuGet C#/WinRT umożliwia tworzenie i odwoływanie się do własnych zestawów międzyoperacyjnych WinRT dla użytkowników .NET. Najnowsza wersja języka C#/WinRT obsługuje również tworzenie 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 Windows. Aby zapewnić obsługę przenośności i wydajności .NET 6 i nowszych, usunęliśmy obsługę projekcji WinRT z kompilatora i środowiska uruchomieniowego .NET i przenieśliśmy ją do zestawu narzędzi 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, odwołaj się do mapowań typów w środowisko wykonawcze systemu Windows w .NET.

Język C#/WinRT obsługuje również składniki w Zestaw SDK do aplikacji systemu Windows, w tym WinUI 3. Zestaw SDK do aplikacji systemu Windows wydziela natywne kontrolki interfejsu użytkownika 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 notatek wydań 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 Windows Metadata (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 .NET kodu 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 międzyoperacyjności WinUI odnosi się do zestawu międzyoperacyjnego SDK Windows.

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

Począwszy od wersji 1.4.1 C#/WinRT, jest zapewniona obsługa osadzania projekcji Windows SDK oraz źródeł środowiska uruchomieniowego zarówno dla .NET, jak i .NET Standard 2.0 w wyniku działania biblioteki lub aplikacji. Jest to przydatne w przypadkach, w których użycie typów Windows SDK jest niezależne. Obsługa osadzona usuwa zależności od WinRT.Runtime.dll i Microsoft.Windows.SDK.NET.dll, co zmniejsza wynikowy rozmiar 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 dzięki aktywacji WinRT bez rejestracji (patrz Poprawa aplikacji desktopowych niemających pakietów przy użyciu składników środowiska wykonawczego Windows), dostępne w Windows 10 w wersji 1903 lub nowszej. 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, aby odwołać się do i przekazać binariów Microsoft.VCLibs.Desktop do użycia w aplikacjach. W przeciwnym razie pakiet VCRT Forwarders będzie wymagany przez korzystanie z aplikacji, jeśli składnik jest przeznaczony tylko dla aplikacji platformy UWP.

Język C#/WinRT udostępnia również alternatywną ścieżkę aktywacji, jeżeli Windows nie może aktywować typu tak, jak opisano powyżej. 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 Windows".

  Metadane Windows można określić przy użyciu właściwości projektu <CsWinRTWindowsMetadata>, 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 SDK Windows określonej we właściwości TargetFramework.

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

  Aby rozwiązać ten błąd, zmodyfikuj właściwość <TargetFramework>, aby kierować do określonej wersji Windows, na przykład:

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

  Zapoznaj się z dokumentacją dotyczącą Calling środowisko wykonawcze systemu Windows 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 za pośrednictwem właściwości projektu lub za pośrednictwem pliku .vcxproj.

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

Mogą wystąpić następujące błędy lub ostrzeżenia w projekcie utworzonym z wcześniejszą wersją zestawu SDK .NET niż którakolwiek z jego zależności.

Komunikat o błędzie lub ostrzeżeniu	Przyczyna
Ostrzeżenie MSB3277: Znaleziono konflikty między różnymi wersjami bibliotek 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 zestawu SDK Windows 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 odwoływania się do i używania uwidocznionych typów 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 udostępnia typów Windows SDK.

Aby naprawić te błędy, zaktualizuj zestaw SDK .NET do najnowszej wersji. Dzięki temu środowisko uruchomieniowe i Windows wersje zestawu SDK używane przez aplikację są 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