Knipprogramma starten

In dit artikel wordt het protocol opgegeven voor het integreren van toepassingen van eerste en derden met het Windows knipprogramma met behulp van het schema ms-screenclip: URI-schema (Uniform Resource Identifier). Het protocol ondersteunt het vastleggen van afbeeldingen en video (met audio) via Snipping Tool, en app-oproepen kunnen kiezen welke functies van Snipping Tool in hun app worden weergegeven.

Ondersteunde functies

Het knipprogrammaprotocol ondersteunt de volgende functies:

• Rechthoek vastleggen
• Vrije vorm vastleggen
• Vensteropname
• Schermopname
• Beschikbare opnamemodi aanpassen
• Automatisch opslaan (optioneel)

Protocolspecificatie

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

Host opnemen

Gebruik de host om de capture capture-overlay van het knipprogramma te starten.

Pad

Modusparameters (opname/beeld)

Voor het /image pad moet u precies één modusparameter opgeven. Modusparameters zijn lege queryparameters zonder waarde.

Queryparameters (vastleggen)

Host detecteren

Gebruik de discover host om tijdens runtime query's uit te voeren op de ondersteunde mogelijkheden, modi en protocolversie van het knipprogramma. Dit is handig voor het controleren van de compatibiliteit voordat u een capture-aanvraag indient.

Queryparameters (ontdekken)

Voorbeeld van ontdekken

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

Antwoordindeling detecteren

Het antwoord is een JSON-object dat als queryparameter discover is toegevoegd aan de omleidings-URI. Het bevat:

• version: De nieuwste protocolversie die deze build van het knipprogramma ondersteunt.
• defaultVersion: Aangenomen protocolversie wanneer een aanvraag api-version weglaat. Lees dit om te begrijpen hoe uw niet-vaste aanvragen worden geïnterpreteerd.
• supportedVersions: Matrix van protocolversies die deze knipprogramma-build accepteert.
• capabilities: Matrix van ondersteunde opnamebewerkingen, elk met:
  • path: Het eindpunt voor vastleggen (bijvoorbeeld capture/image, capture/video).
  • methods: Ondersteunde HTTP-achtige methoden.
  • parameters: Beschikbare parameters voor het eindpunt.
  • description: Beschrijving van de mogelijkheid.

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

enabledModes Met de parameter kunt u bepalen welke opnamemodi beschikbaar zijn in de gebruikersinterface van het knipprogramma. Gebruik deze om de keuzen van de gebruiker te beperken of uit te breiden om aan de vereisten van uw toepassing te voldoen.

Ondersteunde modi

Voorbeelden van EnabledModes

Alleen rechthoekuitknipsel inschakelen:

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

Schakel rechthoek- of vensterknip in:

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

Schakel alle knipmodi in:

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

Alleen opnamemodus inschakelen:

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

Schakel meerdere knip- en opnamemodi in:

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

Omdat vrije vorm is opgegeven in de URI, wordt deze vooraf geselecteerd. Gebruikers kunnen schakelen tussen vrije vorm, rechthoekfragment en rechthoekopname.

Responses

Nadat de gebruiker een opname voltooit of annuleert, stuurt het Knipprogramma een antwoord terug naar uw applicatie via de redirect-uri. Het antwoord is gestructureerd als URI-queryparameters die zijn toegevoegd aan uw omleidings-URI.

Als de redirect-uri queryparameters al zijn opgenomen (bijvoorbeeld my-app://response?sessionId=abc), blijven deze parameters behouden en worden de antwoordparameters toegevoegd aan &. U kunt dit gebruiken om de aanroeperspecifieke status via de retouraanroep heen en weer te sturen. De waarde sessionId=abc wordt samen met code, reason, x-request-correlation-id en (voor een geslaagde opname) file-access-token herhaald in de antwoord-URI.

Antwoordparameters

Statuscodes

Voorbeeldantwoorden

Geslaagde opname:

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

Gebruiker geannuleerd:

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

Ongeldige aanvraag (ontbrekende modusparameter):

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

Volledige URI-voorbeelden

Starten vanuit uw app

U moet Launcher.LaunchUriAsync gebruiken om het knipprogramma te starten vanuit uw verpakte app. Andere startmethoden (zoals Process.Start of het uitvoeren van shell-commando's) geven de identiteit van uw app niet door, en Snipping Tool levert geen reactie.

Stap 1: Een protocolhandler registreren

Registreer een aangepast protocol in uw Package.appxmanifest app, zodat uw app het callback-antwoord kan ontvangen. De protocolnaam moet overeenkomen met het schema dat wordt gebruikt in uw 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>

Zie URI-activering afhandelen voor meer informatie over het registreren en verwerken van protocolactivering.

Stap 2: Knipprogramma starten

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

Stap 3: het antwoord afhandelen

Wanneer de opname is voltooid (of de gebruiker annuleert), activeert Snipping Tool uw app via uw redirect-uri met resultaatparameters die als querystrings zijn toegevoegd. De meeste integraties worden al uitgevoerd wanneer het antwoord binnenkomt - de aanroeper heeft Knipprogramma gestart en vervolgens gewacht op een terugroepbericht - dus uw app moet zowel de koude-startactivering verwerken (de app was niet actief) als de warme heractivatie (de app draait al). Abonneer u op beide routes in App.xaml.cs.

Een antwoord voor vastleggen verwerken (afbeelding of 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}");
    }
}

Een antwoord op een ontdekking verwerken:

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

Vastgelegde media ophalen met behulp van het token

Gebruik de klasse SharedStorageAccessManager om het file-access-token vastgelegde bestand in te wisselen en te openen.

Tokenbeperkingen:

• Een token kan slechts eenmaal worden ingewisseld. Na inwisseling is deze niet meer geldig.
• Een token verloopt na 14 dagen.
• Een app mag niet meer dan 1000 actieve tokens hebben. Nadat een token is ingewisseld, verwijderd of verlopen, wordt het niet meer meegeteld voor het quotum.

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

Beveiligingsoverwegingen

Het knipprogramma valideert alle redirect-uri waarden voordat u ze start. De volgende beveiligingen worden afgedwongen:

• Packaged app-bellers: Wanneer uw app een verpakte Windows-app (MSIX) is, stuurt het besturingssysteem het opnameantwoord veilig terug naar uw app, zodat alleen uw app deze kan ontvangen. Dit is het aanbevolen integratiepad.
• Invoervalidatie: Snipping Tool weigert omleidings-URI's die UNC-paden, voorloop- of volgspaties, of besturingstekens bevatten.
• Geen fragmenten: omleidings-URI's die een URL-fragment (bijvoorbeeld my-app://response#section) bevatten, worden geweigerd. Het knipprogramma voegt de antwoordparameters toe als een querytekenreeks en er wordt een fragment ingeslikt.
• Zelfverwijzende beveiliging: omleidings-URI's die recursieve activering van het knipprogramma veroorzaken, worden geblokkeerd.

Verwante inhoud

• URI-activering afhandelen
• Klasse SharedStorageAccessManager
• Het knipprogramma gebruiken om schermopnamen vast te leggen