Snipping Tool starten

In diesem Artikel wird das Protokoll für die Integration von Erst- und Drittanbieteranwendungen in das Windows Snipping Tool mithilfe des Schemas ms-screenclip: URI (Uniform Resource Identifier) angegeben. Das Protokoll unterstützt die Aufnahme von Bildern und Videos (mit Audio) über das Snipping Tool, und App-Aufrufer können auswählen, welche Snipping Tool-Features ihre App anzeigt.

Unterstützte Funktionen

Das Snipping Tool-Protokoll unterstützt die folgenden Features:

• Rechteckaufnahme
• Freiform-Erfassung
• Fenstererfassung
• Bildschirmaufzeichnung
• Anpassen der verfügbaren Aufnahmemodi
• Automatisches Speichern (optional)

Protokollspezifikation

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

Aufnahmehost

Verwenden Sie den capture Host, um die Aufnahmeüberlagerung des Snipping Tools zu starten.

Pfad

Modusparameter (Aufnahme/Bild)

Für den /image Pfad müssen Sie genau einen Modusparameter angeben. Modusparameter sind bare Abfrageparameter ohne Wert.

Abfrageparameter (Erfassung)

Host entdecken

Verwenden Sie den discover Host, um die unterstützten Funktionen, Modi und Protokollversion des Snipping Tools zur Laufzeit abzufragen. Dies ist nützlich, um die Kompatibilität zu überprüfen, bevor Sie eine Aufnahmeanforderung vornehmen.

Abfrageparameter (Entdecken)

Entdecken Sie Beispiel

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

Antwortformat entdecken

Die Antwort ist ein JSON-Objekt, das als Abfrageparameter an den Umleitungs-URI discover angefügt wird. Sie enthält folgende Elemente:

• version: Neueste Protokollversion, die dieser Snipping-Tool-Build unterstützt.
• defaultVersion: Protokollversion wird angenommen, wenn eine Anforderung api-version auslässt. Lesen Sie dies, um zu verstehen, wie Ihre losgelösten Anforderungen interpretiert werden.
• supportedVersions: Array von Protokollversionen, die von diesem Snipping-Tool akzeptiert werden.
• capabilities: Array der unterstützten Erfassungsvorgänge, jeweils mit:
  • path: Der Aufnahmeendpunkt (z. B. capture/image, capture/video).
  • methods: Unterstützte HTTP-ähnliche Methoden.
  • parameters: Verfügbare Parameter für den Endpunkt.
  • description: Beschreibung der Funktion.

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

Aktivierte Modi

Mit dem enabledModes Parameter können Sie steuern, welche Aufnahmemodi in der Benutzeroberfläche des Snipping-Tools verfügbar sind. Verwenden Sie sie, um die Auswahlmöglichkeiten des Benutzers einzuschränken oder zu erweitern, um den Anforderungen Ihrer Anwendung zu entsprechen.

Unterstützte Modi

EnabledModes-Beispiele

Nur Rechteck-Ausschnitt aktivieren:

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

Aktivieren Sie Rechteck- und Fensterausschneiden:

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

Aktivieren Sie alle Snipping-Modi:

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

Nur Aufzeichnungsmodus aktivieren:

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

Aktivieren sie mehrere Snipping- und Aufzeichnungsmodi:

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

Da die Freihandform im URI angegeben ist, wird sie automatisch vorausgewählt. Benutzer können zwischen Freihandform, Rechteckschnappschuss und Rechteckaufnahme wechseln.

Antworten

Nachdem der Benutzer einen Ausschnitt erstellt oder abgebrochen hat, sendet das Snipping Tool eine Antwort über die redirect-uri an Ihre Anwendung. Die Antwort ist als URI-Abfrageparameter strukturiert, die an den Umleitungs-URI angefügt werden.

Wenn Ihre redirect-uri bereits Abfrageparameter enthalten (z. B. my-app://response?sessionId=abc), werden diese Parameter beibehalten, und die Antwortparameter werden mit & angefügt. Sie können dies verwenden, um den anruferspezifischen Zustand über den Rückruf abzurunden – der Wert sessionId=abc wird zusammen mit code, reason, , x-request-correlation-idund (für eine erfolgreiche Aufnahme) file-access-tokenin den Antwort-URI zurückgerufen.

Antwortparameter

Statuscodes

Beispielantworten

Erfolgreiche Erfassung:

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

Benutzerabbruch:

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

Ungültige Anforderung (fehlender Modusparameter):

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

Vollständige URI-Beispiele

Starten von Ihrer App

Sie müssen Launcher.LaunchUriAsync verwenden, um das Snipping Tool aus Ihrer verpackten App zu starten. Andere Startmethoden (wie Process.Start oder Shellausführung) verleihen Ihrer App keine Identität, und das Snipping Tool übermittelt die Antwort nicht.

Schritt 1: Registrieren eines Protokollhandlers

Registrieren Sie ein benutzerdefiniertes Protokoll in Ihrer Package.appxmanifest App, damit Ihre App die Rückrufantwort empfangen kann. Der Protokollname muss mit dem in Ihrer redirect-uriDatei verwendeten Schema übereinstimmen.

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

Weitere Informationen zum Registrieren und Behandeln von Protokollaktivierungen finden Sie unter Behandeln der URI-Aktivierung .

Schritt 2: Starten des Snipping-Tools

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

Schritt 3: Verarbeiten der Antwort

Wenn die Erfassung abgeschlossen ist (oder der Benutzer abbricht), aktiviert das Snipping Tool Ihre App über redirect-uri, indem Ergebnisparameter als Abfragezeichenfolgen angefügt werden. Die meisten Integrationen laufen bereits, wenn die Antwort eingeht – das Snipping Tool wurde aufgerufen und hat dann auf den Callback gewartet –, sodass Ihre App sowohl die Kaltstartaktivierung (die App war nicht ausgeführt) als auch die warme Reaktivierung (die App läuft bereits) verarbeiten muss. Abonnieren Sie beide Pfade in App.xaml.cs.

Behandeln einer Aufnahmeantwort (Bild oder Video):

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

Verarbeiten einer Entdeckungsantwort:

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

Abrufen erfasster Medien mithilfe des Tokens

Verwenden Sie die SharedStorageAccessManager-Klasse , um die file-access-token erfasste Datei einzulösen und darauf zuzugreifen.

Tokeneinschränkungen:

• Ein Token kann nur einmal eingelöst werden. Nach der Einlösung ist sie nicht mehr gültig.
• Ein Token läuft nach 14 Tagen ab.
• Eine App darf nicht über mehr als 1000 aktive Token verfügen. Nachdem ein Token eingelöst, entfernt oder abläuft, zählt es nicht mehr für das Kontingent.

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

Sicherheitsaspekte

Das Snipping Tool überprüft alle redirect-uri Werte, bevor sie gestartet werden. Die folgenden Schutzmaßnahmen werden erzwungen:

• Packaged-App-Aufrufer: Wenn Ihre App eine verpackte Windows App (MSIX) ist, leitet das Betriebssystem die Aufnahmeantwort sicher an Ihre App weiter und stellt sicher, dass ihre App sie empfangen kann. Dies ist der empfohlene Integrationspfad.
• Eingabeüberprüfung: Das Snipping Tool lehnt Umleitungs-URIs ab, die UNC-Pfade, führende/nachfolgende Leerzeichen oder Steuerzeichen enthalten.
• Keine Fragmente: Umleitungs-URIs, die ein URL-Fragment enthalten (z. B my-app://response#section. ) werden abgelehnt. Das Snipping Tool fügt die Antwortparameter als Abfragezeichenfolge an, und ein Fragment verschluckt sie.
• Selbstverweisender Schutz: Umleitungs-URIs, die eine rekursive Aktivierung des Snipping-Tools verursachen würden, werden blockiert.

Verwandte Inhalte

• URI-Aktivierung bearbeiten
• SharedStorageAccessManager-Klasse
• Aufnehmen von Screenshots mithilfe des Snipping Tools