C#/WinRT

C#/WinRT è un toolkit in pacchetto NuGet che fornisce 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 ai .NET equivalenti appropriati, ad esempio stringhe, URI, tipi valore comuni e raccolte generiche.

C#/WinRT offre attualmente il supporto per l'uso delle API WinRT tramite i Target Framework Monikers (TFMs) 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 fare riferimento a assembly di interoperabilità WinRT personalizzati per i consumatori .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 C#/WinRT GitHub.

Motivazione per C#/WinRT

.NET (precedentemente noto 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 .NET runtime. Per informazioni dettagliate, vedere le mappature .NET dei tipi di Windows Runtime.

C#/WinRT supporta anche i componenti nel Windows App SDK, incluso WinUI 3. Il 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 .NET runtime.

Novità

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

Usage

Il pacchetto NuGet C#/WinRT può essere usato sia per generare proiezioni C# (detti anche assembly di interoperabilità) da componenti WinRT e nella creazione di componenti C#/WinRT. Per altri dettagli sugli scenari di utilizzo per C#/WinRT, vedere la guida usage 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 applicazioni .NET da utilizzare, 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 private. 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)

A partire dalla versione 1.4.1 di C#/WinRT, è incluso il supporto per incorporare i codici sorgente di proiezione e runtime di Windows SDK sia per .NET che per .NET Standard 2.0 nell'output della tua libreria o 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 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 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 (vedere Enhancing Non-packaged Desktop Apps using Windows Runtime Components), disponibile in Windows 10 versione 1903 e successive. I componenti C++ nativi devono impostare la proprietà Windows Desktop Compatible su True tramite le proprietà project o il file .vcxproj, per fare riferimento e inoltrare i file binari Microsoft.VCLibs.Desktop per l'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à <CsWinRTWindowsMetadata> project, 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 ulteriori dettagli sulla proprietà <TargetFramework>, consultare le documentazioni su Chiamata alle API di Windows Runtime.

• 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à Windows Desktop Compatible su True tramite le proprietà project o tramite il file .vcxproj.

errori di controllo delle versioni di .NET SDK

È possibile riscontrare gli errori o gli avvisi seguenti in un project 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 nell'API surface.
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 l'SDK di .NET, 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 C#/WinRT GitHub.

Se si verificano problemi funzionali con il pacchetto NuGet C#/WinRT, il compilatore cswinrt.exe o le origini di proiezione generate, segnalare eventuali problemi alla pagina dei problemi C#/WinRT.

Risorse aggiuntive

• Repository C#/WinRT GitHub