Lancer Snipping Tool

Cet article spécifie le protocole permettant d’intégrer des applications internes et tierces à l’outil Windows Snipping à l’aide du schéma ms-screenclip : URI (Uniform Resource Identifier). Le protocole prend en charge la capture d’images et de vidéos (avec audio) via l’outil Snipping, et les appelants d’application peuvent choisir les fonctionnalités de l’outil de capture d’écran affichées par leur application.

Fonctionnalités prises en charge

Le protocole Snipping Tool prend en charge les fonctionnalités suivantes :

• Capture de rectangle
• Capture de forme libre
• Capture de fenêtre
• Enregistrement d’écran
• Personnalisation des modes de capture disponibles
• Enregistrement automatique (facultatif)

Spécification du protocole

Format d’URI :ms-screenclip://{host}/{path}?{query parameters}

Hôte de capture

Utilisez l’hôte capture pour lancer la superposition de capture de l'outil de capture Snipping.

Chemin

Paramètres de mode (capture/image)

Pour le chemin d’accès /image , vous devez spécifier exactement un paramètre de mode. Les paramètres de mode sont des paramètres de requête nus sans valeur.

Paramètres de requête (capture)

Découvrir l’hôte

Utilisez l’hôte discover pour interroger les fonctionnalités, modes et versions de protocole prises en charge par l’outil Snipping au moment de l’exécution. Cela est utile pour vérifier la compatibilité avant d’effectuer une demande de capture.

Paramètres de requête (découverte)

Découvrez un exemple

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

Découvrir le format de réponse

La réponse est un objet JSON ajouté à l’URI de redirection en tant que paramètre de discover requête. Il contient :

• version : dernière version du protocole que cette build de l'outil Capture d’écran prend en charge.
• defaultVersion: version du protocole supposée lorsqu’une requête omet api-version. Lisez ceci pour comprendre comment vos requêtes non épinglées sont interprétées.
• supportedVersions: Tableau des versions de protocole que cette version de l’outil capture d'écran accepte.
• capabilities: Tableau d’opérations de capture prises en charge, chacune avec :
  • path: point de terminaison de capture (par exemple, capture/image, capture/video).
  • methods: méthodes de type HTTP prises en charge.
  • parameters: paramètres disponibles pour le point de terminaison.
  • description: Description de la fonctionnalité.

{
  "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."
    }
  ]
}

Modes activés

Le enabledModes paramètre vous permet de contrôler les modes de capture disponibles dans l’interface utilisateur de l’outil de capture. Utilisez-la pour restreindre ou développer les choix de l’utilisateur en fonction des exigences de votre application.

Modes pris en charge

Exemples de EnabledModes

Activez uniquement le rectangle snip :

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

Activer la capture de rectangle et de fenêtre :

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

Activez tous les modes de capture d’écran :

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

Activez le mode d’enregistrement uniquement :

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

Activez plusieurs modes d’enregistrement et de capture :

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

Étant donné que la forme libre est spécifiée dans l’URI, elle est pré-sélectionnée. Les utilisateurs peuvent basculer entre découpe en forme libre, découpe rectangulaire et enregistrement rectangulaire.

Responses

Une fois que l’utilisateur a terminé ou annulé une capture, l’outil Snipping renvoie une réponse à votre application via le redirect-uri. La réponse est structurée en tant que paramètres de requête URI ajoutés à votre URI de redirection.

Si vous redirect-uri incluez déjà des paramètres de requête (par exemple, my-app://response?sessionId=abc), ces paramètres sont conservés et les paramètres de réponse sont ajoutés avec &. Vous pouvez l'utiliser pour transférer l'état spécifique de l'appelant via le rappel. La valeur sessionId=abc est renvoyée dans l'URI de réponse avec code, reason, x-request-correlation-id, et (pour une capture réussie) file-access-token.

Paramètres de réponse

Codes d’état

Exemples de réponses

Capture réussie :

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

L’utilisateur a annulé :

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

Requête non valide (paramètre de mode manquant) :

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

Exemples d’URI complets

Lancement à partir de votre application

Vous devez utiliser Launcher.LaunchUriAsync pour lancer L’outil Snipping à partir de votre application empaquetée. D’autres méthodes de lancement (telles que Process.Start l’exécution de l’interpréteur de commandes) ne fournissent pas l’identité de votre application et L’outil Snipping ne fournit pas la réponse.

Étape 1 : Inscrire un gestionnaire de protocole

Inscrivez un protocole personnalisé dans votre Package.appxmanifest application afin que votre application puisse recevoir la réponse de rappel. Le nom du protocole doit correspondre au schéma utilisé dans votre 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>

Pour plus d’informations sur l’inscription et la gestion des activations de protocole, consultez Gérer l’activation d’URI .

Étape 2 : Lancer l’outil de capture d’écran

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

Étape 3 : Gérer la réponse

Une fois la capture terminée (ou en cas d'annulation par l'utilisateur), l'outil Capture active votre application via votre redirect-uri avec les paramètres de résultat ajoutés sous forme de chaînes de requête. La plupart des intégrations sont déjà en cours d’exécution lorsque la réponse arrive ( l’appelant a lancé l’outil Snipping, puis attendu le rappel), de sorte que votre application doit gérer à la fois l’activation de démarrage à froid (l’application n’était pas en cours d’exécution) et la réactivation chaude (l’application est déjà en cours d’exécution). Abonnez-vous aux deux parcours dans App.xaml.cs.

Gérer une réponse de capture (image ou vidéo) :

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

Gérer une réponse de découverte :

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

Récupération d’un média capturé à l’aide du jeton

Utilisez la classe SharedStorageAccessManager pour valider file-access-token et accéder au fichier capturé.

Restrictions de jeton :

• Un jeton ne peut être échangé qu’une seule fois. Après l’échange, il n’est plus valide.
• Un jeton expire après 14 jours.
• Une application ne peut pas avoir plus de 1 000 jetons actifs. Une fois qu’un jeton est échangé, supprimé ou expire, il ne compte plus par rapport au 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);

Considérations relatives à la sécurité

L’application Snipping Tool valide toutes les valeurs redirect-uri avant de les lancer. Les protections suivantes sont appliquées :

• Appelants d’application empaquetés : lorsque votre application est une application Windows empaquetée (MSIX), le système d’exploitation achemine en toute sécurité la réponse de capture vers votre application, ce qui garantit que seule votre application peut la recevoir. Il s’agit du chemin d’intégration recommandé.
• Validation d’entrée : L’outil de capture d’écran rejette les URI de redirection qui contiennent des chemins UNC, des espaces blancs de début/fin ou des caractères de contrôle.
• Aucun fragment : les URI de redirection qui contiennent un fragment d’URL (par exemple) my-app://response#sectionsont rejetés. L’outil de capture ajoute les paramètres de réponse sous forme de chaîne de requête, et un fragment les avale.
• Protection de référencement automatique : les URI de redirection qui provoquent l’activation récursive de l’outil Snipping sont bloquées.

Contenu connexe

• Gérer l’activation de l’URI
• Classe SharedStorageAccessManager
• Utiliser l'outil Capture d'écran pour effectuer des captures d'écran