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

Esse protocolo requer um aplicativo Windows compactado (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. Se um aplicativo não empacotado oferecer um redirect-uri, a Ferramenta de Captura não dará a resposta e poderá sair sem mostrar a interface do usuário de captura.

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
Scheme	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`
Query	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	Yes	URI do retorno de chamada em que a Ferramenta de Captura envia a resposta da captura. Seu aplicativo deve registrar um manipulador de protocolo para esse esquema de URI. Se omitida, a Ferramenta de Recorte não exibirá a interface de captura e 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. 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 do protocolo mais recente compatível com esta criação da Ferramenta de Captura.
defaultVersion: versão do protocolo assumida quando uma solicitação é omitida api-version. Leia isso para entender como as solicitações não fixadas são interpretadas.
supportedVersions: matriz das versões de protocolo aceitas pela criação da Ferramenta de Captura.
capabilities: matriz das operações de captura compatíveis, cada uma com:
- path: o ponto de extremidade de captura (por exemplo, capture/image, capture/video).
- methods: métodos semelhantes a HTTP compatíveis.
- parameters: parâmetros disponíveis para o ponto de extremidade.
- description: descrição da funcionalidade.

{
  "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 recorte retangular:

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

Habilitar captura de retângulo e de janela:

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

Habilite todos os modos de recorte:

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 múltiplos modos de captura 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

Depois que o usuário concluir ou cancelar uma captura, o Snipping Tool enviará 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.

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 cancelado:

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

Você deve usar Launcher.LaunchUriAsync para iniciar a Ferramenta de Captura no 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}");
    }
}

Processe 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.

Recuperando mídia capturada usando o token

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

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 aplicativos empacotados: quando seu aplicativo é um aplicativo Windows empacotado, MSIX, o sistema operacional roteia a resposta de captura de volta para seu aplicativo com segurança, garantindo que apenas seu aplicativo possa recebê-la. Esse é o caminho de integração recomendado.
Validação de entrada: a Ferramenta de Captura rejeita URIs de redirecionamento que contenham 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 autorreferencial: URIs de redirecionamento que causariam a ativação recursiva da Ferramenta de Captura são bloqueadas.

Importante

Para chamar aplicativos:

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.

Comentários

Esta página foi útil?

Last updated on 2026-10-02

Iniciar ferramenta de captura

Recursos com suporte

Especificação de protocolo

Capturar host

Caminho

Parâmetros de modo (captura/imagem)

Parâmetros de consulta (captura)

Descobrir host

Parâmetros de consulta (descobrir)

Descubra o exemplo

Descobrir formato de resposta

EnabledModes

Modos suportados

Exemplos de EnabledModes

Responses

Parâmetros de resposta

Códigos de status

Respostas de exemplo

Exemplos completos de URI

Iniciando do seu aplicativo

Etapa 1: registrar um manipulador de protocolo

Etapa 2: Iniciar a Ferramenta de Captura

Etapa 3: Tratar a resposta

Recuperando mídia capturada usando o token

Considerações de segurança

Conteúdo relacionado

Comentários

Recursos adicionais