Condividi tramite

Introduzione a C++/WinRT

 

 

C++/WinRT è una proiezione del linguaggio C++17 completamente standard per le API Windows Runtime (WinRT), implementata come libreria basata su file header e progettata per offrire un accesso privilegiato all'API Windows moderna. Con C++/WinRT, puoi creare e usare API di Windows Runtime usando qualsiasi compilatore C++17 conforme agli standard. Il Windows SDK include C++/WinRT. È stato 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 di modelli C++ per Windows Runtime (WRL). L'elenco completo degli argomenti di su C++/WinRT include informazioni sia sull'interoperabilità con, sia sulla migrazione da C++/CX e WRL.

Importante

Alcune delle parti più importanti di C++/WinRT da conoscere sono descritte nelle sezioni supporto SDK per C++/WinRT e supporto di Visual Studio per C++/WinRT, XAML, l'estensione VSIX e il pacchetto NuGet.

Vedi anche Dove è possibile trovare app di esempio C++/WinRT?.

Previsioni linguistiche

Il Windows Runtime si basa sulle API COM (Component Object Model), ed è progettato per l'accesso tramite proiezioni linguistiche . Una proiezione nasconde i dettagli COM e offre un'esperienza di programmazione più naturale per un determinato linguaggio.

Proiezione del linguaggio C++/WinRT nel contenuto di riferimento dell'API Windows Runtime

Quando si esplorano le API di Windows Runtime, fare clic sulla casella combinata linguaggio in alto a destra e selezionare C++/WinRT per visualizzare i blocchi di sintassi delle API come appaiono nella proiezione del linguaggio C++/WinRT.

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

Per il supporto di Visual Studio, è necessario Visual Studio 2022 o Visual Studio 2019 o Visual Studio 2017 (almeno la versione 15.6. È consigliabile almeno 15.7). Dal programma di installazione di Visual Studio, installare il carico di lavoro dello sviluppo della piattaforma UWP (Universal Windows Platform) . In Dettagli installazione>sviluppo della piattaforma UWP (Universal Windows Platform), selezionare l'opzione strumenti della Piattaforma Universale Windows C++ (v14x) se non l'hai già fatto. Inoltre, in Impostazioni> di WindowsPrivacy e sicurezza (Windows 10: Update & Security) >Per gli sviluppatori, abilitare l'opzione Modalità sviluppatore (Windows 10: non l'opzione Sideload apps).

Anche se è consigliabile sviluppare con le versioni più recenti di Visual Studio e Windows SDK, se si usa una versione di C++/WinRT fornita con Windows SDK precedente alla versione 10.0.17763.0 (Windows 10, versione 1809), per usare le intestazioni degli spazi dei nomi di Windows indicate in precedenza, è necessaria una versione di destinazione minima di Windows SDK nel progetto 10.0.17134.0 (Windows 10, versione 1803).

Visual Studio 2022 viene fornito con modelli di progetto e di elementi C++/WinRT incorporati, in modo da poter iniziare subito a sviluppare C++/WinRT. Include anche la visualizzazione del debug nativo di Visual Studio (natvis) dei tipi proiettati C++/WinRT, offrendo un'esperienza simile al debug C#. Natvis è automatico per le compilazioni di debug. Per ulteriori informazioni, vedere Visualizzazione Nativa del Debug di Visual Studio per C++/WinRT.

Per le versioni precedenti di Visual Studio, è necessario scaricare e installare la versione più recente del estensione visual Studio C++/WinRT (VSIX) dalla Visual Studio Marketplace.

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

I modelli di progetto di Visual Studio per C++/WinRT sono descritti nelle sezioni seguenti. Quando si crea un nuovo progetto C++/WinRT con la versione più recente dell'estensione VSIX installata, il nuovo progetto C++/WinRT installa automaticamente il pacchetto NuGet Microsoft.Windows.CppWinRT. Il pacchetto NuGet Microsoft.Windows.CppWinRT fornisce il supporto per la compilazione C++/WinRT (proprietà e destinazioni MSBuild), rendendo il progetto portabile tra un computer di sviluppo e un agente di compilazione (in cui è 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 aggiornato a) la versione più recente dell'estensione VSIX, aprire il progetto esistente in Visual Studio, fare clic su Progetto>Gestisci pacchetti NuGet...>Sfoglia, digitare o incollare Microsoft.Windows.CppWinRT nella casella di ricerca, selezionare l'elemento nei risultati della ricerca e quindi fare clic su Installa per installare il pacchetto per il progetto. Dopo aver aggiunto il pacchetto, riceverai il supporto C++/WinRT MSBuild per il progetto, incluso l'uso dello strumento cppwinrt.exe.

Importante

Se sono presenti progetti creati con (o aggiornati per funzionare) una versione dell'estensione VSIX precedente alla 1.0.190128.4, vedere versioni precedenti dell'estensione VSIX. Questa sezione contiene informazioni importanti sulla configurazione dei progetti, che è necessario sapere per aggiornarli per usare la versione più recente dell'estensione VSIX.

  • Poiché C++/WinRT usa funzionalità dello standard C++17, il pacchetto NuGet imposta la proprietà del progetto C/C++>Linguaggio>Standard del Linguaggio C++>Standard ISO C++17 (/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 codice C++/WinRT.
  • Si potrebbe anche voler impostare Modalità di conformità: Sì (/permissive-), che vincola ulteriormente il codice a essere conforme agli standard.
  • Un'altra proprietà del progetto da tenere presente è C/C++>Generale>considerare gli avvisi come errori. Impostare questa opzione su Yes(/WX) o No (/WX-) per il gusto. In alcuni casi, i file di origine generati dallo strumento cppwinrt.exe generano avvisi fino a quando non si aggiunge l'implementazione a tali file.

Dopo aver configurato il sistema come descritto in precedenza, sarà possibile 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 il tool cppwinrt.exe. È possibile puntare lo strumento di cppwinrt.exe in un file di metadati di Windows Runtime (.winmd) per generare una libreria C++ standard basata su file di intestazione che progetti le API descritte nei metadati per l'utilizzo dal codice C++/WinRT. I metadati di Windows Runtime (.winmd) offrono un modo canonico per descrivere una superficie dell'API di Windows Runtime. Puntando cppwinrt.exe a metadati, è possibile generare una libreria da usare con qualsiasi classe di runtime implementata in un componente Windows Runtime di seconda o terza parte o implementata nella propria applicazione. Per ulteriori informazioni, vedi Utilizzare API con C++/WinRT.

Con C++/WinRT, è anche possibile implementare classi di runtime personalizzate usando C++ standard, senza ricorrere alla programmazione in stile COM. Per una classe di runtime, è sufficiente descrivere i tipi in un file IDL e midl.exe e cppwinrt.exe generano automaticamente i file di codice sorgente boilerplate di implementazione. In alternativa, puoi semplicemente implementare le interfacce derivando da una classe di base C++/WinRT. Per ulteriori informazioni, vedi API dell'autore con C++/WinRT.

Per un elenco delle opzioni di personalizzazione per lo strumento di cppwinrt.exe, impostare tramite le proprietà del progetto, consultare il pacchetto NuGet Microsoft.Windows.CppWinRT leggimi.

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

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

Applicazione vuota (C++/WinRT)

Modello di progetto per un'app UWP (Universal Windows Platform) con un'interfaccia utente XAML.

Visual Studio offre il supporto del compilatore XAML per generare stub di implementazione e di intestazione a partire dal file IDL (Interface Definition Language) (.idl), che si trova dietro ogni file di markup XAML. In un file IDL, definisci le classi di runtime locali a cui vuoi fare riferimento nelle pagine XAML dell'app, e quindi compila il progetto una sola volta per generare modelli di implementazione in Generated Filese definizioni di tipi stub in Generated Files\sources. Quindi usa queste definizioni di tipo stub come riferimento, per implementare le classi locali del runtime. Consultare la fattorizzazione delle classi runtime nei file Midl (.idl).

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

App Core (C++/WinRT)

Modello di progetto per un'app UWP (Universal Windows Platform) che non usa XAML.

Invece, utilizza l'intestazione del namespace Windows C++/WinRT per il namespace Windows.ApplicationModel.Core. Dopo aver costruito ed eseguito, fare clic su uno spazio vuoto per aggiungere un quadrato colorato; quindi fare clic su un quadrato colorato per trascinarlo.

Applicazione Console Windows (C++/WinRT)

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

Applicazione desktop Windows (C++/WinRT)

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

Componente Windows Runtime (C++/WinRT)

Modello di progetto per un componente; in genere 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 quindi gli stub di implementazione e intestazione vengono generati dai metadati di Windows Runtime.

In un file IDL definire le classi di runtime nel componente, l'interfaccia predefinita e tutte le altre interfacce implementate. Compilare il progetto una sola volta per generare module.g.cpp, module.h.cpp, modelli di implementazione in Generated Filese definizioni dei tipi stub in Generated Files\sources. Usare quindi le definizioni dei tipi stub come riferimento per implementare le classi di runtime nel componente. Consultare la fattorizzazione delle classi runtime nei file Midl (.idl).

Unire il file binario del componente Windows Runtime costruito e il relativo .winmd con l'app UWP che li utilizza.

Versioni precedenti dell'estensione VSIX

È consigliabile installare (o aggiornare) la versione più recente dell'estensione VSIX . È configurato per l'aggiornamento automatico per impostazione predefinita. Se lo fai, e se hai progetti creati con una versione dell'estensione VSIX precedente alla 1.0.190128.4, questa sezione contiene informazioni importanti sull'aggiornamento di tali progetti per renderli compatibili con la nuova versione. Se non aggiorni, le informazioni in questa sezione ti saranno comunque utili.

In termini di versioni supportate di Windows SDK e Visual Studio e configurazione di Visual Studio, le informazioni contenute nella sezione supporto di Visual Studio per C++/WinRT, XAML, l'estensione VSIX e il pacchetto NuGet sezione precedente si applicano alle versioni precedenti dell'estensione VSIX. Le informazioni seguenti descrivono le differenze importanti relative al comportamento e alla configurazione dei progetti creati con (o aggiornati per lavorare con) versioni precedenti.

Creato prima della versione 1.0.181002.2

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

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

Puoi aggiornare il progetto installando manualmente il pacchetto NuGet Microsoft.Windows.CppWinRT. Dopo aver installato (o aggiornato a) la versione più recente dell'estensione VSIX, aprire il progetto in Visual Studio, fare clic su Progetto>Gestisci pacchetti NuGet...>Sfoglia, digitare o incollare Microsoft.Windows.CppWinRT nella casella di ricerca, selezionare l'elemento nei risultati della ricerca e quindi fare clic su Installa per installare il pacchetto per il progetto.

Creato con (o aggiornato a) 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, comprese, il pacchetto NuGet Microsoft.Windows.CppWinRT è stato automaticamente installato nel progetto dal modello di progetto. Anche un progetto meno recente potrebbe essere stato aggiornato per utilizzare una versione dell'estensione VSIX in questo intervallo. Se fosse stato così, poiché il supporto per la compilazione era ancora presente nelle versioni dell'estensione VSIX in questo intervallo, il progetto aggiornato potrebbe avere o meno il Microsoft.Windows.CppWinRT Pacchetto NuGet installato.

Per aggiornare il tuo progetto, segui le istruzioni riportate nella sezione precedente e assicurati che il pacchetto NuGet Microsoft.Windows.CppWinRT sia presente nel progetto.

Configurazioni di aggiornamento non valide

Con l'ultima versione dell'estensione VSIX, non è valido per un progetto avere la proprietà <CppWinRTEnabled>true</CppWinRTEnabled> se non ha installato anche il pacchetto NuGet Microsoft.Windows.CppWinRT. Un progetto con questa configurazione genera il messaggio di errore di compilazione: "Il VSIX di C++/WinRT non offre più supporto per la creazione del progetto." Si prega di aggiungere un riferimento di progetto al pacchetto NuGet Microsoft.Windows.CppWinRT.

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

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

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

Supporto SDK per C++/WinRT

Anche se è 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 basata su file di intestazione per l'utilizzo di API Windows di prima parte (API Windows Runtime negli spazi dei nomi Windows). Tali intestazioni si trovano 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 progetto.

Anche in caso di compatibilità, Windows SDK include anche lo strumento cppwinrt.exe. È tuttavia consigliabile installare e usare la versione più recente di cppwinrt.exe, inclusa nel pacchetto NuGet Microsoft.Windows.CppWinRT. Il pacchetto e il cppwinrt.exesono 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++. Tuttavia, prenderai anche consapevolezza di alcuni tipi di dati personalizzati nella proiezione e potrai decidere di usarli. Ad esempio, usiamo winrt::hstring nell'esempio di codice di avvio rapido in Introduzione a C++/WinRT.

winrt::com_array è un altro tipo che probabilmente userai ad un certo punto. Tuttavia, è meno probabile che si usi direttamente un tipo, ad esempio winrt::array_view. In alternativa, è possibile scegliere di non usarlo in modo da non avere codice da modificare se e quando viene visualizzato un tipo equivalente nella libreria standard C++.

Avvertimento

Ci sono anche tipi che potresti vedere se studi attentamente le intestazioni dello spazio dei nomi Windows C++/WinRT. Un esempio è winrt::param::hstring, ma ci sono anche esempi di raccolta. Sono disponibili esclusivamente per ottimizzare l'associazione dei parametri di input e producono grandi miglioramenti delle prestazioni e rendono la maggior parte dei modelli di chiamata "just work" per i tipi e i contenitori C++ standard correlati. Questi tipi vengono utilizzati dalla proiezione solo nei casi in cui apportano il massimo valore. Sono altamente ottimizzati e non sono per uso generico; non essere tentati di usarli da soli. Non dovresti neppure usare nulla dal namespace winrt::impl, poiché si tratta di tipi di implementazione e pertanto soggetti a modifiche. È consigliabile continuare a usare i tipi standard o i tipi dello spazio dei nomi winrt .

Consulta anche Passaggio di parametri nel limite ABI.

API importanti