Débogage des piles HTTP personnalisées

Utilisez cet article lorsque votre titre utilise directement une pile HTTP personnalisée au lieu de xCurl et que vous devez déboguer le trafic par l’intermédiaire d’un proxy tel que XBOX Multiplayer Analysis Tool (XMAT). Pour les instructions et les téléchargements en amont, consultez la documentation du projet XMAT et les versions de XMAT. Fiddler est également pris en charge.

Quand utiliser ces conseils

Ces conseils sont particulièrement utiles lorsqu’une ou plusieurs des situations suivantes s’appliquent :

Votre titre doit inspecter ou appliquer directement les paramètres de proxy.
Votre flux de travail de débogage dépend de XMAT, de Fiddler ou d’un autre proxy de développement.
Votre pile HTTP n’utilise pas Schannel comme fournisseur de sécurité et doit charger explicitement les certificats du proxy.

Pour des conseils généraux sur la sécurité, consultez Meilleures pratiques pour des requêtes web et des WebSockets sécurisés pour les titres Microsoft Game Development Kit.

Paramètres de proxy sur XBOX et PC

Lorsque vous gérez les paramètres de proxy sur XBOX, privilégiez WinHttpGetProxySettingsEx avec WinHttpProxySettingsTypeXBox lorsque ce chemin est disponible dans votre build et votre environnement cible. Sur XBOX, cette API est l’API d’avenir pour lire les paramètres de proxy à partir du Microsoft Game Development Kit (GDK) d’avril 2026. Si votre titre cible un GDK antérieur sur XBOX, le chemin des paramètres de proxy propre à XBOX n’est pas disponible. Dans ce cas, définissez manuellement l’adresse et le port du proxy dans votre pile HTTP. Le chemin de chargement des certificats décrit plus loin dans cet article s’applique toujours à ces GDK plus anciens, même si l’API d’adresse de proxy propre à XBOX n’est pas disponible. Les titres PC peuvent également interroger les paramètres de proxy par l’intermédiaire de WinHTTP, mais ne copiez pas directement le flux XBOX. Sur PC, WinHttpGetProxySettingsEx est asynchrone; attendez donc la fin de l’opération avant d’appeler WinHttpGetProxySettingsResultEx et de copier les valeurs de proxy retournées dans votre pile HTTP. Un exemple utilisant libcurl consiste à résoudre l’adresse du proxy avec l’API de paramètres de proxy XBOX, puis à la transmettre directement à la pile. L’exemple ouvre la session avec WINHTTP_FLAG_ASYNC et inscrit un rappel d’état afin que le code gère à la fois l’achèvement synchrone et un retour ERROR_IO_PENDING. L’exemple suivant montre le flux d’appels :

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

Comportement du fournisseur TLS

Piles basées sur Schannel

Si votre pile s’appuie sur un comportement TLS basé sur Schannel, la console applique automatiquement le certificat de proxy que vous configurez. Ce comportement s’applique également aux builds libcurl qui utilisent Schannel comme fournisseur TLS.

Piles non basées sur Schannel

Si votre pile s’appuie sur OpenSSL ou sur un autre fournisseur TLS non basé sur Schannel, votre titre est responsable du chargement explicite du certificat requis par l’outil de débogage actif. Conservez ce chemin de chargement des certificats dans votre code de version finale. Sur console, les titres doivent également conserver le chemin de débogage de proxy connexe disponible dans les builds RETAIL afin que vous puissiez toujours diagnostiquer le trafic passant par un proxy au besoin. Pour des conseils sur la confiance, les proxys et les valeurs par défaut sécurisées, consultez Meilleures pratiques pour des requêtes web et des WebSockets sécurisés pour les titres Microsoft Game Development Kit.

Trouver le certificat racine du proxy

Pour les piles non basées sur Schannel, chargez explicitement le certificat qui correspond à l’outil de débogage et conservez ce chemin dans votre code de version finale. L’emplacement et le sujet du certificat dépendent de l’outil. Par exemple, XBOX Multiplayer Analysis Tool (XMAT) utilise le certificat Xbox Multiplayer Analysis Tool Root Cert Authority dans CurrentUser\Root. Cet exemple recherche ce certificat et copie les octets du certificat encodé en DER dans une mémoire tampon appartenant au titre.

#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;
}

Après cette étape, transmettez encodedCertificate au chemin de chargement des certificats qu’utilise votre fournisseur TLS.

Flux de travail de débogage suggéré

Configurez la console pour le proxy de débogage :
- Pour XMAT, ajoutez une capture Web Proxy pour la console, puis sélectionnez Enable XBOX Proxy. Pour plus d’informations, consultez Utiliser XBOX Multiplayer Analysis Tool pour inspecter et modifier le trafic réseau.
- Pour Fiddler, configurez les paramètres de proxy de la console dans XBOX Device Portal comme décrit dans Fiddler sur les trousses de développement XBOX.
Si vous ciblez XBOX avec le GDK d’avril 2026 ou une version ultérieure et que votre titre doit inspecter directement les paramètres de proxy, utilisez WinHttpGetProxySettingsEx avec WinHttpProxySettingsTypeXBox.
Si votre chemin de code PC interroge les paramètres de proxy par l’intermédiaire de WinHTTP, attendez le résultat asynchrone avant d’appeler WinHttpGetProxySettingsResultEx et d’appliquer les valeurs de proxy retournées.
Si vous ciblez un GDK antérieur sur XBOX ou utilisez une pile qui n’exploite pas le chemin des paramètres de proxy propre à XBOX, définissez manuellement l’adresse et le port du proxy dans votre titre.
Si vous utilisez Schannel, fiez-vous au certificat appliqué par la console. Si vous utilisez OpenSSL ou une autre pile, récupérez le certificat de l’outil de débogage que vous utilisez dans le magasin de certificats et chargez-le explicitement.

Introduction

Onboarding & Access

Setup & Install

Build Your First Title

Débogage des piles HTTP personnalisées

Débogage des piles HTTP personnalisées

Quand utiliser ces conseils

Paramètres de proxy sur XBOX et PC

Comportement du fournisseur TLS

Piles basées sur Schannel

Piles non basées sur Schannel

Trouver le certificat racine du proxy

Flux de travail de débogage suggéré

Pages connexes

​Débogage des piles HTTP personnalisées

​Quand utiliser ces conseils

​Paramètres de proxy sur XBOX et PC

​Comportement du fournisseur TLS

​Piles basées sur Schannel

​Piles non basées sur Schannel

​Trouver le certificat racine du proxy

​Flux de travail de débogage suggéré

​Pages connexes

Débogage des piles HTTP personnalisées

Quand utiliser ces conseils

Paramètres de proxy sur XBOX et PC

Comportement du fournisseur TLS

Piles basées sur Schannel

Piles non basées sur Schannel

Trouver le certificat racine du proxy

Flux de travail de débogage suggéré

Pages connexes