Starta Skärmklippsverktyget

Den här artikeln anger protokollet för integrering av program från första och tredje part med Windows Snipping Tool med hjälp av schemat ms-screenclip: URI (Uniform Resource Identifier). Protokollet stöder insamling av bilder och video (med ljud) via skärmklippsverktyget, och appuppringare kan välja vilka funktioner i skärmklippsverktyget som deras app ska visa.

Funktioner som stöds

Protokollet Snipping Tool stöder följande funktioner:

• Rektangelupptagning
• Frihandstagning
• Avbildning av fönster
• Skärminspelning
• Anpassa tillgängliga avbildningslägen
• Spara automatiskt (valfritt)

Protokollspecifikation

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

Avbilda värd

Använd capture-värden för att starta Snipping Tools avbildningsöverlägg.

Väg

Lägesparametrar (uppfångning/avbildning)

/image För sökvägen måste du ange exakt en lägesparameter. Lägesparametrar är enkla query-parametrar utan värde.

Frågeparametrar (avbildning)

Identifiera värd

Använd discover värd för att fråga Snipping Tools stödda funktioner, lägen och protokollversioner under körning. Detta är användbart för att kontrollera kompatibiliteten innan du gör en avbildningsbegäran.

Frågeparametrar (upptäck)

Upptäck exempel

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

Identifiera svarsformat

Svaret är ett JSON-objekt som läggs till i omdirigerings-URI:n som frågeparameter discover. Den innehåller:

• version: Den senaste protokollversionen som stöds av denna Snipping Tool-byggnad.
• defaultVersion: Protokollversion som antas när en begäran utelämnar api-version. Läs det här för att förstå hur dina opinnade begäranden tolkas.
• supportedVersions: Matris med protokollversioner som den här Snipping Tool-versionen accepterar.
• capabilities: Matris med avbildningsåtgärder som stöds, var och en med:
  • path: Avbildningsslutpunkten (t.ex. capture/image, capture/video).
  • methods: HTTP-liknande metoder som stöds.
  • parameters: Tillgängliga parametrar för slutpunkten.
  • description: Beskrivning av funktionen.

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

AktiveradeLägen

Med enabledModes parametern kan du styra vilka avbildningslägen som är tillgängliga i användargränssnittet för skärmklippsverktyget. Använd den för att begränsa eller utöka användarens val för att matcha programmets krav.

Lägen som stöds

EnabledModes-exempel

Aktivera endast rektangelfragment:

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

Aktivera rektangel- och fönsterutklipp:

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

Aktivera alla skärmklippslägen:

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

Aktivera endast inspelningsläge:

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

Aktivera flera skärmklipps- och inspelningsalternativ:

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

Eftersom fri form har angetts i URI:n kommer den att vara förvald. Användare kan växla mellan frihandsklipp, rektangelklipp och rektangelinspelning.

Responses

När användaren har slutfört eller avbrutit en avbildning skickar Snipping Tool ett svar tillbaka till ditt program via redirect-uri. Svaret är strukturerat som URI-frågeparametrar som läggs till i din omdirigerings-URI.

Om dina redirect-uri redan innehåller frågeparametrar (till exempel my-app://response?sessionId=abc), bevaras dessa parametrar och svarsparametrarna läggs till med &. Du kan använda detta för att återanropsspecifikt tillstånd via återanropet – värdet sessionId=abc upprepas i svars-URI:n tillsammans med code, reason, x-request-correlation-idoch (för en lyckad avbildning) file-access-token.

Svarsparametrar

Statuskoder

Exempelsvar

Lyckad avbildning:

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

Användaren avbröt:

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

Ogiltig begäran (saknad modeparameter):

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

Fullständiga URI-exempel

Starta från din app

Du måste använda Launcher.LaunchUriAsync för att starta Snipping Tool från din paketerade app. Andra startmetoder (till exempel Process.Start eller shell-körning) ger inte appens identitet, och Snipping Tool levererar inte svaret.

Steg 1: Registrera en protokollhanterare

Registrera ett anpassat protokoll i din Package.appxmanifest så att appen kan ta emot motringningssvaret. Protokollnamnet måste matcha schemat som används i din 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>

Mer information om hur du registrerar och hanterar protokollaktiveringar finns i Hantera URI-aktivering .

Steg 2: Starta Skärmklippverktyget

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

Steg 3: Hantera svaret

När fångsten har slutförts (eller användaren avbryter), aktiverar Snipping Tool din app via din redirect-uri med resultatparametrar som läggs till i form av frågesträngar. De flesta integreringar körs redan när svaret kommer – anroparen startade Snipping Tool och väntade sedan på återanropet – så appen måste hantera både kallstartsaktivering (appen kördes inte) och varm återaktivering (appen körs redan). Prenumerera på båda banorna i App.xaml.cs.

Hantera ett avbildningssvar (bild eller 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}");
    }
}

Hantera ett upptäckingssvar:

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

Hämtar insamlade medier med hjälp av token

Använd klassen SharedStorageAccessManager för att lösa in file-access-token och komma åt den insamlade filen.

Tokenbegränsningar:

• En token kan bara lösas in en gång. Efter inlösen är den inte längre giltig.
• En token upphör att gälla efter 14 dagar.
• En app får inte ha fler än 1 000 aktiva token. När en token har lösts in, tagits bort eller upphör att gälla räknas den inte längre mot kvoten.

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

Säkerhetsfrågor

Snipping Tool verifierar alla redirect-uri värden innan du startar dem. Följande skydd tillämpas:

• Packeterade applikationsanrop: När din app är en paketerad Windows-app (MSIX), dirigerar operativsystemet säkert insamlingssvaret tillbaka till din app, så att endast din app kan ta emot det. Det här är den rekommenderade integreringsvägen.
• Indatavalidering: Klippverktyget avvisar omdirigerings-URI:er som innehåller UNC-sökvägar, inledande och avslutande blanksteg, eller kontrolltecken.
• Inga fragment: Omdirigerings-URI:er som innehåller ett URL-fragment (till exempel my-app://response#section) avvisas. Snipping Tool lägger till svarsparametrarna som en frågesträng, och ett fragment skulle svälja dem.
• Självrefererande skydd: Omdirigerings-URI:er som skulle orsaka rekursiv aktivering av Snipping Tool blockeras.

Relaterat innehåll

• Hantera URI-aktiveringar
• SharedStorageAccessManager-klass
• Ta skärmbilder med hjälp av Skärmklippverktyget