Spustit nástroj Výstřižky

Tento článek definuje protokol pro integraci aplikací prvních a třetích stran s nástrojem Výstřižky ve Windows pomocí schématu ms-screenclip: URI (Uniform Resource Identifier). Protokol podporuje zachytávání obrázků a videa (se zvukem) prostřednictvím nástroje Výstřižky a uživatelé aplikací si mohou vybrat, které funkce nástroje Výstřižky se budou zobrazovat.

Podporované funkce

Protokol nástroje pro výstřižky podporuje následující funkce:

• Zachytávání obdélníků
• Freeform Capture
• Zachytávání oken
• Záznam obrazovky
• Přizpůsobení dostupných režimů zachycení
• Automatické ukládání (volitelné)

Specifikace protokolu

Formát identifikátoru URI:ms-screenclip://{host}/{path}?{query parameters}

Zachycení hostitele

Spusťte zachytávací překryv Nástroje Výstřižky pomocí capture hostitele.

Cesta

Parametry režimu (zachytávání/image)

/image Pro cestu musíte zadat přesně jeden parametr režimu. Parametry režimu jsou holé parametry dotazu bez hodnoty.

Parametry dotazu (zachytávání)

Zjišťování hostitele

Pomocí discover hostitele můžete za běhu získávat informace o podporovaných možnostech, režimech a verzích protokolu nástroje Výstřižky. To je užitečné při kontrole kompatibility před vytvořením žádosti o zachycení.

Parametry dotazu (zjišťování)

Objevit příklad

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

Zjistit formát odpovědi

Odpověď je JSON objekt připojený k přesměrovacímu URI jako parametr dotazu discover. Obsahuje:

• version: Nejnovější verze protokolu, kterou podporuje tento build Nástroje výstřižků.
• defaultVersion: Verze protokolu se předpokládá, když požadavek vynechá api-version. Přečtěte si toto, abyste pochopili, jak se interpretují vaše neukotvené požadavky.
• supportedVersions: Seznam verzí protokolu, které tato verze nástroje Nástroj pro vystřižení akceptuje.
• capabilities: Pole podporovaných operací zachytávání, z nichž každá obsahuje:
  • path: Koncový bod zachycení (např capture/image. , capture/video).
  • methods: Podporované metody podobné protokolu HTTP.
  • parameters: Dostupné parametry pro koncový bod.
  • description: Popis schopnosti.

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

Tento enabledModes parametr umožňuje určit, které režimy zachycení jsou k dispozici v uživatelském rozhraní nástroje Výstřižky. Použijte ho k omezení nebo rozšíření možností uživatele tak, aby odpovídaly požadavkům vaší aplikace.

Podporované režimy

Příklady EnabledModes

Povolit pouze obdélníkový výřez:

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

Povolit obdélník a výnip okna:

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

Povolte všechny režimy výstřižků:

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

Povolit pouze režim nahrávání:

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

Povolte více režimů výstřižků a nahrávek:

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

Vzhledem k tomu, že volný tvar je zadaný v identifikátoru URI, bude předem vybrán. Uživatelé můžou přepínat mezi volným výřezem, výstřihem obdélníku a záznamem obdélníku.

Responses

Jakmile uživatel dokončí nebo zruší zachytávání, nástroj Výstřižky odešle odpověď zpět do vaší aplikace prostřednictvím redirect-uri. Odpověď je strukturována jako URI parametry dotazu, které jsou připojeny k vašemu přesměrovacímu URI.

Pokud již obsahuje redirect-uri parametry dotazu (například my-app://response?sessionId=abc), tyto parametry se zachovají a parametry odpovědi se připojí pomocí &. Můžete to použít k přenosu kontextu volajícího skrz zpětné volání – hodnota sessionId=abc se odráží zpět v identifikátoru URI odpovědi spolu s code, reason, x-request-correlation-id a (pro úspěšné zachycení) file-access-token.

Parametry odpovědi

Stavové kódy

Ukázkové odpovědi

Úspěšné zachycení:

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

Uživatel byl zrušen:

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

Neplatný požadavek (chybějící parametr režimu):

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

Úplné příklady identifikátorů URI

Spuštění z aplikace

Ke spuštění nástroje Výstřižky z zabalené aplikace musíte použít Launcher.LaunchUriAsync . Jiné metody spuštění (například Process.Start nebo spuštění v shellu) neposkytnou identitu vaší aplikace a nástroj Výstřižky nedoručí odpověď.

Krok 1: Registrace obslužné rutiny protokolu

Zaregistrujte ve své Package.appxmanifest aplikaci vlastní protokol, aby vaše aplikace získala odpověď zpětného volání. Název protokolu se musí shodovat se schématem použitým ve vašem redirect-urisouboru .

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

Další podrobnosti o registraci a zpracování aktivací protokolu najdete v tématu Zpracování aktivace identifikátoru URI .

Krok 2: Spuštění nástroje Výstřižky

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

Krok 3: Zpracování odpovědi

Po dokončení zachytávání (nebo pokud uživatel zruší) nástroj Výstřižky aktivuje vaši aplikaci prostřednictvím redirect-uri s parametry výsledků, které jsou připojeny jako řetězce dotazu. Většina integrací se už spouští, když dorazí odpověď – volající spustil nástroj Výstřižky a pak čekal na zpětné volání, takže aplikace musí zpracovat aktivaci studeného spuštění (aplikace nebyla spuštěná) a teplá opětovná aktivace (aplikace už běží). Přihlaste se k odběru obou kanálů ve App.xaml.cs.

Zpracování odpovědi na zachytávání (obrázek nebo 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}");
    }
}

Zpracování odpovědi na zjišťování:

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

Načítání zachyceného média pomocí tokenu

K uplatnění zachyceného souboru a přístupu k němu použijte třídu file-access-token.

Omezení tokenu:

• Token lze uplatnit pouze jednou. Po uplatnění už není platný.
• Platnost tokenu vyprší po 14 dnech.
• Aplikace nemůže mít více než 1 000 aktivních tokenů. Po uplatnění, odebrání nebo vypršení platnosti tokenu se už do kvóty nezapočítá.

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

Bezpečnostní aspekty

Nástroj Výstřižky před spuštěním ověří všechny redirect-uri hodnoty. Vynucují se následující ochrany:

• Balené volající aplikace: Pokud je vaše aplikace zabalenou aplikací Windows (MSIX), operační systém bezpečně směruje odpověď zachycení zpět do vaší aplikace, aby ji mohla přijímat pouze vaše aplikace. Toto je doporučená cesta integrace.
• Ověřování vstupu: Nástroj výstřižky odmítne identifikátory URI přesměrování, které obsahují cesty UNC, počáteční nebo koncové prázdné znaky nebo řídicí znaky.
• Žádné fragmenty: Identifikátory URI přesměrování, které obsahují fragment adresy URL (například my-app://response#section), jsou odmítnuty. Aplikace Snipping Tool připojí parametry odpovědi jako řetězec dotazu, a fragment by je spolkl.
• Sebeodkazování ochrana: Přesměrovací URI, které by způsobily rekurzivní aktivaci nástroje Výstřižek, jsou blokované.

Související obsah

• Zpracujte aktivaci identifikátoru URI
• Třída SharedStorageAccessManager
• Použijte nástroj Výstřižky k pořízení screenshotů