Libreria di modelli di Windows Runtime C++ (WRL)Windows Runtime C++ Template Library (WRL)

La libreria modelli C++ per Windows Runtime (WRL) è una libreria modello che offre un approccio di base per creare e usare componenti Windows Runtime.The Windows Runtime C++ Template Library (WRL) is a template library that provides a low-level way to author and use Windows Runtime components.

Nota

WRL è ora sostituito da C++/WinRT, una proiezione del linguaggio C++ 17 standard per le API Windows Runtime.WRL is now superseded by C++/WinRT, a standard C++17 language projection for Windows Runtime APIs. C++/WinRT è disponibile in Windows 10 SDK dalla versione 1803 in poi.C++/WinRT is available in the Windows 10 SDK from version 1803 onward. C++/WinRT viene implementato interamente nei file di intestazione e progettato per offrire all'utente l'accesso di prima classe alla moderna API Windows.C++/WinRT is implemented entirely in header files, and designed to provide you with first-class access to the modern Windows API.

Con C++/WinRT, è possibile utilizzare e creare Windows Runtime API utilizzando qualsiasi compilatore C++ 17 conforme agli standard.With C++/WinRT, you can both consume and author Windows Runtime APIs using any standards-compliant C++17 compiler. C++/WinRT in genere garantisce prestazioni migliori e produce binari più piccoli rispetto a qualsiasi altra opzione del linguaggio per il Windows Runtime.C++/WinRT typically performs better and produces smaller binaries than any other language option for the Windows Runtime. Microsoft continuerà a supportare C++/CX e WRL, ma è consigliabile usare C++/WinRT per le nuove applicazioni.We will continue to support C++/CX and WRL, but highly recommend that new applications use C++/WinRT. Per ulteriori informazioni, vedere C++/WinRT.For more information, see C++/WinRT.

VantaggiBenefits

La libreria di modelli Windows Runtime C++ consente di implementare e utilizzare più facilmente componenti Component Object Model (COM).The Windows Runtime C++ Template Library enables you to more easily implement and consume Component Object Model (COM) components. Fornisce tecniche di manutenzione come il conteggio dei riferimenti per gestire la durata degli oggetti e il test dei valori HRESULT per determinare se un'operazione ha avuto esito positivo o negativo.It provides housekeeping techniques like reference-counting to manage the lifetime of objects and testing HRESULT values to determine whether an operation succeeded or failed. Per utilizzare correttamente la libreria di modelli di Windows Runtime C++, è necessario seguire attentamente queste regole e tecniche.To successfully use the Windows Runtime C++ Template Library, you must carefully follow these rules and techniques.

C++/CX è una modalità di alto livello basata sul linguaggio per l'uso di componenti Windows Runtime.The C++/CX is a high-level, language-based way to use Windows Runtime components. Sia la libreria di modelli di Windows Runtime C++ che C++/CX semplificano la scrittura di codice per il Windows Runtime eseguendo automaticamente le attività di manutenzione per conto dell'utente.Both the Windows Runtime C++ Template Library and C++/CX simplify the writing of code for the Windows Runtime by automatically performing housekeeping tasks on your behalf.

La libreria di modelli Windows Runtime C++ e C++/CX offrono diversi vantaggi.The Windows Runtime C++ Template Library and C++/CX provide different benefits. Ecco alcuni motivi per cui si potrebbe voler usare la libreria di modelli di Windows Runtime C++ anziché C++/CX:Here are some reasons you might want to use the Windows Runtime C++ Template Library instead of C++/CX:

  • Windows Runtime libreria di modelli C++ aggiunge una piccola astrazione sulla Windows Runtime ABI (Application Binary Interface), offrendo la possibilità di controllare il codice sottostante per creare o utilizzare in modo più efficace Windows Runtime API.Windows Runtime C++ Template Library adds little abstraction over the Windows Runtime Application Binary Interface (ABI), giving you the ability to control the underlying code to better create or consume Windows Runtime APIs.

  • C++/CX rappresenta i valori HRESULT COM come eccezioni.C++/CX represents COM HRESULT values as exceptions. Se è stata ereditata una codebase che utilizza COM o una che non utilizza le eccezioni, è possibile che la Windows Runtime libreria di modelli C++ sia un modo più naturale per lavorare con l'Windows Runtime perché non è necessario utilizzare eccezioni.If you’ve inherited a code base that uses COM, or one that doesn’t use exceptions, you might find that the Windows Runtime C++ Template Library is a more natural way to work with the Windows Runtime because you don't have to use exceptions.

    Nota

    La libreria di modelli Windows Runtime C++ usa i valori HRESULT e non genera eccezioni.The Windows Runtime C++ Template Library uses HRESULT values and does not throw exceptions. Inoltre, la libreria di modelli Windows Runtime C++ utilizza i puntatori intelligenti e il modello RAII per garantire che gli oggetti vengano eliminati correttamente quando il codice dell'applicazione genera un'eccezione.In addition, the Windows Runtime C++ Template Library uses smart pointers and the RAII pattern to help guarantee that objects are destroyed correctly when your application code throws an exception. Per ulteriori informazioni sui puntatori intelligenti e RAII, vedere la pagina relativa alle risorse intelligenti per i puntatori e gli oggetti (RAII).For more info about smart pointers and RAII, see Smart Pointers and Objects Own Resources (RAII).

  • Lo scopo e la progettazione della libreria di modelli Windows Runtime C++ sono ispirati dalla Active Template Library (ATL), ovvero un set di classi C++ basate su modelli che semplificano la programmazione di oggetti COM.The purpose and design of the Windows Runtime C++ Template Library is inspired by the Active Template Library (ATL), which is a set of template-based C++ classes that simplify the programming of COM objects. Poiché Windows Runtime libreria di modelli C++ usa il linguaggio C++ standard per eseguire il wrapping del Windows Runtime, è possibile trasferire più facilmente e interagire con molti componenti COM esistenti scritti in ATL per il Windows Runtime.Because Windows Runtime C++ Template Library uses standard C++ to wrap the Windows Runtime, you can more easily port and interact with many existing COM components written in ATL to the Windows Runtime. Se si conosce già ATL, è possibile che Windows Runtime programmazione della libreria di modelli C++ sia più semplice.If you already know ATL, you might find that Windows Runtime C++ Template Library programming is easier.

IntroduzioneGetting Started

Di seguito sono riportate alcune risorse che consentono di lavorare immediatamente con la libreria di modelli di Windows Runtime C++.Here are some resources that can help you get working with the Windows Runtime C++ Template Library right away.

Libreria Windows Runtime (WRL)The Windows Runtime Library (WRL)
In questo video di Channel 9, Scopri di più su come la libreria di modelli di Windows Runtime C++ ti aiuta a scrivere le app piattaforma UWP (Universal Windows Platform) (UWP) e come creare e utilizzare Windows Runtime componenti.In this Channel 9 video, learn more about how the Windows Runtime C++ Template Library helps you write Universal Windows Platform (UWP) apps and how to author and consume Windows Runtime components.

Procedura: attivare e utilizzare un componente Windows RuntimeHow to: Activate and Use a Windows Runtime Component
Viene illustrato come utilizzare la libreria di modelli C++ Windows Runtime per inizializzare il Windows Runtime e attivare e utilizzare un componente Windows Runtime.Shows how to use the Windows Runtime C++ Template Library to initialize the Windows Runtime and activate and use a Windows Runtime component.

Procedura: completare operazioni asincroneHow to: Complete Asynchronous Operations
Viene illustrato come utilizzare la libreria di modelli C++ Windows Runtime per avviare le operazioni asincrone ed eseguire il lavoro quando le operazioni vengono completate.Shows how to use the Windows Runtime C++ Template Library to start asynchronous operations and perform work when the operations complete.

Procedura: gestire eventiHow to: Handle Events
Viene illustrato come utilizzare la libreria di modelli di Windows Runtime C++ per sottoscrivere e gestire gli eventi di un oggetto Windows Runtime.Shows how to use the Windows Runtime C++ Template Library to subscribe to and handle the events of a Windows Runtime object.

Procedura dettagliata: Creazione di un'app UWP tramite WRL e Media FoundationWalkthrough: Creating a UWP app using WRL and Media Foundation
Informazioni su come creare un'app UWP che usa Microsoft Media Foundation.Learn how to create a UWP app that uses Microsoft Media Foundation.

Procedura: creare un componente COM classicoHow to: Create a Classic COM Component
Viene illustrato come utilizzare la libreria di modelli C++ Windows Runtime per creare un componente COM di base e un metodo di base per registrare e utilizzare il componente COM da un'applicazione desktop.Shows how to use the Windows Runtime C++ Template Library to create a basic COM component and a basic way to register and consume the COM component from a desktop app.

Procedura: creare direttamente un'istanza dei componenti WRLHow to: Instantiate WRL Components Directly
Informazioni sull'utilizzo delle funzioni Microsoft::WRL::Details::MakeAndInitialize e Microsoft::WRL::Make per creare un'istanza di un componente dal modulo che lo definisce.Learn how to use the Microsoft::WRL::Make and Microsoft::WRL::Details::MakeAndInitialize functions to instantiate a component from the module that defines it.

Procedura: Usare winmdidl.exe e midlrt.exe per creare file con estensione h dai metadati di WindowsHow to: Use winmdidl.exe and midlrt.exe to create .h files from windows metadata
Viene illustrato come utilizzare i componenti personalizzati di Windows Runtime da WRL creando un file IDL dai metadati di .winmd.Shows how to consume custom Windows Runtime components from WRL by creating an IDL file from the .winmd metadata.

Procedura dettagliata: connessione tramite attività e richieste HTTP XMLWalkthrough: Connecting Using Tasks and XML HTTP Requests
Viene illustrato come utilizzare le interfacce IXMLHTTPRequest2 e IXMLHTTPRequest2Callback insieme alle attività per inviare richieste HTTP GET e post a un servizio Web in un'app UWP.Shows how to use the IXMLHTTPRequest2 and IXMLHTTPRequest2Callback interfaces together with tasks to send HTTP GET and POST requests to a web service in a UWP app.

Esempio dell'utilità di ottimizzazione dei viaggi di Bing MapsBing Maps Trip Optimizer sample
Usa la HttpRequest classe definita in procedura dettagliata: connessione tramite attività e richieste HTTP XML nel contesto di un'app UWP completa.Uses the HttpRequest class that's defined in Walkthrough: Connecting Using Tasks and XML HTTP Requests in the context of a complete UWP app.

Creazione di un esempio di componente DLL Windows Runtime con C++Creating a Windows Runtime DLL component with C++ sample
Viene illustrato come utilizzare la libreria di modelli C++ Windows Runtime per creare un componente DLL in-process e utilizzarlo da C++/CX, JavaScript e C#.Shows how to use the Windows Runtime C++ Template Library to create an in-process DLL component and consume it from C++/CX, JavaScript, and C#.

Esempio di gioco Marble Maze DirectXDirectX marble maze game sample
Viene illustrato come utilizzare la libreria di modelli C++ Windows Runtime per gestire la durata di componenti COM come DirectX e Media Foundation nel contesto di un gioco 3D completo.Demonstrates how to use the Windows Runtime C++ Template Library to manage the lifetime of COM components such as DirectX and Media Foundation in the context of a complete 3-D game.

Notifiche di tipo avviso popup da app desktopToast notifications from desktop apps
Viene illustrato come inviare notifiche di tipo avviso popup da un'applicazione desktop.Demonstrates how to send toast notifications from a desktop app.

Windows Runtime libreria di modelli C++ rispetto ad ATLWindows Runtime C++ Template Library Compared to ATL

Windows Runtime libreria di modelli C++ è simile al Active Template Library (ATL), perché è possibile usarla per creare oggetti COM piccoli e veloci.Windows Runtime C++ Template Library resembles the Active Template Library (ATL) because you can use it to create small, fast COM objects. Windows Runtime libreria di modelli C++ e ATL condividono anche concetti quali la definizione di oggetti nei moduli, la registrazione esplicita delle interfacce e la creazione aperta di oggetti tramite le factory.Windows Runtime C++ Template Library and ATL also share concepts such as definition of objects in modules, explicit registration of interfaces, and open creation of objects by using factories. Se si ha familiarità con ATL, è possibile che si abbia familiarità con Windows Runtime libreria di modelli C++.You might be comfortable with Windows Runtime C++ Template Library if you're familiar with ATL.

Windows Runtime libreria di modelli C++ supporta la funzionalità COM necessaria per le app UWP.Windows Runtime C++ Template Library supports the COM functionality that is required for UWP apps. Di conseguenza, differisce da ATL in quanto non include il supporto diretto alle funzionalità COM come:Therefore, it differs from the ATL because it omits direct support for COM features such as:

  • aggregationaggregation

  • implementazioni predefinitestock implementations

  • interfacce duali (IDispatch)dual interfaces (IDispatch)

  • interfacce dell'enumeratore standardstandard enumerator interfaces

  • punti di connessioneconnection points

  • interfacce tear-offtear-off interfaces

  • incorporamento OLEOLE embedding

  • Controlli ActiveXActiveX controls

  • COM+COM+

ConcettiConcepts

Windows Runtime libreria di modelli C++ fornisce tipi che rappresentano alcuni concetti di base.Windows Runtime C++ Template Library provides types that represent a few basic concepts. Nelle seguenti sezioni vengono descritti questi tipi.The following sections describe those types.

ComPtrComPtr

ComPtr è un tipo di puntatore intelligente che rappresenta l'interfaccia specificata dal parametro di modello.ComPtr is a smart pointer type that represents the interface that's specified by the template parameter. Utilizzare ComPtr per dichiarare una variabile che può accedere ai membri di un oggetto derivato dall'interfaccia.Use ComPtr to declare a variable that can access the members of an object that's derived from the interface. ComPtr mantiene automaticamente un conteggio dei riferimenti per un puntatore di interfaccia sottostante e rilascia l'interfaccia quando il conteggio dei riferimenti va a zero.ComPtr automatically maintains a reference count for the underlying interface pointer and releases the interface when the reference count goes to zero.

RuntimeClassRuntimeClass

RuntimeClass rappresenta una classe di cui è stata creata un'istanza che eredita un set di interfacce specificate.RuntimeClass represents an instantiated class that inherits a set of specified interfaces. Un RuntimeClass oggetto può fornire una combinazione di supporto per una o più Windows Runtime interfacce com o un riferimento debole a un componente.A RuntimeClass object can provide a combination of support for one or more Windows Runtime COM interfaces, or a weak reference to a component.

ModuloModule

Modulo rappresenta una raccolta di oggetti correlati.Module represents a collection of related objects. Un oggetto Module gestisce le class factory, che creano oggetti, e la registrazione, che consente alle altre applicazioni di utilizzare un oggetto.A Module object manages class factories, which create objects, and registration, which enables other applications to use an object.

CallbackCallback

La funzione Callback crea un oggetto la cui funzione membro è un gestore eventi (un metodo di callback).The Callback function creates an object whose member function is an event handler (a callback method). Utilizzare la funzione Callback per scrivere operazioni asincrone.Use the Callback function to write asynchronous operations.

EventSourceEventSource

EventSource viene utilizzato per gestire i gestori eventi del delegato .EventSource is used to manage delegate event handlers. Utilizzare Windows Runtime libreria di modelli C++ per implementare un delegato e utilizzare EventSource per aggiungere, rimuovere e richiamare delegati.Use Windows Runtime C++ Template Library to implement a delegate, and use EventSource to add, remove, and invoke delegates.

AsyncBaseAsyncBase

AsyncBase fornisce metodi virtuali che rappresentano il modello di programmazione asincrono Windows Runtime.AsyncBase provides virtual methods that represent the Windows Runtime asynchronous programming model. Eseguire l'override dei membri di questa classe per creare una classe personalizzata che consente di avviare, arrestare o controllare lo stato di avanzamento di un'operazione asincrona.Override the members in this class to create a custom class that can start, stop, or check the progress of an asynchronous operation.

FtmBaseFtmBase

FtmBase rappresenta un oggetto di gestore del marshalling con modello di threading Free.FtmBase represents a free-threaded marshaler object. FtmBase crea una tabella globale (GIT) dell'interfaccia e aiuta a gestire il marshalling e gli oggetti proxy.FtmBase creates a global interface table (GIT), and helps manage marshaling and proxy objects.

WeakRefWeakRef

WeakRef è un tipo di puntatore intelligente che rappresenta un riferimento debole che fa riferimento a un oggetto che potrebbe essere accessibile o meno.WeakRef is a smart-pointer type that represents a weak reference, which references an object that might or might not be accessible. Un WeakRef oggetto può essere usato solo da Windows Runtime e non da com classico.A WeakRef object can be used by only the Windows Runtime, and not by classic COM.

Un oggetto WeakRef in genere rappresenta un oggetto la cui esistenza è controllata da un thread o da un'applicazione esterna.A WeakRef object typically represents an object whose existence is controlled by an external thread or application. Ad esempio, un oggetto WeakRef può fare riferimento a un oggetto file.For example, a WeakRef object can reference a file object. Quando il file viene aperto, WeakRef è valido e il file a cui si fa riferimento è accessibile.When the file is open, the WeakRef is valid and the referenced file is accessible. Ma quando il file viene chiuso, WeakRef non è valido e il file non è accessibile.But when the file is closed, the WeakRef is invalid and the file is not accessible.

API chiave per categoriaKey APIs by Category
Evidenzia i tipi, le funzioni e le macro principali della libreria di modelli C++ Windows Runtime.Highlights the primary Windows Runtime C++ Template Library types, functions, and macros.

RiferimentoReference
Contiene informazioni di riferimento per la libreria di modelli di Windows Runtime C++.Contains reference information for the Windows Runtime C++ Template Library.

Riferimento rapido (C++/CX)Quick Reference (C++/CX)
Descrive brevemente le funzionalità C++/CX che supportano il Windows Runtime.Briefly describes the C++/CX features that support the Windows Runtime.

Uso di componenti Windows Runtime in Visual C++Using Windows Runtime Components in Visual C++
Viene illustrato come utilizzare C++/CX per creare un componente Windows Runtime di base.Shows how to use C++/CX to create a basic Windows Runtime component.