Transição do WRL para C++/WinRT

Este tópico mostra como portar wrl (Biblioteca de Modelos C++) do Windows Runtime código para seu equivalente em C++/WinRT.

A primeira etapa na migração para C++/WinRT é adicionar manualmente o suporte para C++/WinRT ao seu projeto (consulte suporte do Visual Studio para C++/WinRT). Para fazer isso, instale o pacote NuGet Microsoft.Windows.CppWinRT em seu projeto. Abra o projeto no Visual Studio, clique em Projeto>Gerenciar Pacotes NuGet...>Procurar, digite ou cole Microsoft.Windows.CppWinRT na caixa de pesquisa, selecione o item nos resultados da pesquisa e clique em Instalar para instalar o pacote para esse projeto. Um efeito dessa alteração é que o suporte para C++/CX está desativado no projeto. Se você estiver usando C++/CX no projeto, poderá manter o suporte desativado e atualizar seu código C++/CX para C++/WinRT também (consulte Mover para C++/WinRT do C++/CX). Ou você pode ativar o suporte novamente (nas propriedades do projeto, C/C++>Geral>Extensão de Runtime do Windows>Sim (/ZW)) e primeiro se concentrar em portar seu código WRL. O código C++/CX e C++/WinRT pode coexistir no mesmo projeto, com exceção do suporte ao compilador XAML e componentes do Windows Runtime (consulte Mover para C++/WinRT do C++/CX).

Defina a propriedade geral do projeto >para a versão da Plataforma de Destino como 10.0.17134.0 (Windows 10, versão 1803) ou superior.

No arquivo de cabeçalho pré-compilado (geralmente pch.h), inclua winrt/base.h.

#include <winrt/base.h>

Se você incluir quaisquer cabeçalhos de API do Windows projetados para C++/WinRT (por exemplo, winrt/Windows.Foundation.h), não será necessário incluir explicitamente winrt/base.h assim porque ele será incluído automaticamente para você.

Portando ponteiros inteligentes WRL COM (Microsoft::WRL::ComPtr)

Portar qualquer código que use Microsoft::WRL::ComPtr<T> para utilizar winrt::com_ptr<T>. Aqui está um exemplo de código antes e depois. Na versão após, a função membro com_ptr::put recupera o ponteiro bruto subjacente para que ele possa ser definido.

ComPtr<IDXGIAdapter1> previousDefaultAdapter;
DX::ThrowIfFailed(m_dxgiFactory->EnumAdapters1(0, &previousDefaultAdapter));

winrt::com_ptr<IDXGIAdapter1> previousDefaultAdapter;
winrt::check_hresult(m_dxgiFactory->EnumAdapters1(0, previousDefaultAdapter.put()));

Importante

Se você tiver um winrt::com_ptr já configurado (seu ponteiro cru interno já tem um destino) e deseja reconfigurá-lo para apontar para um objeto diferente, primeiro você precisará atribuir nullptr a ele, conforme mostrado no exemplo de código abaixo. Se você não fizer isso, um com_ptr já estabelecido chamará sua atenção (quando você chamar com_ptr::put ou com_ptr::put_void), por afirmar que seu ponteiro interno não é nulo.

winrt::com_ptr<IDXGISwapChain1> m_pDXGISwapChain1;
...
// We execute the code below each time the window size changes.
m_pDXGISwapChain1 = nullptr; // Important because we're about to re-seat 
winrt::check_hresult(
    m_pDxgiFactory->CreateSwapChainForHwnd(
        m_pCommandQueue.get(), // For Direct3D 12, this is a pointer to a direct command queue, and not to the device.
        m_hWnd,
        &swapChainDesc,
        nullptr,
        nullptr,
        m_pDXGISwapChain1.put())
);

Neste próximo exemplo (na versão após), a função membro com_ptr::put_void recupera o ponteiro bruto subjacente como um ponteiro para um ponteiro para void.

ComPtr<ID3D12Debug> debugController;
if (SUCCEEDED(D3D12GetDebugInterface(IID_PPV_ARGS(&debugController))))
{
    debugController->EnableDebugLayer();
}

winrt::com_ptr<ID3D12Debug> debugController;
if (SUCCEEDED(D3D12GetDebugInterface(__uuidof(debugController), debugController.put_void())))
{
    debugController->EnableDebugLayer();
}

Substitua ComPtr::Get por com_ptr::get.

m_d3dDevice->CreateDepthStencilView(m_depthStencil.Get(), &dsvDesc, m_dsvHeap->GetCPUDescriptorHandleForHeapStart());

m_d3dDevice->CreateDepthStencilView(m_depthStencil.get(), &dsvDesc, m_dsvHeap->GetCPUDescriptorHandleForHeapStart());

Quando você quiser passar o ponteiro bruto para uma função que espera um ponteiro para IUnknown, use a função independente winrt::get_unknown, conforme mostrado neste próximo exemplo.

ComPtr<IDXGISwapChain1> swapChain;
DX::ThrowIfFailed(
    m_dxgiFactory->CreateSwapChainForCoreWindow(
        m_commandQueue.Get(),
        reinterpret_cast<IUnknown*>(m_window.Get()),
        &swapChainDesc,
        nullptr,
        &swapChain
    )
);

winrt::agile_ref<winrt::Windows::UI::Core::CoreWindow> m_window; 
winrt::com_ptr<IDXGISwapChain1> swapChain;
winrt::check_hresult(
    m_dxgiFactory->CreateSwapChainForCoreWindow(
        m_commandQueue.get(),
        winrt::get_unknown(m_window.get()),
        &swapChainDesc,
        nullptr,
        swapChain.put()
    )
);

Portando um módulo WRL (Microsoft::WRL::Module)

Esta seção refere-se ao código de portabilidade que usa o tipo Microsoft::WRL::Module.

Você pode adicionar gradualmente o código C++/WinRT a um projeto existente que usa WRL para implementar um componente e suas classes WRL existentes continuarão a ter suporte. Esta seção mostra como.

Se você criar um novo Componente do Windows Runtime (C++/WinRT) tipo de projeto no Visual Studio e compilar, o arquivo Generated Files\module.g.cpp será gerado para você. Esse arquivo contém as definições de duas funções C++/WinRT úteis (listadas abaixo), que você pode copiar e adicionar ao seu projeto. Essas funções são WINRT_CanUnloadNow e WINRT_GetActivationFactory e, como você pode ver, elas chamam condicionalmente WRL para dar suporte a qualquer estágio de portabilidade em que você esteja.

HRESULT WINRT_CALL WINRT_CanUnloadNow()
{
#ifdef _WRL_MODULE_H_
    if (!::Microsoft::WRL::Module<::Microsoft::WRL::InProc>::GetModule().Terminate())
    {
        return S_FALSE;
    }
#endif

    if (winrt::get_module_lock())
    {
        return S_FALSE;
    }

    winrt::clear_factory_cache();
    return S_OK;
}

HRESULT WINRT_CALL WINRT_GetActivationFactory(HSTRING classId, void** factory)
{
    try
    {
        *factory = nullptr;
        wchar_t const* const name = WINRT_WindowsGetStringRawBuffer(classId, nullptr);

        if (0 == wcscmp(name, L"MoveFromWRLTest.Class"))
        {
            *factory = winrt::detach_abi(winrt::make<winrt::MoveFromWRLTest::factory_implementation::Class>());
            return S_OK;
        }

#ifdef _WRL_MODULE_H_
        return ::Microsoft::WRL::Module<::Microsoft::WRL::InProc>::GetModule().GetActivationFactory(classId, reinterpret_cast<::IActivationFactory**>(factory));
#else
        return winrt::hresult_class_not_available().to_abi();
#endif
    }
    catch (...) { return winrt::to_hresult(); }
}

Depois de ter essas funções em seu projeto, em vez de chamar Module::GetActivationFactory diretamente, chame WINRT_GetActivationFactory (que chama a função WRL internamente). Aqui está um exemplo de código antes e depois.

HRESULT WINAPI DllGetActivationFactory(_In_ HSTRING activatableClassId, _Out_ ::IActivationFactory **factory)
{
    auto & module = Microsoft::WRL::Module<Microsoft::WRL::InProc>::GetModule();
    return module.GetActivationFactory(activatableClassId, factory);
}

HRESULT __stdcall WINRT_GetActivationFactory(HSTRING activatableClassId, void** factory);
HRESULT WINAPI DllGetActivationFactory(_In_ HSTRING activatableClassId, _Out_ ::IActivationFactory **factory)
{
    return WINRT_GetActivationFactory(activatableClassId, reinterpret_cast<void**>(factory));
}

Em vez de chamar diretamente Module::Terminate, chame WINRT_CanUnloadNow (que, internamente, chama a função WRL). Aqui está um exemplo de código antes e depois.

HRESULT __stdcall DllCanUnloadNow(void)
{
    auto &module = Microsoft::WRL::Module<Microsoft::WRL::InProc>::GetModule();
    HRESULT hr = (module.Terminate() ? S_OK : S_FALSE);
    if (hr == S_OK)
    {
        hr = ...
    }
    return hr;
}

HRESULT __stdcall WINRT_CanUnloadNow();
HRESULT __stdcall DllCanUnloadNow(void)
{
    HRESULT hr = WINRT_CanUnloadNow();
    if (hr == S_OK)
    {
        hr = ...
    }
    return hr;
}

Portabilidade wrappers Microsoft::WRL::Wrappers

Esta seção refere-se a portar código que usa os wrappers Microsoft::WRL::Wrappers .

Como você pode ver na tabela abaixo, para substituir os auxiliares de encadeamento, recomendamos que você use a biblioteca de suporte de thread do padrão C++ . Um mapeamento um-para-um dos WRL wrappers pode ser enganoso, uma vez que sua escolha depende de suas necessidades. Além disso, alguns tipos que podem parecer mapeamentos óbvios são novos no padrão C++20, portanto, eles serão impraticáveis se você ainda não tiver atualizado.

Tipo	Notas sobre portabilidade
classe CriticalSection	Utilize a biblioteca de suporte de thread
classe de evento (WRL)	Use o modelo de struct winrt::event
de classe HandleT	Use o struct winrt::handle ou o struct winrt::file_handle
classe HString	Use struct winrt::hstring
classe HStringReference	Sem substituição, porque o C++/WinRT lida com isso internamente de uma maneira tão eficiente quanto HStringReference com a vantagem que você não precisa pensar sobre isso.
de classe Mutex	Utilize a biblioteca de suporte de thread
classe RoInitializeWrapper	Use winrt::init_apartment e winrt::uninit_apartment; ou escreva seu próprio wrapper trivial ao redor de CoInitializeEx e CoUninitialize.
classe Semaphore	Utilize a biblioteca de suporte de thread
classe SRWLock	Utilize a biblioteca de suporte de thread

APIs importantes

Introdução ao C++/WinRT
Mudar de C++/CX para C++/WinRT
WRL (Biblioteca de Modelos C++ do Windows Runtime)

Comentários

Esta página foi útil?

Last updated on 2025-06-20