Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
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 omiteapi-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 quandoenabledModesé 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=RectangleSnipdisponibiliza as opções de captura de forma livre (do URI) e de retângulo, com a forma livre pré-selecionada. - Se
enabledModesfor 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 deenabledModes.
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.
Conteúdo relacionado
Windows developer