Introduzione a C++/WinRTGet started with C++/WinRT

Per iniziare velocemente a usare C++/WinRT, questo argomento presenta un esempio di codice semplice basato su un nuovo progetto Applicazione console di Windows (C++/WinRT) .To get you up to speed with using C++/WinRT, this topic walks through a simple code example based on a new Windows Console Application (C++/WinRT) project. Questo argomento illustra anche come aggiungere il supporto di C++/WinRT a un progetto di applicazione desktop di Windows.This topic also shows how to add C++/WinRT support to a Windows Desktop application project.

Nota

Anche se è consigliabile usare le versioni più recenti di Visual Studio e Windows SDK per lo sviluppo, se usi Visual Studio 2017 (versione 15.8.0 o successive) con Windows SDK versione 10.0.17134.0 (Windows 10 versione 1803) come destinazione, è possibile che la compilazione di un nuovo progetto C++/WinRT non riesca con l'errore "errore C3861: 'from_abi': identificatore non trovato" e con altri errori con origine in base.h.While we recommend that you develop with the latest versions of Visual Studio and the Windows SDK, if you're using Visual Studio 2017 (version 15.8.0 or higher), and targeting the Windows SDK version 10.0.17134.0 (Windows 10, version 1803), then a newly created C++/WinRT project may fail to compile with the error "error C3861: 'from_abi': identifier not found", and with other errors originating in base.h. La soluzione è selezionare una versione successiva (più conforme) di Windows SDK come destinazione oppure impostare la proprietà del progetto C/C++ > Linguaggio > Modalità di conformità: No (elimina anche /permissive- se compare nella proprietà del progetto C/C++ > Linguaggio > Riga di comando in Opzioni aggiuntive).The solution is to either target a later (more conformant) version of the Windows SDK, or set project property C/C++ > Language > Conformance mode: No (also, if /permissive- appears in project property C/C++ > Language > Command Line under Additional Options, then delete it).

Guida introduttiva a C++/WinRTA C++/WinRT quick-start

Nota

Per informazioni sulla configurazione di Visual Studio per lo sviluppo in C++/WinRT, compresi l'installazione e l'uso dell'estensione C++/WinRT per Visual Studio (VSIX) e del pacchetto NuGet, che insieme forniscono il modello di progetto e il supporto della compilazione, vedi Supporto di Visual Studio per C++/WinRT.For info about setting up Visual Studio for C++/WinRT development—including installing and using the C++/WinRT Visual Studio Extension (VSIX) and the NuGet package (which together provide project template and build support)—see Visual Studio support for C++/WinRT.

Crea un nuovo progetto Applicazione console di Windows (C++/WinRT) .Create a new Windows Console Application (C++/WinRT) project.

Modifica pch.h e main.cpp in modo che abbia questo aspetto.Edit pch.h and main.cpp to look like this.

// pch.h
#pragma once
#include <winrt/Windows.Foundation.Collections.h>
#include <winrt/Windows.Web.Syndication.h>
#include <iostream>
// main.cpp
#include "pch.h"

using namespace winrt;
using namespace Windows::Foundation;
using namespace Windows::Web::Syndication;

int main()
{
    winrt::init_apartment();

    Uri rssFeedUri{ L"https://blogs.windows.com/feed" };
    SyndicationClient syndicationClient;
    SyndicationFeed syndicationFeed = syndicationClient.RetrieveFeedAsync(rssFeedUri).get();
    for (const SyndicationItem syndicationItem : syndicationFeed.Items())
    {
        winrt::hstring titleAsHstring = syndicationItem.Title().Text();
        std::wcout << titleAsHstring.c_str() << std::endl;
    }
}

Vediamo in dettaglio il breve esempio di codice precedente e cosa succede in ogni parte.Let's take the short code example above piece by piece, and explain what's going on in each part.

#include <winrt/Windows.Foundation.Collections.h>
#include <winrt/Windows.Web.Syndication.h>

Con le impostazioni di progetto predefinite, le intestazioni incluse provengono da Windows SDK , all'interno della cartella %WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt.With the default project settings, the included headers come from the Windows SDK, inside the folder%WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt. Visual Studio include il percorso nella relativa macro IncludePath.Visual Studio includes that path in its IncludePath macro. Non è però presente una dipendenza rigida da Windows SDK, perché il progetto (tramite lo strumento cppwinrt.exe) genera le stesse intestazioni all'interno della cartella $(GeneratedFilesDir) del progetto.But there's no strict dependency on the Windows SDK, because your project (via the cppwinrt.exe tool) generates those same headers into your project's $(GeneratedFilesDir) folder. Le intestazioni verranno caricate da tale cartella se non è possibile trovarle altrove o se modifichi le impostazioni del progetto.They'll be loaded from that folder if they can't be found elsewhere, or if you change your project settings.

Le intestazioni contengono le API di Windows proiettate in C++/WinRT.The headers contain Windows APIs projected into C++/WinRT. In altre parole, per ogni tipo di Windows, C++/WinRT definisce un equivalente C++ adatto (chiamato tipo proiettato).In other words, for each Windows type, C++/WinRT defines a C++-friendly equivalent (called the projected type). Un tipo proiettato ha lo stesso nome completo del tipo Windows, ma viene posizionato nello spazio dei nomi winrt C++.A projected type has the same fully-qualified name as the Windows type, but it's placed in the C++ winrt namespace. L'inserimento di questi elementi nella tua intestazione precompilata riduce i tempi di compilazione incrementale.Putting these includes in your precompiled header reduces incremental build times.

Importante

Ogni volta che si vuole usare un tipo da uno spazio dei nomi di Windows, è necessario #include il file di intestazione dello spazio dei nomi di Windows C++/WinRT corrispondente, come indicato in precedenza.Whenever you want to use a type from a Windows namespaces, you must #include the corresponding C++/WinRT Windows namespace header file, as shown above. L'intestazione corrispondente è quella con lo stesso nome dello spazio dei nomi del tipo.The corresponding header is the one with the same name as the type's namespace. Ad esempio, per usare la proiezione C++/WinRT per la classe di runtime Windows::Foundation::Collections::PropertySet, includi l'intestazione winrt/Windows.Foundation.Collections.h.For example, to use the C++/WinRT projection for the Windows::Foundation::Collections::PropertySet runtime class, include the winrt/Windows.Foundation.Collections.h header.

Di solito l'intestazione di una proiezione C++/WinRT include automaticamente il relativo file di intestazione dello spazio dei nomi padre.It's usual for a C++/WinRT projection header to automatically include its parent namespace header file. Ad esempio, winrt/Windows.Foundation.Collections.h include winrt/Windows.Foundation.h.So, for example, winrt/Windows.Foundation.Collections.h includes winrt/Windows.Foundation.h. Tuttavia, è consigliabile non fare affidamento su questo comportamento, poiché si tratta di un dettaglio di implementazione che cambia nel tempo.But you shouldn't rely on this behavior, since it's an implementation detail that changes over time. È necessario includere in modo esplicito tutte le intestazioni necessarie.You must explicitly include any headers that you need.

using namespace winrt;
using namespace Windows::Foundation;
using namespace Windows::Web::Syndication;

Le direttive using namespace sono facoltative, ma convenienti.The using namespace directives are optional, but convenient. Il modello illustrato sopra per tali direttive (che consente la ricerca di nomi non qualificati per qualsiasi elemento all'interno dello spazio dei nomi winrt) è adatto per quando si sta iniziando un nuovo progetto e C++/WinRT è l'unica proiezione di linguaggio in uso all'interno di progetto.The pattern shown above for such directives (allowing unqualified name lookup for anything in the winrt namespace) is suitable for when you're beginning a new project and C++/WinRT is the only language projection you're using inside of that project. Se, invece, stai creando un mix di codice C++/WinRT con C++/CX e/o codice ABI (Application Binary Interface) dell'SDK (stai effettuando la conversione da o stai interoperando con uno o entrambi questi modelli), vedi gli argomenti Interoperabilità tra C++/WinRT e C++/CX, Passaggio a C++/WinRT da C++/CX e Interoperabilità tra C++/WinRT e l'ABI.If, on the other hand, you're mixing C++/WinRT code with C++/CX and/or SDK application binary interface (ABI) code (you're either porting from, or interoperating with, one or both of those models), then see the topics Interop between C++/WinRT and C++/CX, Move to C++/WinRT from C++/CX, and Interop between C++/WinRT and the ABI.

winrt::init_apartment();

La chiamata a winrt::init_apartment inizializza il thread in Windows Runtime in un apartment a thread multipli per impostazione predefinita.The call to winrt::init_apartment initializes the thread in the Windows Runtime; by default, in a multithreaded apartment. La chiamata inizializza anche COM.The call also initializes COM.

Uri rssFeedUri{ L"https://blogs.windows.com/feed" };
SyndicationClient syndicationClient;

Esegui l'allocazione in stack di due oggetti: rappresentano l'URI del blog di Windows e un client di diffusione.Stack-allocate two objects: they represent the uri of the Windows blog, and a syndication client. È necessario creare l'URI con un semplice valore letterale di stringa estesa (vedi Gestione delle stringhe in C++/WinRT per altri modi di utilizzo delle stringhe).We construct the uri with a simple wide string literal (see String handling in C++/WinRT for more ways you can work with strings).

SyndicationFeed syndicationFeed = syndicationClient.RetrieveFeedAsync(rssFeedUri).get();

SyndicationClient::RetrieveFeedAsync è un esempio di una funzione Windows Runtime asincrona.SyndicationClient::RetrieveFeedAsync is an example of an asynchronous Windows Runtime function. L'esempio di codice riceve un oggetto operazione asincrona da RetrieveFeedAsync e chiama get su tale oggetto per bloccare il thread di chiamata e attendere il risultato (un feed di diffusione, in questo caso).The code example receives an asynchronous operation object from RetrieveFeedAsync, and it calls get on that object to block the calling thread and wait for the result (which is a syndication feed, in this case). Per altre informazioni sulla concorrenza e per le tecniche non bloccanti, vedi Concorrenza e operazioni asincrone con C++/WinRT.For more about concurrency, and for non-blocking techniques, see Concurrency and asynchronous operations with C++/WinRT.

for (const SyndicationItem syndicationItem : syndicationFeed.Items()) { ... }

SyndicationFeed.Items è un intervallo, definito dagli iteratori restituiti dalle funzioni begin e end (o le relative varianti costante, inversa e costante-inversa).SyndicationFeed.Items is a range, defined by the iterators returned from begin and end functions (or their constant, reverse, and constant-reverse variants). Per questo motivo, puoi enumerare Items con un'istruzione for basata sull'intervallo o con la funzione modello std:: for_each.Because of this, you can enumerate Items with either a range-based for statement, or with the std::for_each template function. Ogni volta che esegui un'iterazione di una raccolta di Windows Runtime in questo modo, dovrai usare #include <winrt/Windows.Foundation.Collections.h>.Whenever you iterate over a Windows Runtime collection like this, you'll need to #include <winrt/Windows.Foundation.Collections.h>.

winrt::hstring titleAsHstring = syndicationItem.Title().Text();
std::wcout << titleAsHstring.c_str() << std::endl;

Ottiene il testo del titolo del feed, come oggetto winrt::hstring (altri dettagli sono disponibili in Gestione delle stringhe in C++/WinRT).Gets the feed's title text, as a winrt::hstring object (more details in String handling in C++/WinRT). Viene quindi effettuato l'output dell'oggetto hstring, tramite la funzione c_str che riflette il motivo usato con le stringhe della libreria C++ standard.The hstring is then output, via the c_str function, which reflects the pattern used with C++ Standard Library strings.

Come puoi vedere, C++/WinRT incoraggia espressioni C++ moderne e di tipo classe, come syndicationItem.Title().Text().As you can see, C++/WinRT encourages modern, and class-like, C++ expressions such as syndicationItem.Title().Text(). Si tratta di uno stile di programmazione più fluido e diverso rispetto alla programmazione COM tradizionale.This is a different, and cleaner, programming style from traditional COM programming. Non devi inizializzare direttamente COM, né usare i puntatori COM.You don't need to directly initialize COM, nor work with COM pointers.

Non è neanche necessario gestire codici di restituzione HRESULT.Nor do you need to handle HRESULT return codes. C++/WinRT converte gli HRESULT di errore in eccezioni quali winrt::hresult-error per uno stile di programmazione naturale e moderno.C++/WinRT converts error HRESULTs to exceptions such as winrt::hresult-error for a natural and modern programming style. Per altre informazioni sulla gestione degli errori e gli esempi di codice, vedi Gestione degli errori con C++/WinRT.For more info about error-handling, and code examples, see Error handling with C++/WinRT.

Modificare un progetto di applicazione desktop di Windows per aggiungere il supporto di C++/WinRTModify a Windows Desktop application project to add C++/WinRT support

Questa sezione illustra come è possibile aggiungere il supporto di C++/WinRT a un progetto di applicazione desktop di Windows esistente.This section shows you how you can add C++/WinRT support to a Windows Desktop application project that you might have. Se non è disponibile un progetto di applicazione desktop di Windows, puoi seguire questi passaggi creandone prima di tutto uno.If you don't have an existing Windows Desktop application project, then you can follow along with these steps by first creating one. Ad esempio, apri Visual Studio e crea un progetto Visual C++ > Desktop di Windows > Applicazione desktop di Windows.For example, open Visual Studio and create a Visual C++ > Windows Desktop > Windows Desktop Application project.

Puoi installare facoltativamente l'Estensione di Visual Studio C++/WinRT (VSIX) e il pacchetto NuGet.You can optionally install the C++/WinRT Visual Studio Extension (VSIX) and the NuGet package. Per informazioni dettagliate, vedi Supporto di Visual Studio per C++/WinRT.For details, see Visual Studio support for C++/WinRT.

Impostare le proprietà del progettoSet project properties

Passa alla proprietà del progetto Generale > Versione di Windows SDK e seleziona Tutte le configurazioni e Tutte le piattaforme.Go to project property General > Windows SDK Version, and select All Configurations and All Platforms. Assicurati che l'opzione Versione di Windows SDK sia impostata su 10.0.17134.0 (Windows 10, versione 1803) o versione successiva.Ensure that Windows SDK Version is set to 10.0.17134.0 (Windows 10, version 1803) or greater.

Verifica che non esistano le condizioni descritte in Per quale motivo il mio nuovo progetto non viene compilato?.Confirm that you're not affected by Why won't my new project compile?.

Dato che C++/WinRT usa funzionalità dallo standard C++17, imposta la proprietà del progetto C/C++ > Linguaggio > Standard del linguaggio C++ su Standard C++17 ISO (/std:c++17) .Because C++/WinRT uses features from the C++17 standard, set project property C/C++ > Language > C++ Language Standard to ISO C++17 Standard (/std:c++17).

Intestazione precompilataThe precompiled header

Il modello di progetto predefinito crea un'intestazione precompilata, denominata framework.h o stdafx.h.The default project template creates a precompiled header for you, named either framework.h, or stdafx.h. Rinominala pch.h.Rename that to pch.h. Se hai un file stdafx.cpp rinominalo pch.cpp.If you have a stdafx.cpp file, then rename that to pch.cpp. Imposta la proprietà del progetto C/C++ > Intestazioni precompilate > Intestazione precompilata su Crea (/Yc) e File di intestazione precompilato su pch.h.Set project property C/C++ > Precompiled Headers > Precompiled Header to Create (/Yc), and Precompiled Header File to pch.h.

Trova e sostituisci tutte le occorrenze di #include "framework.h" (o #include "stdafx.h") con #include "pch.h".Find and replace all #include "framework.h" (or #include "stdafx.h") with #include "pch.h".

In pch.h includi winrt/base.h.In pch.h, include winrt/base.h.

// pch.h
...
#include <winrt/base.h>

Il collegamentoLinking

La proiezione del linguaggio C++/WinRT dipende da determinate funzioni libere (non membro) di Windows Runtime e da punti di ingresso, che richiedono il collegamento della libreria generica WindowsApp.lib.The C++/WinRT language projection depends on certain Windows Runtime free (non-member) functions, and entry points, that require linking to the WindowsApp.lib umbrella library. In questa sezione vengono descritti tre modi per soddisfare il linker.This section describes three ways of satisfying the linker.

La prima opzione consiste nell'aggiungere al progetto di Visual Studio tutte le proprietà e le destinazioni MSBuild C++/WinRT.The first option is to add to your Visual Studio project all of the C++/WinRT MSBuild properties and targets. A tale scopo, installa il pacchetto NuGet Microsoft.Windows.CppWinRT nel progetto.To do this, install the Microsoft.Windows.CppWinRT NuGet package into your project. Apri il progetto 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 e quindi fai clic su Installa per installare il pacchetto per il progetto.Open the project in Visual Studio, click Project > Manage NuGet Packages... > Browse, type or paste Microsoft.Windows.CppWinRT in the search box, select the item in search results, and then click Install to install the package for that project.

Puoi anche usare le impostazioni dei collegamenti di progetto per il collegamento esplicito di WindowsApp.lib.You can also use project link settings to explicitly link WindowsApp.lib. In alternativa, puoi farlo nel codice sorgente (in pch.h, ad esempio) come indicato di seguito.Or, you can do it in source code (in pch.h, for example) like this.

#pragma comment(lib, "windowsapp")

Puoi ora eseguire la compilazione e il collegamento, quindi aggiungere codice C++/WinRT al progetto (ad esempio codice simile a quello nella sezione precedente Guida introduttiva a C++/WinRT).You can now compile and link, and add C++/WinRT code to your project (for example, code similar to that shown in the A C++/WinRT quick-start section, above).

Tre scenari principali per C++/WinRTThe three main scenarios for C++/WinRT

Man mano che usi C++/WinRT acquisendo familiarità con questa proiezione di linguaggio e che esamini il resto di questa documentazione, probabilmente noterai che si verificano tre scenari principali, come illustrato nelle sezioni seguenti.As you use and become familiar with C++/WinRT, and work through the rest of the documentation here, you'll likely notice that there are three main scenarios, as described in the following sections.

Utilizzo di API e tipi di Windows RuntimeConsuming Windows Runtime APIs and types

In questo caso, si fa riferimento all'uso o alla chiamata di API,In other words, using, or calling APIs. ad esempio l'esecuzione di chiamate API per la comunicazione tramite Bluetooth, per lo streaming e la presentazione di video, per l'integrazione con la shell di Windows e così via.For example, making API calls to communicate using Bluetooth; to stream and present video; to integrate with the Windows shell; and so on. C++/WinRT supporta completamente questa categoria di scenario.C++/WinRT fully and uncompromisingly supports this category of scenario. Per altre info, vedi Usare API con C++/WinRT.For more info, see Consume APIs with C++/WinRT.

Creazione di API e tipi di Windows RuntimeAuthoring Windows Runtime APIs and types

In questo caso, per creazione si intende la produzione di API e di tipi,In other words, producing APIs and types. ad esempio la produzione di API come quelle illustrate nella sezione precedente oppure di API grafiche, API di archiviazione e del file system, API per le funzionalità di rete e così via.For example, producing the kinds of APIs described in the section above; or the graphics APIs; the storage and file system APIs; the networking APIs, and so on. Per altre info, vedi Creare API con C++/WinRT.For more info, see Author APIs with C++/WinRT.

La creazione di API con C++/WinRT è un'attività leggermente più complessa rispetto al semplice utilizzo perché devi usare IDL per definire la forma dell'API prima di poterla implementare.Authoring APIs with C++/WinRT is a little more involved than consuming them, because you must use IDL to define the shape of the API before you can implement it. Per comprendere come procedere, vedi la procedura dettagliata in Controlli XAML, binding a una proprietà C++/WinRT.There's a walkthrough of doing that in XAML controls; bind to a C++/WinRT property.

Applicazioni XAMLXAML applications

Questo scenario riguarda la creazione di applicazioni e controlli nel framework interfaccia utente XAML.This scenario is about building applications and controls on the XAML UI framework. L'attività di sviluppo di un'applicazione XAML è il risultato di una combinazione di utilizzo e creazione.Working in a XAML application amounts to a combination of consuming and authoring. Tuttavia, dal momento che XAML attualmente è il framework interfaccia utente predominante in Windows e che la relativa influenza su Windows Runtime è proporzionale a tale predominanza, è opportuno parlare di una categoria di scenario a parte.But since XAML is the dominant UI framework on Windows today, and its influence over the Windows Runtime is proportionate to that, it deserves its own category of scenario.

Tieni presente che XAML funziona in modo ottimale con linguaggi di programmazione che offrono la reflection.Be aware that XAML works best with programming languages that offer reflection. In C++/WinRT devi a volte eseguire alcune operazioni aggiuntive per interagire con il framework XAML.In C++/WinRT, you sometimes have to do a little extra work in order to interoperate with the XAML framework. Tutti questi casi vengono trattati nella documentazione.All of those cases are covered in the documentation. Per iniziare, vedi Controlli XAML, binding a una proprietà C++/WinRT e Controlli (basati su modelli) personalizzati XAML con C++/WinRT.Good places to start are XAML controls; bind to a C++/WinRT property and XAML custom (templated) controls with C++/WinRT.

App di esempio scritte in C++ /WinRTSample apps written in C++/WinRT

Vedere Dove si possono trovare app di esempio C++/WinRT?.See Where can I find C++/WinRT sample apps?.

API importantiImportant APIs