Depuração de pilhas HTTP personalizadas

Use este artigo quando seu título usar uma pilha HTTP personalizada diretamente em vez do xCurl e você precisar depurar o tráfego por meio de um proxy, como a XBOX Multiplayer Analysis Tool (XMAT). Para obter as instruções e os downloads originais, consulte a documentação do projeto XMAT e as versões da XMAT. O Fiddler também é compatível.

Quando usar estas diretrizes

Estas diretrizes são mais úteis quando uma ou mais das seguintes condições se aplicam:

Seu título precisa inspecionar ou aplicar as configurações de proxy diretamente.
Seu fluxo de trabalho de depuração depende da XMAT, do Fiddler ou de outro proxy de desenvolvimento.
Sua pilha HTTP não usa o Schannel como provedor de segurança e precisa carregar os certificados do proxy explicitamente.

Para obter diretrizes gerais de segurança, consulte Práticas recomendadas para solicitações da Web e WebSockets seguros para títulos do Microsoft Game Development Kit.

Configurações de proxy no XBOX e no PC

Ao lidar com as configurações de proxy no XBOX, prefira WinHttpGetProxySettingsEx com WinHttpProxySettingsTypeXBox quando esse caminho estiver disponível no seu build e no ambiente de destino. No XBOX, essa API é a API voltada para o futuro para ler as configurações de proxy a partir do Microsoft Game Development Kit (GDK) de abril de 2026. Se o seu título for destinado a um GDK anterior no XBOX, o caminho de configurações de proxy específico do XBOX não estará disponível. Nesse caso, defina manualmente o endereço e a porta do proxy na sua pilha HTTP. O caminho de carregamento de certificados descrito mais adiante neste artigo ainda se aplica a esses GDKs mais antigos, mesmo que a API de endereço de proxy específica do XBOX não esteja disponível. Os títulos para PC também podem consultar as configurações de proxy por meio do WinHTTP, mas não copie o fluxo do XBOX diretamente. No PC, WinHttpGetProxySettingsEx é assíncrona, portanto, aguarde a conclusão da operação antes de chamar WinHttpGetProxySettingsResultEx e copiar os valores de proxy retornados para a sua pilha HTTP. Um exemplo usando a libcurl é resolver o endereço do proxy com a API de configurações de proxy do XBOX e, em seguida, passá-lo diretamente para a pilha. O exemplo abre a sessão com WINHTTP_FLAG_ASYNC e registra um retorno de chamada de status para que o código trate tanto a conclusão síncrona quanto um retorno ERROR_IO_PENDING. O exemplo a seguir mostra o fluxo de chamadas:

// WinHttpCreateProxyResolver is not declared in WinHttp.h when using the GDK.
WINHTTPAPI DWORD WINAPI WinHttpCreateProxyResolver(HINTERNET hSession, HINTERNET* phResolver);

std::string ResolveXboxProxy()
{
    HINTERNET session = WinHttpOpen(
        L"CustomHttp/1.0",
        WINHTTP_ACCESS_TYPE_AUTOMATIC_PROXY,
        WINHTTP_NO_PROXY_NAME,
        WINHTTP_NO_PROXY_BYPASS,
        WINHTTP_FLAG_ASYNC);
    if (!session)
        return {};

    struct ProxyContext
    {
        HANDLE event;
        DWORD  error;
    };

    ProxyContext ctx{ CreateEventW(nullptr, TRUE, FALSE, nullptr), ERROR_SUCCESS };

    WinHttpSetStatusCallback(session,
        [](HINTERNET, DWORD_PTR context, DWORD status, LPVOID info, DWORD)
        {
            auto* c = reinterpret_cast<ProxyContext*>(context);
            if (status == WINHTTP_CALLBACK_STATUS_GETPROXYFORURL_COMPLETE)
            {
                c->error = ERROR_SUCCESS;
                SetEvent(c->event);
            }
            else if (status == WINHTTP_CALLBACK_STATUS_REQUEST_ERROR)
            {
                c->error = reinterpret_cast<WINHTTP_ASYNC_RESULT*>(info)->dwError;
                SetEvent(c->event);
            }
        },
        WINHTTP_CALLBACK_FLAG_ALL_COMPLETIONS,
        0);

    HINTERNET resolver = nullptr;
    if (WinHttpCreateProxyResolver(session, &resolver) != ERROR_SUCCESS)
    {
        CloseHandle(ctx.event);
        WinHttpCloseHandle(session);
        return {};
    }

    DWORD result = WinHttpGetProxySettingsEx(
        resolver,
        WinHttpProxySettingsTypeXBox,
        nullptr,
        reinterpret_cast<DWORD_PTR>(&ctx));

    if (result == ERROR_IO_PENDING)
    {
        // Wait for the async callback to fire (5-second timeout).
        WaitForSingleObject(ctx.event, 5000);
        result = ctx.error;
    }

    std::string proxyAddress;
    if (result == ERROR_SUCCESS)
    {
        WINHTTP_PROXY_SETTINGS_EX proxySettings{};
        if (WinHttpGetProxySettingsResultEx(resolver, &proxySettings) == ERROR_SUCCESS)
        {
            PCWSTR proxy =
                proxySettings.pcwszSecureProxy != nullptr
                    ? proxySettings.pcwszSecureProxy
                    : proxySettings.pcwszProxy;

            if (proxy != nullptr)
            {
                // Example function for conversion.
                proxyAddress = Utf16ToUtf8(std::wstring(proxy));
            }

            WinHttpFreeProxySettingsEx(WinHttpProxySettingsTypeXBox, &proxySettings);
        }
    }

    CloseHandle(ctx.event);
    WinHttpCloseHandle(resolver);
    WinHttpCloseHandle(session);
    return proxyAddress;
}

std::string proxyAddress = ResolveXboxProxy();
if (!proxyAddress.empty())
{
    curl_easy_setopt(curlHandle, CURLOPT_PROXY, proxyAddress.c_str());
}

Comportamento do provedor TLS

Pilhas baseadas em Schannel

Se a sua pilha depender do comportamento de TLS baseado em Schannel, o console aplicará automaticamente o certificado de proxy que você configurar. Esse comportamento também se aplica a builds da libcurl que usam o Schannel como provedor TLS.

Pilhas que não usam Schannel

Se a sua pilha depender do OpenSSL ou de outro provedor TLS que não seja o Schannel, seu título será responsável por carregar explicitamente o certificado exigido pela ferramenta de depuração ativa. Mantenha esse caminho de carregamento de certificados no seu código de versão de lançamento. No console, os títulos também devem manter o caminho de depuração de proxy relacionado disponível em builds RETAIL para que você ainda possa diagnosticar o tráfego que passa pelo proxy quando necessário. Para obter diretrizes sobre confiança, proxy e padrões seguros, consulte Práticas recomendadas para solicitações da Web e WebSockets seguros para títulos do Microsoft Game Development Kit.

Localizar o certificado raiz do proxy

Para pilhas que não usam Schannel, carregue explicitamente o certificado que corresponde à ferramenta de depuração e mantenha esse caminho no seu código de versão de lançamento. O local e o assunto do certificado dependem da ferramenta. Por exemplo, a XBOX Multiplayer Analysis Tool (XMAT) usa o certificado Xbox Multiplayer Analysis Tool Root Cert Authority em CurrentUser\Root. Este exemplo procura esse certificado e copia os bytes do certificado codificado em DER para um buffer pertencente ao título.

#include <wincrypt.h>
#include <vector>

HRESULT ExtractXmatRootCertificateDer(_Out_ std::vector<uint8_t>& encodedCertificate)
{
    encodedCertificate.clear();

    constexpr DWORD certificateStoreLocation = CERT_SYSTEM_STORE_CURRENT_USER;
    constexpr wchar_t certificateStoreName[] = L"Root";
    constexpr wchar_t certificateSubjectName[] =
        L"Xbox Multiplayer Analysis Tool Root Cert Authority";

    HCERTSTORE certificateStore = CertOpenStore(
        CERT_STORE_PROV_SYSTEM_W,
        0,
        0,
        certificateStoreLocation |
            CERT_STORE_OPEN_EXISTING_FLAG |
            CERT_STORE_READONLY_FLAG,
        certificateStoreName);
    if (certificateStore == nullptr)
    {
        return HRESULT_FROM_WIN32(GetLastError());
    }

    PCCERT_CONTEXT certificate = CertFindCertificateInStore(
        certificateStore,
        X509_ASN_ENCODING | PKCS_7_ASN_ENCODING,
        0,
        CERT_FIND_SUBJECT_STR_W,
        certificateSubjectName,
        nullptr);
    if (certificate == nullptr)
    {
        HRESULT hr = HRESULT_FROM_WIN32(GetLastError());
        CertCloseStore(certificateStore, 0);
        return hr;
    }

    encodedCertificate.assign(
        certificate->pbCertEncoded,
        certificate->pbCertEncoded + certificate->cbCertEncoded);

    CertFreeCertificateContext(certificate);
    CertCloseStore(certificateStore, 0);
    return S_OK;
}

Após essa etapa, passe encodedCertificate para o caminho de carregamento de certificados usado pelo seu provedor TLS.

Fluxo de trabalho de depuração sugerido

Configure o console para o proxy de depuração:
- Para a XMAT, adicione uma captura de Web Proxy para o console e, em seguida, selecione Enable XBOX Proxy. Para obter mais informações, consulte Usar a XBOX Multiplayer Analysis Tool para inspecionar e modificar o tráfego de rede.
- Para o Fiddler, defina as configurações de proxy do console no XBOX Device Portal, conforme descrito em Fiddler em kits de desenvolvimento XBOX.
Se o seu destino for o XBOX com o GDK de abril de 2026 ou posterior e o seu título precisar inspecionar as configurações de proxy diretamente, use WinHttpGetProxySettingsEx com WinHttpProxySettingsTypeXBox.
Se o caminho de código do PC consultar as configurações de proxy por meio do WinHTTP, aguarde o resultado assíncrono antes de chamar WinHttpGetProxySettingsResultEx e aplicar os valores de proxy retornados.
Se o seu destino for um GDK anterior no XBOX ou se você usar uma pilha que não consome o caminho de configurações de proxy específico do XBOX, defina o endereço e a porta do proxy manualmente no seu título.
Se você usar o Schannel, conte com o certificado aplicado pelo console. Se você usar o OpenSSL ou outra pilha, recupere o certificado da ferramenta de depuração que está usando no repositório de certificados e carregue-o explicitamente.

Porting

Build Paths

Depuração de pilhas HTTP personalizadas

Depuração de pilhas HTTP personalizadas

Quando usar estas diretrizes

Configurações de proxy no XBOX e no PC

Comportamento do provedor TLS

Pilhas baseadas em Schannel

Pilhas que não usam Schannel

Localizar o certificado raiz do proxy

Fluxo de trabalho de depuração sugerido

Páginas relacionadas

​Depuração de pilhas HTTP personalizadas

​Quando usar estas diretrizes

​Configurações de proxy no XBOX e no PC

​Comportamento do provedor TLS

​Pilhas baseadas em Schannel

​Pilhas que não usam Schannel

​Localizar o certificado raiz do proxy

​Fluxo de trabalho de depuração sugerido

​Páginas relacionadas

Depuração de pilhas HTTP personalizadas

Quando usar estas diretrizes

Configurações de proxy no XBOX e no PC

Comportamento do provedor TLS

Pilhas baseadas em Schannel

Pilhas que não usam Schannel

Localizar o certificado raiz do proxy

Fluxo de trabalho de depuração sugerido

Páginas relacionadas