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 di API WinRT tramite l'uso di Target Framework Monikers (TFMs) in .NET. L'impostazione del "TFM" con una versione specifica dell'SDK di Windows aggiunge riferimenti alla proiezione dell'SDK di Windows e agli assembly di runtime generati da C#/WinRT.

Il pacchetto NuGet C#/WinRT consente di creare e fare riferimento a propri assembly di interoperabilità WinRT personalizzati per i consumatori .NET. La versione più recente di C#/WinRT supporta anche la 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 mappature .NET dei tipi di Windows Runtime.

C#/WinRT supporta anche i componenti nel SDK per app di Windows, incluso WinUI 3. Il SDK per app di Windows solleva i controlli nativi dell'interfaccia utente Microsoft e altri componenti nativi all'esterno del 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 release notes 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 (WinMD) Windows. Pacchetto NuGet C#/WinRT (Microsoft.Windows. CsWinRT) include il compilatore C#/WinRT, cswinrt.exe, che è possibile usare per elaborare i file WinMD e generare .NET codice C#. 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 a cui le applicazioni .NET possono 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à 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

A partire da C#/WinRT versione 1.4.1, il supporto è incluso per l'incorporamento delle origini di proiezione e runtime dell'SDK di Windows sia per .NET che per .NET Standard 2.0 nell'output della libreria o dell'app. Ciò è utile nei casi in cui l'uso dei tipi SDK di Windows è 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 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 nativi C++ devono impostare la proprietà Windows Desktop Compatible su True tramite le proprietà del progetto o il file .vcxproj, per fare riferimento e inoltrare i binari di Microsoft.VCLibs.Desktop alle app che li utilizzano. In caso contrario, il pacchetto VCRT Forwarders verrà richiesto utilizzando le app 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 forniti o rilevati".

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

  <CsWinRTWindowsMetadata>10.0.19041.0</CsWinRTWindowsMetadata>
  

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

• 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 proprietà <TargetFramework> in modo da specificare una versione Windows specifica, ad esempio:

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

  Per ulteriori dettagli sulla proprietà <TargetFramework>, consultare la documentazione riguardante le API di Windows Runtime in Calling Windows Runtime APIs.

• 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à del progetto o tramite il file .vcxproj.

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 .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 tipi di Windows SDK nella propria superficie API.
Errore CS1705: L'assembly 'AssemblyName1' usa 'TypeName' con una versione successiva rispetto all'assembly di riferimento 'AssemblyName2'	Questo errore del compilatore si verifica quando si fa riferimento e si utilizzano tipi SDK di Windows esposti in una libreria.
System.IO.FileLoadException	Questo errore di runtime può verificarsi quando si chiamano determinate API in una libreria che non espone tipi SDK di Windows.

Per correggere questi errori, aggiornare .NET SDK alla versione più recente. In questo modo si assicura che il runtime e le versioni degli assembly nel Windows SDK utilizzate 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 GitHub C#/WinRT