Iniciar ferramenta de captura

Este artigo especifica o protocolo para integrar aplicativos de primeira e terceiros à Ferramenta de Captura do Windows usando o esquema URI (Uniform Resource Identifier) de 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á.

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}

Capturar host

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

Caminho

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âmetros de consulta (captura)

Descobrir o host

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

Parâmetros de consulta (descobrir)

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 da Ferramenta de Snipping.
• defaultVersion: versão do protocolo assumida quando uma solicitação é omitida api-version. Leia isso para entender como suas solicitações não fixadas são interpretadas.
• supportedVersions: matriz de versões de protocolo aceitas pelo build da Ferramenta de Snipping.
• 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 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."
    }
  ]
}

ModosAtivados

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

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 entre recorte de forma livre, recorte de retângulo e gravação de 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 transitar o estado específico do chamador através do retorno de chamada — o valor sessionId=abc é refletido no URI de resposta junto com code, reason, x-request-correlation-id e (para uma captura bem-sucedida) file-access-token.

Parâmetros de resposta

Códigos de status

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

Iniciando do seu aplicativo

Você deve usar Launcher.LaunchUriAsync para iniciar a Ferramenta de Snipping 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 em seu Package.appxmanifest para que seu aplicativo possa receber o 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 Snipping

// 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 Recorte ativa seu aplicativo através de seu redirect-uri com parâmetros de resultado como cadeias de consulta. A maioria das integrações já está em execução quando a resposta chega — o chamador iniciou a Ferramenta de Snipping e, em seguida, esperou pelo retorno de chamada — portanto, seu aplicativo deve lidar com a ativação de início frio (o aplicativo não estava em execução) e a reativação morna (o aplicativo já está em execução). Assine os dois 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
    }
}

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 Snipping valida todos os redirect-uri valores 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 Recorte rejeita URIs de redirecionamento que contêm caminhos UNC, espaço em branco inicial/final 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 Snipping acrescenta os parâmetros de resposta como uma cadeia de caracteres de consulta e um fragmento os engoliria.
• Proteção de auto-referência: URIs de redirecionamento que causariam a ativação recursiva da Ferramenta de Snipping são bloqueadas.

Conteúdo relacionado

• Manipular a ativação do URI
• Classe SharedStorageAccessManager
• Usar a Ferramenta de Captura para obter capturas de tela