Depuración de pilas HTTP personalizadas

Use este artículo cuando su título use directamente una pila HTTP personalizada en lugar de xCurl y necesite depurar el tráfico a través de un proxy como Fiddler.

Cuándo usar esta guía

Esta guía resulta más útil cuando se aplican una o varias de las condiciones siguientes:

Su título necesita inspeccionar o aplicar la configuración de proxy directamente.
Su flujo de trabajo de depuración depende de Fiddler u otro proxy de desarrollo.
Su pila HTTP no usa Schannel como proveedor de seguridad y debe cargar los certificados del proxy explícitamente.

Para obtener instrucciones generales de seguridad, consulte Procedimientos recomendados para solicitudes web y WebSockets seguros para títulos del Microsoft Game Development Kit.

Configuración de proxy en XBOX y PC

Al gestionar la configuración de proxy en XBOX, es preferible usar WinHttpGetProxySettingsEx con WinHttpProxySettingsTypeXBox cuando esa ruta esté disponible en su compilación y entorno de destino. En XBOX, esta API es la API orientada al futuro para leer la configuración de proxy a partir del Microsoft Game Development Kit (GDK) de abril de 2026. Si su título tiene como destino un GDK anterior en XBOX, la ruta de configuración de proxy específica de XBOX no está disponible. En ese caso, establezca manualmente la dirección y el puerto del proxy en su pila HTTP. La ruta de carga de certificados que se describe más adelante en este artículo sigue aplicándose en esos GDK más antiguos aunque la API de dirección de proxy específica de XBOX no esté disponible. Los títulos de PC también pueden consultar la configuración de proxy a través de WinHTTP, pero no copie directamente el flujo de XBOX. En PC, WinHttpGetProxySettingsEx es asincrónica, así que espere a que la operación se complete antes de llamar a WinHttpGetProxySettingsResultEx y copiar los valores de proxy devueltos en su pila HTTP. Un ejemplo con libcurl consiste en resolver la dirección del proxy con la API de configuración de proxy de XBOX y, a continuación, pasarla directamente a la pila. La sesión se abre con WINHTTP_FLAG_ASYNC y se registra una devolución de llamada de estado para que el código gestione tanto la finalización sincrónica como una devolución de ERROR_IO_PENDING. El ejemplo siguiente muestra el flujo de llamadas:

// 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());
}

Comportamiento del proveedor de TLS

Pilas basadas en Schannel

Si su pila depende del comportamiento de TLS respaldado por Schannel, la consola aplica automáticamente el certificado de proxy que usted configure. Este comportamiento también se aplica a las compilaciones de libcurl que usan Schannel como proveedor de TLS.

Pilas que no usan Schannel

Si su pila depende de OpenSSL u otro proveedor de TLS distinto de Schannel, su título es responsable de cargar explícitamente el certificado requerido por la herramienta de depuración activa. Mantenga esta ruta de carga de certificados en su código de versión. En consola, los títulos también deben mantener disponible la ruta de depuración de proxy relacionada en las compilaciones RETAIL para poder seguir diagnosticando el tráfico a través de proxy cuando sea necesario. Para obtener instrucciones sobre confianza, proxy y valores predeterminados seguros, consulte Procedimientos recomendados para solicitudes web y WebSockets seguros para títulos del Microsoft Game Development Kit.

Búsqueda del certificado raíz del proxy

Para las pilas que no usan Schannel, cargue explícitamente el certificado que corresponde a la herramienta de depuración y mantenga esta ruta en su código de versión. La ubicación y el firmante del certificado dependen de la herramienta. Por ejemplo, XBOX Multiplayer Analysis Tool (XMAT) usa el certificado Xbox Multiplayer Analysis Tool Root Cert Authority en CurrentUser\Root. Este ejemplo busca ese certificado y copia los bytes del certificado codificado en DER en un búfer propiedad del 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;
}

Después de este paso, pase encodedCertificate a la ruta de carga de certificados que use su proveedor de TLS.

Flujo de trabajo de depuración sugerido

Configure los ajustes de proxy de la consola en XBOX Device Portal como se describe en Fiddler en kits de desarrollo de XBOX.
Si su destino es XBOX con el GDK de abril de 2026 o posterior y su título necesita inspeccionar la configuración de proxy directamente, use WinHttpGetProxySettingsEx con WinHttpProxySettingsTypeXBox.
Si su ruta de código de PC consulta la configuración de proxy a través de WinHTTP, espere el resultado asincrónico antes de llamar a WinHttpGetProxySettingsResultEx y aplicar los valores de proxy devueltos.
Si su destino es un GDK anterior en XBOX o usa una pila que no consume la ruta de configuración de proxy específica de XBOX, establezca la dirección y el puerto del proxy manualmente dentro de su título.
Si usa Schannel, confíe en el certificado aplicado por la consola. Si usa OpenSSL u otra pila, recupere del almacén de certificados el certificado de la herramienta de depuración que esté usando y cárguelo explícitamente.

GDK and Game Engines Integration

Steam porting guide

Game Principles

Core Features

Console Features

Cuándo usar esta guía

Configuración de proxy en XBOX y PC

Comportamiento del proveedor de TLS

Pilas basadas en Schannel

Pilas que no usan Schannel

Búsqueda del certificado raíz del proxy

Flujo de trabajo de depuración sugerido

Páginas relacionadas

​Cuándo usar esta guía

​Configuración de proxy en XBOX y PC

​Comportamiento del proveedor de TLS

​Pilas basadas en Schannel

​Pilas que no usan Schannel

​Búsqueda del certificado raíz del proxy

​Flujo de trabajo de depuración sugerido

​Páginas relacionadas

Cuándo usar esta guía

Configuración de proxy en XBOX y PC

Comportamiento del proveedor de TLS

Pilas basadas en Schannel

Pilas que no usan Schannel

Búsqueda del certificado raíz del proxy

Flujo de trabajo de depuración sugerido

Páginas relacionadas