C#/WinRT

C#/WinRT è un toolkit in pacchetto NuGet che fornisce il supporto per le proiezioni Windows Runtime (WinRT) per il linguaggio C#. Un assembly di proiezione è un assembly di interoperabilità, che consente di programmare le API WinRT in modo naturale e familiare per il linguaggio di destinazione. La proiezione C#/WinRT nasconde i dettagli dell'interoperabilità tra le interfacce di C# e WinRT e fornisce il mapping di molti tipi WinRT agli equivalenti .NET appropriati, ad esempio stringhe, URI, tipi di valore comuni e raccolte generiche.

C#/WinRT offre attualmente il supporto per l'uso di API WinRT tramite l'uso di moniker framework di destinazione in .NET. L'impostazione di moniker framework di destinazione con una versione specifica di Windows SDK aggiunge riferimenti agli assembly di proiezione e runtime di Windows SDK generati da C#/WinRT.

Il pacchetto NuGet C#/WinRT consente di creare e fare riferimento agli assembly di interoperabilità WinRT per i consumer .NET. La versione più recente di C#/WinRT include anche un'anteprima della creazione di tipi WinRT in C#.

Per altre informazioni, vedere il repository di C#/WinRT in GitHub.

Motivazioni per l'uso di C#/WinRT

.NET (noto in precedenza come .NET Core) è un runtime open source multipiattaforma che può essere usato per creare applicazioni per dispositivi, cloud e Internet.

Le versioni precedenti di .NET Framework e .NET Core includevano il supporto predefinito di WinRT, una tecnologia specifica di Windows. Per supportare gli obiettivi di portabilità ed efficienza di .NET 6+, il supporto delle proiezioni WinRT è stato rimosso dal compilatore e dal runtime .NET ed è stato spostato nel toolkit di C#/WinRT. Vedere Supporto predefinito per WinRT rimosso da .NET. L'obiettivo di C#/WinRT è offrire la parità con il supporto predefinito di WinRT fornito dalle versioni precedenti del compilatore C# e del runtime .NET. Per informazioni dettagliate, vedi Mapping .NET dei tipi Windows Runtime.

C#/WinRT supporta anche i componenti in Windows App SDK, incluso WinUI 3. Windows App SDK sposta i controlli nativi dell'interfaccia utente Microsoft e altri componenti nativi al di fuori del sistema operativo. Questo consente agli sviluppatori di app di usare i controlli e i componenti più recenti in Windows 10, versione 1809 e versioni successive.

Infine, C#/WinRT è un toolkit generale che ha lo scopo di supportare altri scenari in cui il supporto predefinito per WinRT non è disponibile nel compilatore C# o nel runtime .NET.

Novità

Le versioni più recenti di C#/WinRT sono disponibili nella pagina delle note sulla versione nel repository GitHub.

Utilizzo

Il pacchetto NuGet C#/WinRT può essere usato per generare le proiezioni C# (denominate anche assembly di interoperabilità) dai componenti WinRT e per creare componenti di C#/WinRT. Per altri dettagli sugli scenari di utilizzo per C#/WinRT, vedere la guida all'utilizzo nel repository.

Generare e distribuire un assembly di interoperabilità

Le API WinRT sono definite nei file di metadati Windows (WinMD). Il pacchetto NuGet C#/WinRT (Microsoft.Windows.CsWinRT) include il compilatore C#/WinRT, cswinrt.exe, che consente di elaborare file WinMD e generare codice C# per .NET. C#/WinRT compila questi file di origine in un assembly di interoperabilità, analogamente al modo in cui C++/WinRT genera intestazioni per la proiezione del linguaggio C++. È quindi possibile distribuire l'assembly di interoperabilità C#/WinRT insieme all'assembly di implementazione per le applicazioni .NET a cui fare riferimento, in genere come pacchetto NuGet.

Per altre informazioni su come generare e distribuire un assembly di interoperabilità, vedere Generare una proiezione C# da un componente C++/WinRT ed eseguire la distribuzione come NuGet per le app .NET.

Fare riferimento a un assembly di interoperabilità

In genere, agli assembly di interoperabilità C#/WinRT fanno riferimento i progetti applicazione, a cui a loro volta potrebbero fare riferimento anche assembly di interoperabilità intermedi. Ad esempio, l'assembly di interoperabilità WinUI fa riferimento all'assembly di interoperabilità Windows SDK.

Se si distribuisce un componente WinRT di terze parti senza un assembly di interoperabilità ufficiale, un progetto applicazione può seguire la procedura per la generazione di un assembly di interoperabilità per generare le proprie origini di proiezione private. Questo approccio non è consigliato, perché può generare conflitti tra proiezioni dello stesso tipo all'interno di un processo. La funzionalità di creazione di pacchetti NuGet, che segue lo schema di controllo delle versioni semantico, è progettata per evitare questo problema. È preferibile usare un assembly di interoperabilità di terze parti ufficiale.

Supporto incorporato per i tipi WinRT (anteprima)

A partire da C#/WinRT versione 1.4.1, è incluso il supporto per incorporare le origini di proiezione e runtime di Windows SDK per .NET e .NET Standard 2.0 nell'output della libreria o dell'app. Ciò è utile nei casi in cui l'utilizzo dei tipi di Windows SDK è autonomo. Il supporto incorporato rimuove le dipendenze da WinRT.Runtime.dll e Microsoft.Windows.SDK.NET.dll, riducendo così la libreria o le dimensioni di output dell'app. Consente inoltre agli sviluppatori di librerie di fornire supporto di livello inferiore e rimuove la necessità di multi-targeting.

Per altri dettagli, vedere la documentazione incorporata di C#/WinRT nel repository.

Attivazione del tipo WinRT

C#/WinRT supporta l'attivazione di tipi WinRT ospitati dal sistema operativo, nonché componenti di terze parti, ad esempio Win2D. Il supporto per l'attivazione di componenti di terze parti in un'applicazione desktop è abilitato con l'attivazione gratuita di WinRT di registrazione (vedere Miglioramento delle app desktop non in pacchetto con componenti Windows Runtime), disponibile in Windows 10 versione 1903 e successive. I componenti C++ nativi devono impostare la proprietà Compatibile con Windows Desktop su True tramite le proprietà del progetto o il file .vcxproj, per fare riferimento e inoltrare i file binari Microsoft.VCLibs.Desktop alle app che ne fanno uso. In caso contrario, il pacchetto Server d'inoltro VCRT sarà richiesto dalle app che ne fanno uso se il componente è destinato solo alle app UWP.

C#/WinRT fornisce anche un percorso di fallback per l'attivazione se Windows non riesce ad attivare il tipo come descritto in precedenza. In questo caso, C#/WinRT tenta di individuare una DLL di implementazione nativa in base al nome completo del tipo, rimuovendo progressivamente gli elementi. Ad esempio, la logica di fallback tenterà di attivare il tipo Contoso.Controls.Widget dai moduli seguenti, in sequenza:

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

C#/WinRT usa l'ordine di ricerca alternativo LoadLibrary per individuare una DLL di implementazione. Un'app basata su questo comportamento di fallback deve creare il pacchetto della DLL di implementazione insieme al modulo dell'app.

Errori comuni e risoluzione dei problemi

• Errore: "Metadati Windows non forniti o rilevati".

  È possibile, ad esempio, specificare i metadati di Windows usando la proprietà del progetto <CsWinRTWindowsMetadata>:

  <CsWinRTWindowsMetadata>10.0.19041.0</CsWinRTWindowsMetadata>
  

  In C#/WinRT versione 1.2.1 e successive per impostazione predefinita questa proprietà è TargetPlatformVersion, derivata dalla versione di Windows SDK specificata nella proprietà TargetFramework.

• Errore CS0246: Non è possibile trovare il tipo o il nome dello spazio dei nomi 'Windows' (direttiva using o riferimento ad assembly mancante?)

  Per risolvere questo errore, modificare la proprietà <TargetFramework> in modo che sia destinata a una versione specifica di Windows, ad esempio:

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

  Fare riferimento alla documentazione sulle chiamate delle API di Windows Runtime per informazioni dettagliate su come specificare la proprietà <TargetFramework>.

• System.InvalidCastException durante il cast a un'interfaccia con l'attributo ComImport

  Quando si esegue il cast di un oggetto a un'interfaccia con l'attributo ComImport, è necessario usare l'operatore .As<> anziché usare un'espressione cast esplicita. Ad esempio:

  someObject.As<SomeComImportInterface>
  

  Per altre informazioni, vedere la guida all'interoperabilità COM.

• System.Runtime.InteropServices.COMException: classe non registrata (0x80040154 (REGDB_E_CLASSNOTREG))

  • Se viene visualizzata questa eccezione quando si utilizza una proiezione C#/WinRT da un componente C++/WinRT, assicurarsi che il componente abbia impostato la proprietà Compatibile con Windows Desktop su True tramite le proprietà del progetto o tramite il file .vcxproj.

Errori di controllo delle versioni di .NET SDK

In un progetto creato con una versione di .NET SDK precedente rispetto a una delle relative dipendenze, è possibile riscontrare gli errori o gli avvisi seguenti.

Messaggio di errore o di avviso	Motivo
Avviso MSB3277: Sono stati rilevati conflitti non risolvibili tra versioni diverse di WinRT.Runtime o Microsoft.Windows.SDK.NET.	Questo avviso di compilazione si verifica quando si fa riferimento a una libreria che espone i tipi di Windows SDK sulla relativa superficie dell'API.
Errore CS1705: L'assembly 'NomeAssembly1' usa 'NomeTipo' la cui versione è successiva a quella dell'assembly 'NomeAssembly2' a cui viene fatto riferimento	Questo errore di compilazione si verifica quando si fa riferimento e si utilizzano i tipi di Windows SDK esposti in una libreria.
System.IO.FileLoadException	Questo errore di runtime può verificarsi quando si chiamano determinate API di una raccolta che non espone i tipi di Windows SDK.

Per correggere questi errori, aggiornare .NET SDK alla versione più recente. Questa operazione garantisce la compatibilità delle versioni di runtime e degli assembly di Windows SDK usate dall'applicazione con tutte le dipendenze. Questi errori possono verificarsi con aggiornamenti anticipati della manutenzione e/o delle funzionalità di .NET SDK, poiché per le correzioni di runtime possono essere necessari aggiornamenti delle versioni degli assembly.

Problemi noti

I problemi noti e le modifiche di rilievo sono indicati nel repository di C#/WinRT in GitHub.

Se si verificano problemi funzionali con il pacchetto NuGet C#/WinRT, il compilatore cswinrt.exe o le origini di proiezione generate, puoi inviare gli eventuali problemi tramite la pagina relativa ai problemi di C#/WinRT.

Risorse aggiuntive

• Repository C#/WinRT in GitHub