Procedura: attivare e utilizzare un componente Windows Runtime mediante WRL

Articolo
10/12/2023

Questo documento illustra come usare la libreria di modelli C++ di Windows Runtime (WRL) per inizializzare Windows Runtime e come attivare e usare un componente Windows Runtime.

Per usare un componente, è necessario acquisire un puntatore di interfaccia al tipo implementato dal componente. Poiché la tecnologia sottostante di Windows Runtime è il Component Object Model (COM), è necessario seguire le regole COM per mantenere un'istanza del tipo. Ad esempio, è necessario mantenere il conteggio dei riferimenti che determina quando il tipo viene eliminato dalla memoria.

Per semplificare l'uso di Windows Runtime, la libreria di modelli C++ di Windows Runtime fornisce il modello di puntatore intelligente ComPtr <T>, che esegue automaticamente il conteggio dei riferimenti. Quando si dichiara una variabile, specificare ComPtr<l'identificatore interface-name>. Per accedere a un membro dell'interfaccia, applicare l'operatore arrow member-access (->) all'identificatore.

Importante

Quando si chiama una funzione di interfaccia, testare sempre il valore restituito HRESULT.

Attivazione e uso di un componente Windows Runtime

I passaggi seguenti usano l'interfaccia Windows::Foundation::IUriRuntimeClass per illustrare come creare una factory di attivazione per un componente Windows Runtime, creare un'istanza di tale componente e recuperare un valore della proprietà. Mostrano anche come inizializzare Windows Runtime. L'esempio completo segue.

Importante

Anche se in genere usi la libreria modelli C++ di Windows Runtime in un'app UWP (piattaforma UWP (Universal Windows Platform)), questo esempio usa un'app console per l'illustrazione. Le funzioni, wprintf_s ad esempio, non sono disponibili da un'app UWP. Per altre informazioni sui tipi e le funzioni che puoi usare in un'app UWP, vedi Funzioni CRT non supportate nelle app piattaforma UWP (Universal Windows Platform) e Win32 e COM per le app UWP.

Per attivare e usare un componente Windows Runtime

Includere (#include) tutte le intestazioni della libreria di modelli di Windows Runtime, Windows Runtime C++ o della libreria standard C++.
```
#include <Windows.Foundation.h>
#include <wrl\wrappers\corewrappers.h>
#include <wrl\client.h>
#include <stdio.h>

using namespace ABI::Windows::Foundation;
using namespace Microsoft::WRL;
using namespace Microsoft::WRL::Wrappers;
```
Si consiglia di utilizzare la direttiva using namespace nel file con estensione cpp per rendere il codice più leggibile.
Inizializzare il thread in cui viene eseguita l'app. Ogni app deve inizializzare il proprio modello di thread e threading. In questo esempio viene utilizzata la classe Microsoft::WRL::Wrappers::RoInitializeWrapper per inizializzare Windows Runtime e specifica RO_INIT_MULTITHREADED come modello di threading. La RoInitializeWrapper classe chiama Windows::Foundation::Initialize alla costruzione e Windows::Foundation::Uninitialize quando viene distrutta.
```
// Initialize the Windows Runtime.
RoInitializeWrapper initialize(RO_INIT_MULTITHREADED);
if (FAILED(initialize))
{
    return PrintError(__LINE__, initialize);
}
```
Nella seconda istruzione l'operatore RoInitializeWrapper::HRESULT restituisce dalla HRESULT chiamata a Windows::Foundation::Initialize.
Creare una factory di attivazione per l'interfaccia ABI::Windows::Foundation::IUriRuntimeClassFactory .
```
// Get the activation factory for the IUriRuntimeClass interface.
ComPtr<IUriRuntimeClassFactory> uriFactory;
HRESULT hr = GetActivationFactory(HStringReference(RuntimeClass_Windows_Foundation_Uri).Get(), &uriFactory);
if (FAILED(hr))
{
    return PrintError(__LINE__, hr);
}
```
Windows Runtime usa nomi completi per identificare i tipi. Il RuntimeClass_Windows_Foundation_Uri parametro è una stringa fornita da Windows Runtime e contiene il nome della classe di runtime richiesto.
Inizializzare una variabile Microsoft::WRL::Wrappers::HString che rappresenta l'URI "https://www.microsoft.com".
```
// Create a string that represents a URI.
HString uriHString;
hr = uriHString.Set(L"http://www.microsoft.com");
if (FAILED(hr))
{
    return PrintError(__LINE__, hr);
}
```
In Windows Runtime non allocare memoria per una stringa che verrà usata da Windows Runtime. Windows Runtime crea invece una copia della stringa in un buffer che gestisce e usa per le operazioni e quindi restituisce un handle al buffer creato.

Utilizzare il IUriRuntimeClassFactory::CreateUri metodo factory per creare un ABI::Windows::Foundation::IUriRuntimeClass oggetto .

// Create the IUriRuntimeClass object.
ComPtr<IUriRuntimeClass> uri;
hr = uriFactory->CreateUri(uriHString.Get(), &uri);
if (FAILED(hr))
{
    return PrintError(__LINE__, hr);
}

Chiamare il IUriRuntimeClass::get_Domain metodo per recuperare il valore della Domain proprietà .

// Get the domain part of the URI.
HString domainName;
hr = uri->get_Domain(domainName.GetAddressOf());
if (FAILED(hr))
{
    return PrintError(__LINE__, hr);
}

Stampare il nome di dominio nella console e restituire. Tutti gli oggetti ComPtr e RAII lasciano l'ambito e vengono rilasciati automaticamente.
```
// Print the domain name and return.
wprintf_s(L"Domain name: %s\n", domainName.GetRawBuffer(nullptr));

// All smart pointers and RAII objects go out of scope here.
```
La funzione WindowsGetStringRawBuffer recupera il formato Unicode sottostante della stringa URI.

Ecco l'esempio completo:

// wrl-consume-component.cpp
// compile with: runtimeobject.lib
#include <Windows.Foundation.h>
#include <wrl\wrappers\corewrappers.h>
#include <wrl\client.h>
#include <stdio.h>

using namespace ABI::Windows::Foundation;
using namespace Microsoft::WRL;
using namespace Microsoft::WRL::Wrappers;

// Prints an error string for the provided source code line and HRESULT
// value and returns the HRESULT value as an int.
int PrintError(unsigned int line, HRESULT hr)
{
    wprintf_s(L"ERROR: Line:%d HRESULT: 0x%X\n", line, hr);
    return hr;
}

int wmain()
{
    // Initialize the Windows Runtime.
    RoInitializeWrapper initialize(RO_INIT_MULTITHREADED);
    if (FAILED(initialize))
    {
        return PrintError(__LINE__, initialize);
    }

    // Get the activation factory for the IUriRuntimeClass interface.
    ComPtr<IUriRuntimeClassFactory> uriFactory;
    HRESULT hr = GetActivationFactory(HStringReference(RuntimeClass_Windows_Foundation_Uri).Get(), &uriFactory);
    if (FAILED(hr))
    {
        return PrintError(__LINE__, hr);
    }

    // Create a string that represents a URI.
    HString uriHString;
    hr = uriHString.Set(L"http://www.microsoft.com");
    if (FAILED(hr))
    {
        return PrintError(__LINE__, hr);
    }

    // Create the IUriRuntimeClass object.
    ComPtr<IUriRuntimeClass> uri;
    hr = uriFactory->CreateUri(uriHString.Get(), &uri);
    if (FAILED(hr))
    {
        return PrintError(__LINE__, hr);
    }

    // Get the domain part of the URI.
    HString domainName;
    hr = uri->get_Domain(domainName.GetAddressOf());
    if (FAILED(hr))
    {
        return PrintError(__LINE__, hr);
    }

    // Print the domain name and return.
    wprintf_s(L"Domain name: %s\n", domainName.GetRawBuffer(nullptr));

    // All smart pointers and RAII objects go out of scope here.
}
/*
Output:
Domain name: microsoft.com
*/

Compilazione del codice

Per compilare il codice, copiarlo e incollarlo in un progetto di Visual Studio oppure incollarlo in un file denominato wrl-consume-component.cpp e quindi eseguire il comando seguente in una finestra del prompt dei comandi di Visual Studio.

cl.exe wrl-consume-component.cpp runtimeobject.lib

Vedi anche

Libreria modelli C++ per Windows Runtime