C#/WinRT

C#/WinRT è un toolkit in pacchetto NuGet che fornisce il supporto per la proiezione di 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 target. La proiezione C#/WinRT nasconde i dettagli dell'interoperabilità tra le interfacce C# e WinRT e fornisce mapping di molti tipi WinRT a 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 dei Moniker del Framework di Destinazione (TFM) in .NET. L'impostazione di TFM 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 utilizzare i propri assembly di interoperabilità di 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 GitHub C#/WinRT.

Motivazione per C#/WinRT

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

Le versioni precedenti di .NET Framework e .NET Core avevano una conoscenza predefinita di WinRT, una tecnologia specifica di Windows. Per supportare gli obiettivi di portabilità ed efficienza di .NET 6+, è stato rimosso il supporto della proiezione WinRT dal compilatore e dal runtime .NET e spostato nel toolkit C#/WinRT (vedere Supporto predefinito per WinRT viene rimosso da .NET). L'obiettivo di C#/WinRT è fornire parità con il supporto WinRT predefinito fornito dalle versioni precedenti del compilatore C# e del runtime .NET. Per ulteriori dettagli, vedere Mappature di .NET dei tipi di Windows Runtime.

C#/WinRT supporta anche i componenti di Windows App SDK, tra cui WinUI. Windows App SDK solleva i controlli nativi dell'interfaccia utente Microsoft e altri componenti nativi dal sistema operativo. Ciò 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 ed è progettato per 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.

Usage

Il pacchetto NuGet C#/WinRT può essere usato sia per generare proiezioni C# (denominate anche assembly di interoperabilità) dai componenti WinRT, sia per la creazione di componenti 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 di Windows (WinMD). Il pacchetto NuGet C#/WinRT (Microsoft.Windows.CsWinRT) include il compilatore C#/WinRT, cswinrt.exe, che è possibile usare per elaborare i file WinMD e generare codice C# .NET. C#/WinRT compila questi file di origine in un assembly di interoperabilità, simile 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, distribuire come nuGet per le app .NET.

Fare riferimento a un assembly di interoperabilità

In genere, i progetti dell'applicazione fanno riferimento agli assembly di interoperabilità C#/WinRT. Ma possono anche essere a loro volta referenziati da assembly di interoperabilità intermedi. Ad esempio, l'assembly di interoperabilità WinUI fa riferimento all'assembly di interoperabilità di Windows SDK.

Se si distribuisce un componente WinRT di terze parti senza un assembly di interoperabilità ufficiale, un progetto di applicazione può seguire la procedura per generare un assembly di interoperabilità per generare le proprie origini di proiezione privata. Questo approccio non è consigliato perché può produrre proiezioni in conflitto dello stesso tipo all'interno di un processo. La creazione di pacchetti NuGet, seguendo lo schema di controllo delle versioni semantiche , è progettata per evitare questo problema. È preferibile un assembly di interoperabilità ufficiale di terze parti.

Supporto incorporato per i tipi WinRT (anteprima)

Dalla versione 1.4.1 di C#/WinRT, è stato incluso il supporto per incorporare le origini di proiezione e runtime di Windows SDK per .NET e .NET Standard 2.0 nell'output dell'applicazione o della libreria. 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 che riduce le dimensioni di output della libreria o dell'app. Consente anche agli sviluppatori di librerie di fornire supporto di livello inferiore e rimuove la necessità di multitargeting.

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

Attivazione dei tipi di WinRT

C#/WinRT supporta l'attivazione di tipi WinRT ospitati dal sistema operativo, nonché componenti di terze parti come Win2D. Il supporto per l'attivazione di componenti di terze parti in un'applicazione desktop è abilitato con l'attivazione winRT gratuita di registrazione (vedi 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 desktop di Windows su True tramite le proprietà del progetto o il .vcxproj file, per fare riferimento e inoltrare i file binari Microsoft.VCLibs.Desktop all'utilizzo delle app. In caso contrario, il pacchetto VCRT Forwarders sarà richiesto dalle app utilizzatrici se il componente è destinato solo alle app UWP.

C#/WinRT fornisce anche un percorso di fallback di 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 basata sul nome completo del tipo, rimuovendo progressivamente gli elementi. Ad esempio, la logica di fallback tenterebbe 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 che si basa su questo comportamento di fallback deve creare un pacchetto della DLL di implementazione insieme al modulo dell'app.

Errori comuni e risoluzione dei problemi

• Errore: "Metadati di Windows non specificati o non rilevati."

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

  <CsWinRTWindowsMetadata>10.0.19041.0</CsWinRTWindowsMetadata>
  

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

• Errore CS0246: Impossibile trovare il tipo o il nome dello spazio dei nomi 'Windows' (manca una direttiva using o un riferimento all'assembly?)

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

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

  Per altre informazioni su come specificare la proprietà, vedere la documentazione sulla <TargetFramework>.

• System.InvalidCastException quando si effettua il cast verso un'interfaccia dotata di 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. Per esempio:

  someObject.As<SomeComImportInterface>
  

  Per altri dettagli, 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 desktop di Windows su True tramite le proprietà del progetto o tramite il .vcxproj file.

Errori di controllo delle versioni di .NET SDK

È possibile che si verifichino gli errori o gli avvisi seguenti in un progetto compilato con una versione precedente di .NET SDK rispetto a una delle relative dipendenze.

Messaggio di errore o di avviso	Motivo
Avviso MSB3277: sono stati rilevati conflitti tra versioni diverse di WinRT.Runtime o Microsoft.Windows.SDK.NET che non è stato possibile risolvere.	Questo avviso di compilazione si verifica quando si fa riferimento a una libreria che espone i tipi di Windows SDK nella relativa superficie API.
Errore CS1705: L'assembly 'AssemblyName1' usa 'TypeName' con una versione successiva rispetto all'assembly di riferimento 'AssemblyName2'	Questo errore del compilatore di compilazione si verifica quando si fa riferimento e si utilizzano tipi di Windows SDK esposti in una libreria.
System.IO.FileLoadException	Questo errore di runtime può verificarsi quando si chiamano determinate API in una libreria che non espone i tipi di Windows SDK.

Per correggere questi errori, aggiornare .NET SDK alla versione più recente. In questo modo si garantisce che le versioni di runtime e assembly di Windows SDK usate dall'applicazione siano compatibili con tutte le dipendenze. Questi errori possono verificarsi con aggiornamenti di manutenzione/funzionalità iniziali per .NET SDK, perché le correzioni di runtime potrebbero richiedere aggiornamenti alle versioni degli assembly.

Problemi noti

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

Se riscontri problemi funzionali con il pacchetto NuGet C#/WinRT, il compilatore cswinrt.exe o le sorgenti di proiezione generate, segnala i problemi tramite la pagina delle segnalazioni di C#/WinRT.

Risorse aggiuntive

• Repository GitHub C#/WinRT