Iniciar a ferramenta de recorte

Este artigo especifica o protocolo para integrar aplicações de primeira e terceira parte com a Windows Snipping Tool utilizando o esquema URI (Uniform Resource Identifier) ms-screenclip:. O protocolo suporta a captura de imagens e vídeo (com áudio) através da Ferramenta de Recorte, e os utilizadores da aplicação podem escolher quais as funcionalidades da Ferramenta de Corte que a sua aplicação irá mostrar.

Funcionalidades suportadas

O protocolo Snipping Tool suporta as seguintes funcionalidades:

• Captura de Retângulo
• Captura Livre
• Captura de Janela
• Gravação de tela
• Personalização dos modos de captura disponíveis
• Gravação automática (opcional)

Especificação do protocolo

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

Captura de hospedeiro

Usa o capture host para iniciar a sobreposição de captura do Snipping Tool.

Caminho

Parâmetros de modo (captura/imagem)

Para o /image trajeto, deve especificar exatamente um parâmetro de modo. Os parâmetros de modo são parâmetros de consulta simples sem valor.

Parâmetros de consulta (captura)

Descobrir anfitrião

Use o discover host para consultar as capacidades, modos e versão do protocolo suportados pela Ferramenta de Recorte em tempo de execução. Isto é útil para verificar a compatibilidade antes de fazer um pedido de captura.

Parâmetros de consulta (descobrir)

Descubra exemplo

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

Descobrir o formato de resposta

A resposta é um objeto JSON anexado ao URI de redirecionamento como parâmetro de discover consulta. Contém:

• version: Versão de protocolo mais recente que esta versão da Ferramenta de Recorte suporta.
• defaultVersion: Versão do protocolo assumida quando um pedido omite api-version. Lê isto para perceberes como os teus pedidos não fixados são interpretados.
• supportedVersions: Conjunto de versões de protocolo aceitas por esta versão da Ferramenta de Recorte.
• capabilities: Array de operações de captura suportadas, cada uma com:
  • path: O ponto final de captura (por exemplo, capture/image, capture/video).
  • methods: Suportava métodos semelhantes a HTTP.
  • 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."
    }
  ]
}

Modos Ativados

O enabledModes parâmetro permite-lhe controlar quais os modos de captura disponíveis na interface da Ferramenta de Corte. Use-o para restringir ou expandir as escolhas do utilizador para corresponder aos requisitos da sua aplicação.

Modos suportados

Exemplos de EnabledModes

Ativar apenas o modo de recorte retangular:

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

Ativar o corte de rectângulos e janelas:

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

Ativar todos os modos de corte:

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

Ativar apenas o modo de gravação:

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

Ative múltiplos modos de corte e gravação:

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

Como o formato livre está especificado no URI, será pré-selecionado. Os utilizadores podem alternar entre recorte livre, corte retangular e gravação retangular.

Responses

Depois de o utilizador concluir ou cancelar uma captura, a Ferramenta de Corte envia uma resposta de volta à sua aplicação através do redirect-uri. A resposta está estruturada como parâmetros de consulta URI adicionados ao seu URI de redirecionamento.

Se your redirect-uri já inclui parâmetros de consulta (por exemplo, my-app://response?sessionId=abc), esses parâmetros são preservados e os parâmetros de resposta são acrescentados a &. Pode usar isto para fazer uma ida e volta ao estado específico do chamador através do callback — o valor sessionId=abc é ecoado de volta no URI da resposta juntamente com code, reason, x-request-correlation-id, e (para uma captura bem-sucedida) file-access-token.

Parâmetros de resposta

Códigos de status

Exemplos de respostas

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

Utilizador cancelado:

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

Pedido inválido (parâmetro de modo em falta):

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

Lançar a partir da sua aplicação

Deve usar o Launcher.LaunchUriAsync para iniciar a Ferramenta de Corte a partir da sua aplicação incluída. Outros métodos de lançamento (como shell ou execução Process.Start) não fornecerão a identidade do seu app, e o Snipping Tool não fornecerá a resposta.

Passo 1: Registar um manipulador de protocolo

Regista um protocolo personalizado no Package.appxmanifest para que a tua aplicação possa receber a resposta de callback. O nome do protocolo deve corresponder ao esquema usado no seu 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 Ativação de URI para mais detalhes sobre registo e gestão de ativações de protocolos.

Passo 2: Iniciar a Ferramenta de Corte

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

Passo 3: Lidar com a resposta

Quando a captura termina (ou o utilizador cancela), o Snipping Tool ativa a sua aplicação através de redirect-uri, com parâmetros de resultado adicionados como strings de consulta. A maioria das integrações já está em execução quando a resposta chega — o interlocutor lançou a Ferramenta de Recorte e depois aguardou pela chamada de retorno — por isso a sua aplicação tem de gerir tanto a ativação a frio (a aplicação não estava a funcionar) como a reativação a quente (a aplicação já está em funcionamento). Registe-se em ambos os percursos em App.xaml.cs.

Lidar com 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}");
    }
}

Processar 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
    }
}

Recuperação de media capturada usando o token

Use a classe SharedStorageAccessManager para resgatar file-access-token e aceder ao ficheiro capturado.

Restrições de tokens:

• Um token só pode ser resgatado uma vez. Depois da redenção, deixa de ser válida.
• Um token expira após 14 dias.
• Uma aplicação não pode ter mais de 1000 tokens ativos. Depois de um token ser resgatado, removido ou expirar, deixa de contar para a quota.

// 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

O Snipping Tool valida todos os redirect-uri valores antes de os lançar. São aplicadas as seguintes proteções:

• Chamadores de aplicações empacotadas: Quando a sua aplicação é uma aplicação de Windows empacotada (MSIX), o sistema operativo encaminha de forma segura a resposta de captura de volta para a sua aplicação, garantindo que apenas a sua aplicação pode recebê-la. Este é o caminho de integração recomendado.
• Validação de entrada: A Ferramenta de Corte rejeita URIs de redirecionamento que contenham caminhos UNC, espaços em branco iniciais/finais ou caracteres de controlo.
• Sem fragmentos: URIs de redirecionamento que contenham um fragmento de URL (por exemplo, my-app://response#section) são rejeitados. O Snipping Tool adiciona os parâmetros de resposta como uma string de consulta, e um fragmento engoliria-os.
• Proteção auto-referencial: URIs de redirecionamento que causariam ativação recursiva da Ferramenta de Corte são bloqueados.

Conteúdo relacionado

• Manipular a ativação de URI
• Classe SharedStorageAccessManager
• Utilizar a Ferramenta de Recorte para efetuar capturas de ecrã