Iniciar ferramenta de captura

Este artigo especifica o protocolo para integrar aplicativos primários e de terceiros à Ferramenta de Captura do Windows usando o esquema URI (Uniform Resource Identifier) ms-screenclip:. O protocolo dá suporte à captura de imagens e vídeos (com áudio) por meio da Ferramenta de Snipping, e os chamadores de aplicativo podem escolher quais recursos da Ferramenta de Snipping seu aplicativo exibirá.

Importante

O LaunchUriAsync fluxo de retorno de chamada requer um aplicativo Windows empacotado (MSIX). Quando o aplicativo é empacotado, o sistema operacional fornece automaticamente a identidade do aplicativo para a Ferramenta de Captura, que a usa para encaminhar com segurança a resposta de captura de volta para o aplicativo. Chamadores não empacotados (Win32) não podem receber respostas por meio de redirect-uri. Para receber uma resposta de captura de imagem sem um protocolo de retorno de chamada, use LaunchUriForResultsAsync como descrito em Receber um resultado de imagem diretamente. Resgatar o token de arquivo retornado ainda requer a identidade do pacote.

Note

Esse protocolo substitui a experiência documentada em captura de tela de inicialização (obsoleto), que agora está obsoleto.

Recursos com suporte

O protocolo Snipping Tool dá suporte aos seguintes recursos:

  • Captura de retângulo
  • Captura de forma livre
  • Captura de janela
  • Gravação de Tela
  • Personalizando os modos de captura disponíveis
  • Salvamento automático (opcional)

Especificação de protocolo

Formato de URI:ms-screenclip://{host}/{path}?{query parameters}

Componente Description Valores
Esquema O esquema personalizado para a Ferramenta de Captura ms-screenclip
Host A operação da Ferramenta de Captura a ser realizada capture ou discover
Caminho O tipo de mídia a ser capturado (aplica-se somente ao capture host; o discover host não tem caminho) /image ou /video
Consulta Parâmetros para a operação Veja as tabelas abaixo

Note

Caminhos e nomes de parâmetro de consulta não diferenciam maiúsculas de minúsculas. Por exemplo, ms-screenclip://capture/Image?Redirect-Uri=my-app://response comporta-se da mesma forma que ms-screenclip://capture/image?redirect-uri=my-app://response.

Capturar host

Use o host capture para iniciar a sobreposição de captura da Ferramenta de Captura.

Caminho

Caminho Description
/image Inicia a captura de imagem (captura de tela). Requer um parâmetro de modo.
/video Inicia a captura de vídeo (gravação de tela). Sempre usa o modo retangular.

Parâmetros de modo (captura/imagem)

Para o /image caminho, você deve especificar exatamente um parâmetro de modo. Parâmetros de modo são parâmetros de consulta sem valor.

Parâmetro Description
rectangle Modo de captura de retângulo interativo.
freeform Modo de captura interativa em forma livre.
window Modo interativo de captura de janela.

Importante

Parâmetros de modo devem ser especificados sem um valor. Por exemplo, use &rectangle, não&rectangle=value. Fornecer um valor resultará em uma resposta de erro.

Para /image, você deve especificar exatamente um parâmetro de modo. Especificar zero ou mais de um modo resultará em uma 400 Bad Request resposta de erro. Para /video, qualquer parâmetro de modo é ignorado.

Parâmetros de consulta (captura)

Note

Os parâmetros de consulta podem ser fornecidos em qualquer ordem.

Parâmetro Tipo Obrigatório Description Default
redirect-uri URI Apenas retorno de chamada URI do retorno de chamada em que a Ferramenta de Captura envia a resposta da captura. Inclua esse parâmetro quando você usar LaunchUriAsynce registre um manipulador de protocolo para seu esquema. Omita esse parâmetro quando você usa LaunchUriForResultsAsync. n/a
user-agent cadeia Não (altamente recomendado) Identificador do aplicativo de chamada, usado para log e análise. Necessário para diagnosticar problemas por meio de canais de suporte; omita por sua conta e risco. n/a
api-version cadeia No Versão do protocolo a ser usada, por exemplo "1.2". Se omitida, a solicitação será processada como versão 1.2. 1.2
x-request-correlation-id cadeia No Identificador exclusivo para a solicitação, permitindo referência a uma determinada transação ou cadeia de eventos. GUID gerado automaticamente
enabledModes cadeia de caracteres (lista) No Controles que capturam modos estão disponíveis na interface do usuário. Veja EnabledModes abaixo. Somente o modo especificado na URI
auto-save sinalizador No Quando presente, a captura de tela ou gravação capturada é salva automaticamente no dispositivo do usuário. Não está presente (sem salvamento automático)

Note

O padrão api-version do 1.2 não é alterado quando versões de protocolo mais recentes são lançadas. As solicitações que omitem api-version são sempre processadas como 1.2. Para usar recursos adicionados em uma versão posterior, defina api-version para essa versão. É recomendável especificar api-version explicitamente em cada solicitação para que seu aplicativo permaneça vinculado a uma versão de protocolo conhecida em vez do padrão implícito.

Note

Quando você fornece api-version, ele deve corresponder exatamente a um dos valores na /discover matriz da supportedVersions resposta (atualmente 1.0, 1.1e 1.2). Qualquer outro valor , incluindo valores intermediários como 1.15 ou valores malformados, como 1.0abc – retorna uma 400 Bad Request resposta. Para descobrir o conjunto de versões aceito por uma criação da Ferramenta de Captura, chame o descobrir host.

Note

O auto-save flag respeita as configurações da Ferramenta de Recorte do usuário. Se o usuário tiver desabilitado o salvamento automático na Ferramenta de Snipping, a captura não será salva no dispositivo mesmo quando sua solicitação incluir auto-save.

Descobrir host

Use o host discover para consultar os recursos, os modos, a versão do protocolo compatíveis com a Ferramenta de Captura em runtime. Isso é útil para verificar a compatibilidade antes de fazer uma solicitação de captura.

Parâmetros de consulta (descobrir)

Parâmetro Tipo Obrigatório Description Default
redirect-uri URI Yes URI do retorno de chamada em que a Ferramenta de Captura envia a resposta de recursos. Seu aplicativo deve registrar um manipulador de protocolo para esse esquema de URI. Se omitida, a Ferramenta de Captura não retornará uma resposta. n/a
user-agent cadeia Não (altamente recomendado) Identificador do aplicativo de chamada, usado para log e análise. n/a
x-request-correlation-id cadeia No Identificador exclusivo para a solicitação. GUID gerado automaticamente

Descubra o exemplo

ms-screenclip://discover?user-agent=MyApp&redirect-uri=my-app://response

Descobrir formato de resposta

A resposta é um objeto JSON acrescentado ao URI de redirecionamento como o parâmetro de discover consulta. Ele contém:

  • version: versão de protocolo mais recente compatível com esta compilação do Snipping Tool.
  • defaultVersion: versão do protocolo assumida quando uma solicitação omite api-version. Leia isso para entender como as solicitações não fixadas são interpretadas.
  • supportedVersions: matriz de versões de protocolo aceitas pelo build do Snipping Tool.
  • capabilities: matriz de operações de captura com suporte, cada uma com:
    • path: o ponto de extremidade de captura (por exemplo, capture/image, capture/video).
    • methods: métodos semelhantes a HTTP com suporte.
    • parameters: parâmetros disponíveis para o endpoint.
    • description: Descrição da capacidade.
{
  "version": 1.2,
  "defaultVersion": 1.2,
  "supportedVersions": [1.0, 1.1, 1.2],
  "capabilities": [
    {
      "path": "capture/image",
      "methods": ["GET"],
      "parameters": ["rectangle", "freeform", "window"],
      "description": "Captures an image with options for shape."
    },
    {
      "path": "capture/video",
      "methods": ["GET"],
      "parameters": [],
      "description": "Captures a video in a defined area."
    }
  ]
}

EnabledModes

O enabledModes parâmetro permite controlar quais modos de captura estão disponíveis na interface do usuário da Ferramenta de Recorte. Use-o para restringir ou expandir as opções do usuário para corresponder aos requisitos do aplicativo.

Modos suportados

Modo Description
RectangleSnip Modo de captura retangular.
WindowSnip Modo de captura de janela.
FreeformSnip Modo de captura de forma livre.
FullscreenSnip Modo de captura de tela inteira.
SnippingAllModes Todos os modos de captura de imagem: RectangleSnip, , WindowSnip, FreeformSnip. FullscreenSnip
RectangleRecord Modo de gravação em retângulo.
RecordAllModes Todos os modos de gravação: atualmente somente RectangleRecord.
All Todos os modos suportados: a união de SnippingAllModes e RecordAllModes.

Dica

All, SnippingAllModese RecordAllModes são valores agregados. Os modos que eles incluem podem ser alterados nas versões da Ferramenta de Captura. Um aplicativo que usa um desses valores automaticamente seleciona os modos adicionados em versões futuras. Para manter o conjunto de modos disponíveis corrigido entre atualizações, liste os modos específicos explicitamente (por exemplo, RectangleSnip,FreeformSnip).

Importante

  • Para /image, um parâmetro de modo (por exemplo, rectangle, freeform, window) é necessário na URI, mesmo quando enabledModes é especificado. O parâmetro de modo determina o modo inicialmente selecionado.
  • O modo especificado no URI está sempre disponível na interface do usuário, mesmo que não esteja listado em enabledModes. Por exemplo, ?freeform&enabledModes=RectangleSnip disponibiliza as opções de captura de forma livre (do URI) e de retângulo, com a forma livre pré-selecionada.
  • Se enabledModes for omitido, somente o modo especificado no URI estará disponível na interface do usuário.
  • Se nenhum parâmetro de modo for especificado para /image, a requisição será inválida e resultará em um erro, independentemente de enabledModes.

Exemplos de EnabledModes

Habilitar somente o snip de retângulo:

ms-screenclip://capture/image?rectangle&enabledModes=RectangleSnip&user-agent=MyApp&redirect-uri=my-app://response

Habilitar retângulo e snip de janela:

ms-screenclip://capture/image?rectangle&enabledModes=RectangleSnip,WindowSnip&user-agent=MyApp&redirect-uri=my-app://response

Habilite todos os modos de snipping:

ms-screenclip://capture/image?rectangle&enabledModes=SnippingAllModes&user-agent=MyApp&redirect-uri=my-app://response

Habilitar somente o modo de gravação:

ms-screenclip://capture/video?enabledModes=RecordAllModes&user-agent=MyApp&redirect-uri=my-app://response

Habilite vários modos de recorte e gravação:

ms-screenclip://capture/image?freeform&enabledModes=RectangleSnip,RectangleRecord&user-agent=MyApp&redirect-uri=my-app://response

Como a forma livre é especificada no URI, ela será pré-selecionada. Os usuários podem alternar a captura de forma livre, de retângulo e gravação em retângulo.

Responses

Para o fluxo de retorno de chamada, depois que o usuário conclui ou cancela uma captura, a Ferramenta de Snipping envia uma resposta de volta ao seu aplicativo por meio do redirect-uri. A resposta é estruturada como parâmetros de consulta URI acrescentados ao URI de redirecionamento. Para receber resultados de captura de imagem em ValueSet em vez disso, consulte Receber um resultado de imagem diretamente.

Se seu redirect-uri já incluir parâmetros de consulta (por exemplo, my-app://response?sessionId=abc), esses parâmetros serão preservados e os parâmetros de resposta serão acrescentados ao &. Você pode usá-lo para fazer a viagem de ida e volta do estado específico do chamador por meio do retorno de chamada – o valor sessionId=abc é repetido no URI de resposta com code, reason, x-request-correlation-id e (para uma captura bem-sucedida) file-access-token.

Parâmetros de resposta

Parâmetro Tipo Presente Description
code int Sempre Código de status de estilo HTTP que indica o resultado.
reason cadeia Sempre Descrição legível pelo ser humano do resultado.
x-request-correlation-id cadeia Sempre A ID de correlação da solicitação original (ou uma gerada automaticamente).
file-access-token cadeia Apenas sucesso Um SharedStorageAccessManager token que representa a mídia capturada. Use isso para recuperar o arquivo.
discover cadeia Somente descoberta JSON codificado em URL contendo a resposta de recursos.

Códigos de status

Code Reason Description
200 Êxito A captura foi concluída com êxito. Um file-access-token é incluído na resposta.
400 Solicitação inválida - Parâmetros inválidos ou ausentes Não foi possível processar a solicitação. Verifique se todos os parâmetros necessários estão presentes e válidos.
408 Tempo limite da solicitação – operação demorou muito A operação atingiu o tempo limite antes da conclusão.
499 Solicitação fechada do cliente – o usuário cancelou a captura O usuário cancelou a captura pressionando Escape ou clicando fora. Aplica-se a /image e /video somente.
500 Erro interno do servidor – Falha no processamento Ocorreu um erro inesperado durante a captura.

Respostas de exemplo

Captura bem-sucedida:

my-app://response?code=200&reason=Success&x-request-correlation-id=aaaa0000-bb11-2222-33cc-444444dddddd&file-access-token=cccc2222-dd33-4444-55ee-666666ffffff

Usuário cancelou:

my-app://response?code=499&reason=Client%20Closed%20Request%20-%20User%20Cancelled%20the%20Snip&x-request-correlation-id=bbbb1111-cc22-3333-44dd-555555eeeeee

Solicitação inválida (parâmetro de modo ausente):

my-app://response?code=400&reason=Bad%20Request%20-%20Invalid%20or%20Missing%20Parameters&x-request-correlation-id=bbbb1111-cc22-3333-44dd-555555eeeeee

Exemplos completos de URI

Caso de uso URI Description
Captura de tela em retângulo ms-screenclip://capture/image?rectangle&user-agent=MyApp&redirect-uri=my-app://response Captura de retângulo interativo. Resultado retornado ao solicitante.
Captura de tela em forma livre ms-screenclip://capture/image?freeform&user-agent=MyApp&redirect-uri=my-app://response Captura de forma livre interativa. Resultado retornado ao solicitante.
Captura de tela da janela ms-screenclip://capture/image?window&user-agent=MyApp&redirect-uri=my-app://response Captura de janela interativa. Resultado retornado ao solicitante.
Gravação de tela ms-screenclip://capture/video?user-agent=MyApp&redirect-uri=my-app://response Gravação de tela interativa. Resultado retornado ao solicitante.
Descobrir funcionalidades ms-screenclip://discover?user-agent=MyApp&redirect-uri=my-app://response Consultar recursos com suporte. Recursos retornados por JSON ao chamador.
Retângulo com gravação automática ms-screenclip://capture/image?rectangle&auto-save&user-agent=MyApp&redirect-uri=my-app://response Captura de retângulo habilitada com salvamento automático.
Retângulo com todos os modos ms-screenclip://capture/image?rectangle&enabledModes=All&user-agent=MyApp&redirect-uri=my-app://response Captura de retângulo pré-selecionada, todos os modos disponíveis na interface do usuário.

Iniciando do seu aplicativo

Para o fluxo de retorno de chamada, você deve usar Launcher.LaunchUriAsync para iniciar o Snipping Tool a partir do seu aplicativo empacotado. Outros métodos de inicialização (como Process.Start ou execução de shell) não fornecerão a identidade do aplicativo e a Ferramenta de Snipping não fornecerá a resposta.

Etapa 1: registrar um manipulador de protocolo

Registre um protocolo personalizado no Package.appxmanifest para que o aplicativo possa receber a resposta do retorno de chamada. O nome do protocolo deve corresponder ao esquema usado em sua redirect-uri.

<Extensions>
  <uap:Extension Category="windows.protocol">
    <uap:Protocol Name="my-app" DesiredView="default">
      <uap:DisplayName>My App Protocol</uap:DisplayName>
    </uap:Protocol>
  </uap:Extension>
</Extensions>

Consulte Manipular a ativação do URI para obter mais detalhes sobre como registrar e manipular ativações de protocolo.

Etapa 2: Iniciar a Ferramenta de Captura

// Capture a screenshot in rectangle mode
var uri = new Uri(
    "ms-screenclip://capture/image"
    + "?rectangle"
    + "&user-agent=MyApp"
    + "&redirect-uri=my-app://capture-response"
    + "&x-request-correlation-id=" + Guid.NewGuid().ToString()
);
await Launcher.LaunchUriAsync(uri);
// Record a video
var uri = new Uri(
    "ms-screenclip://capture/video"
    + "?user-agent=MyApp"
    + "&redirect-uri=my-app://capture-response"
);
await Launcher.LaunchUriAsync(uri);
// Discover capabilities (returns immediately, no capture UI)
var uri = new Uri(
    "ms-screenclip://discover"
    + "?user-agent=MyApp"
    + "&redirect-uri=my-app://discover-response"
);
await Launcher.LaunchUriAsync(uri);

Etapa 3: Tratar a resposta

Quando a captura é concluída (ou o usuário cancela), a Ferramenta de Captura ativa o aplicativo por meio do redirect-uri com parâmetros de resultado acrescentados como cadeias de consulta. A maioria das integrações já está em execução quando a resposta chega – o chamador iniciou a Ferramenta de Captura e, em seguida, aguardou o retorno de chamada – logo, o aplicativo deve lidar com a ativação de inicialização a frio (o aplicativo não estava em execução) e a reativação a quente (o aplicativo já está em execução). Inscreva-se em ambos os caminhos em App.xaml.cs.

Manipular uma resposta de captura (imagem ou vídeo):

// In App.xaml.cs: handle protocol activation for both cold-start and warm re-activation
protected override void OnLaunched(Microsoft.UI.Xaml.LaunchActivatedEventArgs args)
{
    // Cold-start path: the app was launched by Snipping Tool's callback.
    var activatedArgs = Microsoft.Windows.AppLifecycle.AppInstance.GetCurrent().GetActivatedEventArgs();
    if (activatedArgs.Kind == Microsoft.Windows.AppLifecycle.ExtendedActivationKind.Protocol)
    {
        if (activatedArgs.Data is Windows.ApplicationModel.Activation.IProtocolActivatedEventArgs protocolArgs)
        {
            _ = HandleProtocolActivationAsync(protocolArgs.Uri);
        }
    }

    // Warm re-activation path: the app is already running when the callback arrives.
    Microsoft.Windows.AppLifecycle.AppInstance.GetCurrent().Activated += (sender, e) =>
    {
        if (e.Kind == Microsoft.Windows.AppLifecycle.ExtendedActivationKind.Protocol &&
            e.Data is Windows.ApplicationModel.Activation.IProtocolActivatedEventArgs protocolArgs)
        {
            _ = HandleProtocolActivationAsync(protocolArgs.Uri);
        }
    };
}

private async Task HandleProtocolActivationAsync(Uri uri)
{
    var query = new WwwFormUrlDecoder(uri.Query);

    var code = query.GetFirstValueByName("code");
    var reason = query.GetFirstValueByName("reason");

    if (code == "200")
    {
        var token = query.GetFirstValueByName("file-access-token");
        var file = await SharedStorageAccessManager.RedeemTokenForFileAsync(token);

        // Use the captured file (see "Retrieving captured media" below)
    }
    else
    {
        // Handle error (400, 408, 499, 500)
        Debug.WriteLine($"Snipping Tool returned {code}: {reason}");
    }
}

Manipular uma resposta de descoberta:

private void HandleDiscoverResponse(Uri uri)
{
    var query = new WwwFormUrlDecoder(uri.Query);

    var code = query.GetFirstValueByName("code");

    if (code == "200")
    {
        var discover = query.GetFirstValueByName("discover");
        // discover contains a URL-encoded JSON capabilities payload
        var capabilities = Uri.UnescapeDataString(discover);
        // Parse the JSON to inspect supported capture modes
    }
}

Dica

Se você enviou um x-request-correlation-id com a solicitação, verifique se a resposta ecoa o mesmo valor, de maneira que possa combinar a resposta à solicitação de pré-lançamento correta. Se você permitir que a Ferramenta de Captura gere automaticamente uma, a resposta carregará o valor gerado – trate-a como correspondente à solicitação de pré-lançamento mais recente.

Receber um resultado de imagem diretamente

Launcher.LaunchUriForResultsAsync retorna a resposta em um ValueSet, portanto, seu aplicativo não precisa de um protocolo de retorno de chamada ou um redirect-uri. Você pode iniciar para obter resultados de aplicativos empacotados, aplicativos empacotados com localização externa e aplicativos não empacotados. Recuperar o arquivo capturado é uma etapa separada: SharedStorageAccessManager requer a identidade do pacote, portanto, aplicativos não empacotados sem identidade não podem resgatar o token de arquivo retornado.

Os resultados diretos oferecem suporte apenas a solicitações ms-screenclip://capture/image. A captura de vídeo, o host discover e as solicitações de gravação herdadas não têm suporte e retornam o código 501.

LaunchUriResult.Status indica se Windows iniciou com êxito o aplicativo de destino e recebeu um resultado. Quando esse status for Success, inspecione o valor inteiro code em LaunchUriResult.Result para obter o resultado da operação de captura. O resultado também contém reason, x-request-correlation-ide, para uma captura bem-sucedida, file-access-token.

O exemplo de C# a seguir é para uma janela WinUI 3 em um aplicativo com a identidade do pacote (empacotado ou empacotado com local externo). Ele associa LauncherOptions ao HWND da janela, direciona o Snipping Tool, solicita uma captura de retângulo, valida a resposta do protocolo e resgata o token de arquivo retornado.

using System;
using System.Diagnostics;
using System.Threading.Tasks;
using Windows.ApplicationModel.DataTransfer;
using Windows.Foundation.Collections;
using Windows.Storage;
using Windows.System;

private async Task<StorageFile?> CaptureImageAsync()
{
    string correlationId = Guid.NewGuid().ToString();
    var uri = new Uri(
        "ms-screenclip://capture/image"
        + "?rectangle"
        + "&api-version=1.2"
        + "&enabledModes=SnippingAllModes"
        + "&user-agent=MyApp"
        + $"&x-request-correlation-id={correlationId}");

    var options = new LauncherOptions
    {
        TargetApplicationPackageFamilyName = "Microsoft.ScreenSketch_8wekyb3d8bbwe"
    };

    nint hwnd = WinRT.Interop.WindowNative.GetWindowHandle(this);
    WinRT.Interop.InitializeWithWindow.Initialize(options, hwnd);

    LaunchUriResult launchResult =
        await Launcher.LaunchUriForResultsAsync(uri, options);

    if (launchResult.Status != LaunchUriStatus.Success)
    {
        Debug.WriteLine($"Snipping Tool couldn't be launched: {launchResult.Status}");
        return null;
    }

    ValueSet values = launchResult.Result;
    if (values is null ||
        !values.TryGetValue("code", out object? codeValue) ||
        codeValue is not int code)
    {
        Debug.WriteLine("Snipping Tool didn't return a valid integer status code.");
        return null;
    }

    string? reason = GetString(values, "reason");
    string? responseCorrelationId =
        GetString(values, "x-request-correlation-id");

    if (responseCorrelationId != correlationId)
    {
        Debug.WriteLine("The response correlation ID doesn't match the request.");
        return null;
    }

    if (code != 200)
    {
        Debug.WriteLine($"Snipping Tool returned {code}: {reason}");
        return null;
    }

    string? token = GetString(values, "file-access-token");
    if (string.IsNullOrEmpty(token))
    {
        Debug.WriteLine("Snipping Tool didn't return a file access token.");
        return null;
    }

    return await SharedStorageAccessManager.RedeemTokenForFileAsync(token);
}

private static string? GetString(ValueSet values, string key) =>
    values.TryGetValue(key, out object? value) ? value as string : null;

Note

Um aplicativo UWP tem uma associação de janela implícita e não precisa das duas linhas de inicialização HWND. Os aplicativos da área de trabalho, incluindo aplicativos WinUI 3, WPF e WinForms, devem associar LauncherOptions a uma janela proprietária antes de iniciar a interface do usuário.

Recuperando mídia capturada usando o token

Use a classe SharedStorageAccessManager para resgatar o file-access-token e acessar o arquivo capturado.

Importante

SharedStorageAccessManager requer identidade de pacote. O exemplo a seguir se aplica a aplicativos empacotados e aplicativos empacotados com localização externa, não a aplicativos não empacotados sem identidade.

Restrições de token:

  • Um token só pode ser resgatado uma vez. Após o resgate, ele não é mais válido.
  • Um token expira após 14 dias.
  • Um aplicativo não pode ter mais de 1000 tokens ativos. Depois que um token é resgatado, removido ou expira, ele não conta mais com a cota.
// Redeem the token and display the captured image
var file = await SharedStorageAccessManager.RedeemTokenForFileAsync(token);

using (var stream = await file.OpenReadAsync())
{
    var bitmap = new BitmapImage();
    await bitmap.SetSourceAsync(stream);
    MyImage.Source = bitmap;
}

// Or copy to your app's local storage
var localFolder = ApplicationData.Current.LocalFolder;
await file.CopyAsync(localFolder, file.Name, NameCollisionOption.GenerateUniqueName);

Considerações de segurança

A Ferramenta de Captura valida todos os valores redirect-uri antes de iniciá-los. As seguintes proteções são impostas:

  • Chamadores de aplicativo empacotados: quando seu aplicativo é empacotado Windows aplicativo (MSIX), o sistema operacional roteia com segurança a resposta de captura de volta para seu aplicativo, garantindo que apenas seu aplicativo possa recebê-lo. Esse é o caminho de integração recomendado.
  • Validação de entrada: o Snipping Tool rejeita URIs de redirecionamento que contêm caminhos UNC, espaço em branco à esquerda/à direita ou caracteres de controle.
  • Nenhum fragmento: as URIs de redirecionamento que contêm um fragmento de URL (por exemplo, my-app://response#section) são rejeitadas. A Ferramenta de Captura acrescenta os parâmetros de resposta como uma cadeia de consulta, e um fragmento os engoliria.
  • Proteção de auto-referência: URIs de redirecionamento que causariam a ativação recursiva do Snipping Tool são bloqueadas.

Importante

Para aplicativos chamadores:

  • Registre um manipulador de protocolo para o esquema de URI de redirecionamento para que seu aplicativo possa receber a resposta.
  • Valide e sanifique todos os parâmetros recebidos na resposta antes de processá-los.
  • Verifique se a resposta corresponde x-request-correlation-id à sua solicitação em voo para evitar lidar com uma resposta obsoleta ou misturar solicitações simultâneas. O ID de correlação evita confusões; ele não estabelece a procedência do token — o roteamento seguro de tokens vem do canal de callback do aplicativo empacotado.