Condividi tramite

Introduzione a C++/WinRT

  • Articolo

 

 

C++/WinRT è una proiezione del linguaggio C++ 17 interamente standard e moderna per le API di Windows Runtime (WinRT), implementata come libreria basata su file di intestazione e progettata per fornirti accesso privilegiato alla moderna API di Windows. Con C++/WinRT puoi creare e utilizzare API di Windows Runtime usando qualsiasi compilatore C++17 conforme agli standard. Windows SDK include C++/WinRT, introdotto nella versione 10.0.17134.0 (Windows 10, versione 1803).

C++/WinRT è la sostituzione consigliata da Microsoft per la proiezione del linguaggio C++/CX e la Libreria modelli C++ per Windows Runtime. L'elenco completo dei argomenti su C++/WinRT include informazioni sull'interoperabilità e sulla conversione da C++/CX e WRL.

Importante

Alcuni dei componenti più importanti di C++/WinRT da conoscere sono descritti nelle sezioni Supporto di SDK per C++/WinRT e Supporto di Visual Studio per C++/WinRT, XAML, l'estensione VSIX e il pacchetto NuGet.

Vedere anche Dove si possono trovare app di esempio C++/WinRT?

Proiezioni di linguaggio

Windows Runtime è basato sulle API COM (Component Object Model) ed è progettato per essere accessibile tramite proiezioni di linguaggio. Una proiezione nasconde i dettagli COM e offre un'esperienza di programmazione più naturale per un determinato linguaggio.

Proiezione di linguaggio C++/WinRT nel contenuto di riferimento delle API di Windows Runtime

Quando esplori le API di Windows Runtime, fai clic sulla casella combinata Linguaggio in alto a destra e seleziona C++/WinRT per visualizzare i blocchi di sintassi di API come appaiono nella proiezione di linguaggio C++/WinRT.

Supporto di Visual Studio per C++/WinRT, XAML, l'estensione VSIX e il pacchetto NuGet

Per il supporto di Visual Studio, è necessario Visual Studio 2022 o Visual Studio 2019, o Visual Studio 2017 (versione minima 15.6; si consiglia almeno 15.7). Dal programma di installazione di Visual Studio installare il carico di lavoro Sviluppo di app per la piattaforma UWP (Universal Windows Platform). In Dettagli di installazione>Sviluppo di app per la piattaforma UWP (Universal Windows Platform) seleziona una o più opzioni di Strumenti della piattaforma UWP (Universal Windows Platform) C++ (v14x), se non lo hai già fatto. E, in Impostazioni di Windows>Privacy & Sicurezza (Windows 10: Aggiorna & Sicurezza) >Per gli sviluppatori, abilitare l'opzione Modalità sviluppatore (Windows 10: non l'opzione App sideload).

Anche se è consigliabile usare le ultime versioni di Visual Studio e Windows SDK per lo sviluppo, se insieme a Windows SDK usi una versione di C++/WinRT precedente alla versione 10.0.17763.0 (Windows 10, versione 1809), sarà necessaria almeno la versione di destinazione 10.0.17134.0 di Windows SDK nel progetto (Windows 10, versione 1803) per usare le intestazioni degli spazi dei nomi sopra menzionate.

Visual Studio 2022 viene fornito con modelli di progetto e di elemento C++/WinRT incorporati, in modo da poter iniziare subito a sviluppare C++/WinRT. Viene inoltre fornito con la visualizzazione del debug nativo di Visual Studio (natvis) dei tipi proiettati C ++ / WinRT; fornendo un'esperienza simile al debug C#. Natvis è automatico per le build di debug. Per altre info, vedi Visualizzazione del debug nativo di Visual Studio per C++/WinRT.

Per le versioni precedenti di Visual Studio, è consigliabile scaricare e installare la versione più recente di Visual Studio Extension (VSIX) C++/WinRT da Visual Studio Marketplace.

  • L'estensione VSIX offre modelli di progetto e di elemento C++/WinRT in Visual Studio.
  • Inoltre, offre la visualizzazione del debug nativo di Visual Studio (natvis) dei tipi proiettati C++/WinRT.

I modelli di progetto di Visual Studio per C++/WinRT sono descritti nelle sezioni seguenti. Quando crei un nuovo progetto di C++/WinRT con l'ultima versione dell'estensione VSIX installata, verrà installato automaticamente il pacchetto NuGet Microsoft.Windows.CppWinRT. Il pacchetto NuGet Microsoft.Windows.CppWinRT fornisce il supporto per la compilazione in C++/WinRT (proprietà e destinazioni di MSBuild), rendendo il progetto portabile tra un computer di sviluppo e un agente di compilazione (in cui viene installato solo il pacchetto NuGet, e non l'estensione VSIX).

In alternativa, puoi convertire un progetto esistente installando manualmente il pacchetto NuGet Microsoft.Windows.CppWinRT. Dopo aver installato (o eseguito l'aggiornamento) alla versione più recente dell'estensione VSIX, apri il progetto esistente in Visual Studio, fai clic su Progetto> Gestisci pacchetti NuGet... >Sfoglia, digita o incolla Microsoft.Windows.CppWinRT nella casella di ricerca, seleziona l'elemento nei risultati della ricerca, quindi fai clic su Installa per installare il pacchetto per il progetto. Dopo che avrai aggiunto il pacchetto, otterrai il supporto MSBuild C++/WinRT per il progetto, inclusa la chiamata dello strumento cppwinrt.exe.

Importante

Se hai progetti che sono stati creati con (o aggiornati in modo da funzionare con) una versione dell'estensione VSIX precedente alla 1.0.190128.4, vedi Versioni precedenti dell'estensione VSIX. Questa sezione contiene informazioni importanti sulla configurazione dei progetti, che è necessario conoscere per eseguire l'aggiornamento in modo che usino l'ultima versione dell'estensione VSIX.

  • Dato che C++/WinRT usa funzionalità dallo standard C++17, il pacchetto NuGet imposta la proprietà del progetto C/C++>Linguaggio>Standard del linguaggio C++>ISO C++17 Standard (/std:c++17) in Visual Studio.
  • Aggiunge anche l'opzione del compilatore /bigobj.
  • Aggiunge l'opzione del compilatore /await per abilitare co_await.
  • Indica al compilatore XAML di generare istruzioni a partire dal codice C++/WinRT.
  • È anche possibile impostare la Modalità di conformità: Sì (/permissive-), che vincola ulteriormente il codice a essere conforme agli standard.
  • Un'altra proprietà di progetto da tenere presente è C/C++>Generale>Considera gli avvisi come errori. Imposta questa proprietà su Sì (/WX) o No (/WX-) a seconda delle esigenze. In alcuni casi, i file di origine generati dallo strumento cppwinrt.exe generano avvisi fino a quando non aggiungi l'implementazione.

Con il sistema impostato come descritto in precedenza, potrai creare e compilare, o aprire, un progetto C++/WinRT in Visual Studio e distribuirlo.

A partire dalla versione 2.0, il pacchetto NuGet Microsoft.Windows.CppWinRT include lo strumento cppwinrt.exe. È possibile puntare lo strumento cppwinrt.exe su un file di metadati di Windows Runtime (.winmd) per generare una libreria C++ standard basata su file di intestazione che proietta le API descritte nei metadati per l'utilizzo dal codice C++/WinRT. I file di metadati Windows Runtime (.winmd) forniscono un modo canonico di descrivere una superficie di API Windows Runtime. Puntando cppwinrt.exe sui metadati, puoi generare una libreria per l'uso con qualsiasi classe di runtime implementata in un componente Windows Runtime di seconda o terza parte o implementata nella tua applicazione. Per altre info, vedi Usare API con C++/WinRT.

Con C++/WinRT, puoi anche implementare le tue classi di runtime in C++ standard, senza ricorrere alla programmazione di tipo COM. Per una classe di runtime, è sufficiente descrivere i tipi in un file IDL, e midl.exe e cppwinrt.exe generano i file del codice sorgente boilerplate di implementazione per te. In alternativa puoi semplicemente implementare le interfacce eseguendo la derivazione dalla classe di base C++/WinRT. Per altre info, vedi Creare API con C++/WinRT.

Per un elenco di opzioni di personalizzazione per lo strumento cppwinrt.exe, impostate tramite le proprietà del progetto, vedi il file readme del pacchetto NuGet Microsoft.Windows.CppWinRT.

Puoi identificare un progetto che usa il supporto MSBuild C++/WinRT dalla presenza del pacchetto NuGet Microsoft.Windows.CppWinRT installato all'interno del progetto.

Ecco i modelli di progetto Visual Studio forniti dall'estensione VSIX.

Applicazione vuota (C++/WinRT)

Un modello di progetto per un'app della piattaforma UWP (Universal Windows Platform) con un'interfaccia utente XAML.

Visual Studio offre il supporto del compilatore XAML per generare stub di implementazione e intestazione dal file del linguaggio di definizione interfaccia (IDL) (.idl) che si trova dietro ogni file di markup XAML. In un file IDL, definisci tutte le classi di runtime locali a cui desideri fare riferimento nelle pagine XAML della tua app, quindi compila il progetto una volta per generare i modelli di implementazione in Generated Files e le definizioni dei tipi di stub in Generated Files\sources. Usa quindi queste definizioni dei tipi di stub come riferimento per implementare le classi di runtime locali. Vedi Factoring delle classi di runtime nei file Midl (.idl).

Il supporto dell'area di progettazione XAML in Visual Studio 2019 per C++/WinRT è vicino alla parità con C#. In Visual Studio 2019, è possibile usare la scheda Eventi della finestra Proprietà per aggiungere gestori di eventi all'interno di un progetto C++/WinRT. È anche possibile aggiungere gestori eventi al codice manualmente. Per altre informazioni, vedi Gestire eventi mediante i delegati in C++/WinRT.

App Core (C++/WinRT)

Un modello di progetto per un'app della piattaforma UWP (Universal Windows Platform) che non usa XAML.

Al contrario, usa l'intestazione dello spazio dei nomi Windows di C++/WinRT per lo spazio dei nomi Windows.ApplicationModel.Core. Dopo la compilazione e l'esecuzione, fai clic su uno spazio vuoto per aggiungere un quadrato colorato, quindi fai clic su un quadrato colorato per trascinarlo.

Applicazione console di Windows (C++/WinRT)

Un modello di progetto per un'applicazione client C++/WinRT per Windows Desktop, con un'interfaccia utente della console.

Applicazione desktop di Windows (C++/WinRT)

Un modello di progetto per un'applicazione client C++/WinRT per Windows Desktop, che visualizza un Windows.Foundation.Uri di Windows Runtime all'interno di una MessageBox di Win32.

Componente Windows Runtime (C++/WinRT)

Un modello di progetto per un componente, generalmente per l'utilizzo da una piattaforma UWP (Universal Windows Platform).

Questo modello illustra la toolchain midl.exe>cppwinrt.exe, in cui i metadati di Windows Runtime (.winmd) vengono generati da IDL e gli stub di implementazione e di intestazione vengono generati dai metadati di Windows Runtime.

In un file IDL, definisci le classi di runtime nel tuo componente, la loro interfaccia predefinita e qualunque altra interfaccia che implementano. Compila il progetto una volta per generare module.g.cpp, module.h.cpp, i modelli di implementazione in Generated Files e le definizioni del tipo di stub in Generated Files\sources. Quindi usa tali definizioni di tipo stub come riferimento per implementare le classi di runtime locali. Vedi Factoring delle classi di runtime nei file Midl (.idl).

Crea un bundle del file binario del componente Windows Runtime e del relativo file .winmd con l'app UWP che li usa.

Versioni precedenti dell'estensione VSIX

È consigliabile installare (o aggiornare) l'ultima versione dell'estensione VSIX. Per impostazione predefinita, la configurazione prevede l'aggiornamento automatico. Se esegui l'aggiornamento e hai progetti che sono stati creati con una versione dell'estensione VSIX precedente alla 1.0.190128.4, questa sezione contiene informazioni importanti sull'aggiornamento di quei progetti con la nuova versione. Se non esegui l'aggiornamento, troverai comunque utili le informazioni in questa sezione.

In termini di versioni supportate di Windows SDK e Visual Studio e di configurazione di Visual Studio, le informazioni nella precedente sezione Supporto di Visual Studio per C++/WinRT, XAML, l'estensione VSIX e il pacchetto NuGet si applicano alle versioni precedenti dell'estensione VSIX. Le informazioni seguenti descrivono le importanti differenze riguardanti il comportamento e la configurazione dei progetti creati (o aggiornati in modo da funzionare con) le versioni precedenti.

Creato prima della versione 1.0.181002.2

Se il progetto è stato creato con una versione dell'estensione VSIX precedente alla 1.0.181002.2, il supporto per la compilazione in C++/WinRT è stato integrato in tale versione dell'estensione VSIX. La proprietà <CppWinRTEnabled>true</CppWinRTEnabled> è impostata nel file .vcxproj del progetto.

<Project ...>
    <PropertyGroup Label="Globals">
        <CppWinRTEnabled>true</CppWinRTEnabled>
...

Puoi aggiornare il tuo progetto installando manualmente il pacchetto NuGet Microsoft.Windows.CppWinRT. Dopo aver installato (o eseguito l'aggiornamento) alla versione più recente dell'estensione VSIX, apri il progetto esistente in Visual Studio, fai clic su Progetto> Gestisci pacchetti NuGet...>Sfoglia, digita o incolla 9 Microsoft.Windows.CppWinRT nella casella di ricerca, seleziona l'elemento nei risultati della ricerca, quindi fai clic su Installa per installare il pacchetto per il progetto.

Creato con (o aggiornato a) una versione compresa tra 1.0.181002.2 e 1.0.190128.3

Se il progetto è stato creato con una versione dell'estensione VSIX compresa tra 1.0.181002.2 e 1.0.190128.3 incluse, il pacchetto NuGet Microsoft.Windows.CppWinRT è stato installato nel progetto automaticamente dal modello di progetto. Potresti anche aver aggiornato un progetto precedente in modo da usare una versione dell'estensione VSIX comprese in questo intervallo. In tal caso, dal momento che il supporto per la compilazione era ancora presente nelle versioni dell'estensione VSIX comprese in questo intervallo, il pacchetto NuGet Microsoft.Windows.CppWinRT può essere o non essere stato installato nel progetto aggiornato.

Per aggiornare il progetto, segui le istruzioni contenute nella sezione precedente e assicurati che nel progetto sia stato installato il pacchetto NuGet Microsoft.Windows.CppWinRT.

Configurazioni di aggiornamento non valide

Con la versione più recente dell'estensione VSIX, un progetto non può contenere la proprietà <CppWinRTEnabled>true</CppWinRTEnabled> se non ha anche il pacchetto NuGet Microsoft.Windows.CppWinRT installato. Un progetto con questa configurazione genera il messaggio di errore di compilazione: "The C++/WinRT VSIX no longer provides project build support. Please add a project reference to the Microsoft.Windows.CppWinRT Nuget package" (C++/WinRT VSIX non offre più il supporto per la compilazione dei progetti. Aggiungi un riferimento al progetto nel pacchetto NuGet Microsoft.Windows.CppWinRT).

Come indicato in precedenza, un progetto C++/WinRT deve ora includere il pacchetto NuGet installato.

Poiché l'elemento <CppWinRTEnabled> è obsoleto, è possibile modificare facoltativamente .vcxproj ed eliminare l'elemento. Non è strettamente necessario, ma è un'opzione.

Inoltre, se .vcxproj contiene <RequiredBundles>$(RequiredBundles);Microsoft.Windows.CppWinRT</RequiredBundles>, è possibile rimuoverlo per poter compilare senza richiedere l'installazione dell'estensione VSIX di C++WinRT.

Supporto di SDK per C++/WinRT

Benché sia ora presente solo per motivi di compatibilità, a partire dalla versione 10.0.17134.0 (Windows 10, versione 1803), Windows SDK contiene una libreria C++ standard basate su file di intestazione per l'utilizzo di API di Windows di terze parti (API Windows Runtime in spazi dei nomi Windows). Queste intestazioni sono all'interno della cartella %WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt. A partire da Windows SDK versione 10.0.17763.0 (Windows 10, versione 1809), queste intestazioni vengono generate automaticamente all'interno della cartella $(GeneratedFilesDir) del tuo progetto.

Anche in questo caso per la compatibilità, Windows SDK include anche lo strumento cppwinrt.exe. Tuttavia, è consigliabile invece installare e usare la versione più recente di cppwinrt.exe, inclusa con il pacchetto NuGet Microsoft.Windows.CppWinRT. Tale pacchetto, e cppwinrt.exe, sono descritti nelle sezioni precedenti.

Tipi personalizzati nella proiezione C++/WinRT

Nella programmazione C++/WinRT, puoi usare funzionalità del linguaggio C++ standard e tipi di dati C++ standard e C++/WinRT, inclusi alcuni tipi di dati della libreria standard C++, nella programmazione C++/WinRT. Ma verrai anche a conoscenza di alcuni tipi di dati personalizzati nella proiezione, che potrai scegliere di usare. Ad esempio, usiamo winrt::hstring nell'esempio di codice di avvio rapido in Informazioni di base su C++/WinRT.

winrt::com_array è un altro tipo che potresti usare in un determinato momento. Molto probabilmente non userai direttamente un tipo come winrt::array_view. Oppure puoi scegliere di non usarlo in modo da non avere codice da modificare se e quando viene visualizzato un tipo equivalente nella libreria standard C++.

Avviso

Esistono anche tipi che potresti vedere se studi attentamente le intestazioni dello spazio dei nomi Windows di C++/WinRT. Un esempio è winrt::param::hstring, ma esistono anche altri esempi di raccolta. Esistono esclusivamente per ottimizzare l'associazione di parametri di input e producono grandi miglioramenti delle prestazioni, e fanno in modo che la maggior parte dei motivi di chiamata "funzionino semplicemente" per i contenitori e tipi C++ standard correlati. Questi tipi vengono usati esclusivamente dalla proiezione nei casi in cui aggiungono maggiormente valore. Sono altamente ottimizzati e non sono per uso generale; non provare a usarli da solo. Non è inoltre consigliabile usare alcun oggetto dello spazio dei nomi winrt::impl, dal momento che si tratta di tipi di implementazione, quindi soggetti a modifica. È consigliabile continuare a usare tipi standard o tipi dello dello spazio dei nomi winrt.

Vedi anche Passaggio di parametri nel limite ABI.

API importanti