Képmetsző eszköz indítása

Ez a cikk a ms-screenclip: URI (Uniform Resource Identifier) séma használatával határozza meg az első és harmadik féltől származó alkalmazások Windows Snipping Tool használatával történő integrálásának protokollját. A protokoll támogatja a képek és videók rögzítését (hanggal) a Képmetsző eszköz segítségével, és az alkalmazáshívók kiválaszthatják, hogy mely Snipping Tool funkciók jelenjenek meg az alkalmazásukban.

Important

Ehhez a protokollhoz packaged Windows alkalmazásra (MSIX) van szükség. Amikor az alkalmazás be van csomagolva, az operációs rendszer automatikusan biztosítja az alkalmazás identitását a Képmetsző eszköznek, amely ezzel biztonságosan visszairányítja a rögzítési választ az alkalmazáshoz. A kicsomagolatlan (Win32) hívók nem fogadhatnak válaszokat a redirect-uri-on keresztül. Ha egy csomagolatlan alkalmazás biztosít egy redirect-uri, a Snipping Tool nem fogja kézbesíteni a választ, és a rögzítési felhasználói felület megjelenítése nélkül is kiléphet.

Megjegyzés:

Ez a protokoll lecseréli a Launch screen snipping (Elavult) funkcióban dokumentált élményt, amely most elavult.

Támogatott funkciók

A Snipping Tool protokoll a következő funkciókat támogatja:

  • Téglalap rögzítése
  • Szabadformájú rögzítés
  • Ablakfelvétel
  • Képernyőfelvétel
  • Az elérhető rögzítési módok testreszabása
  • Automatikus mentés (nem kötelező)

Protokoll specifikációja

URI formátum:ms-screenclip://{host}/{path}?{query parameters}

Komponens Description Értékek
Séma A Snipping Tool egyéni sémája ms-screenclip
Házigazda A Snipping Tool művelet végrehajtása capture vagy discover
Path A rögzíteni kívánt médiatípus (csak a capture szerverre vonatkozik, a discover szerver nem rendelkezik útvonallal) /image vagy /video
Query A művelet paraméterei Lásd az alábbi táblázatokat

Megjegyzés:

Az elérési utak és a lekérdezési paraméterek neve nem megkülönbözteti a kis- és nagybetűket. Például ms-screenclip://capture/Image?Redirect-Uri=my-app://response ugyanúgy viselkedik, mint ms-screenclip://capture/image?redirect-uri=my-app://response.

Gazdagép rögzítése

A capture host rendszer használatával jelenítse meg a Snipping Tool rögzítési átfedését.

Elérési útvonal

Elérési útvonal Description
/image Elindítja a képrögzítést (képernyőkép). Módparamétert igényel.
/video Elindítja a videorögzítést (képernyőfelvétel). Mindig téglalap módot használ.

Módparaméterek (rögzítés/kép)

/image Az elérési úthoz pontosan egy módparamétert kell megadnia. A módparaméterek olyan lekérdezési paraméterek, amelyeknek nincs értékük.

Paraméter Description
rectangle Interaktív téglalaprögzítési mód.
freeform Interaktív szabadkéű rögzítési mód.
window Interaktív ablakrögzítési mód.

Important

A módparamétereket érték nélkül kell megadni. Használja &rectangle, ne&rectangle=value. Ha értéket ad meg, hibaüzenet jelenik meg.

Ehhez /imagepontosan egy módparamétert kell megadnia. Ha nullát vagy egynél több módot ad meg, hibaüzenet jelenik 400 Bad Request meg. A /videorendszer minden módparamétert figyelmen kívül hagy.

Lekérdezési paraméterek (rögzítés)

Megjegyzés:

A lekérdezési paraméterek bármilyen sorrendben megadhatók.

Paraméter Típus Szükséges Description Alapértelmezett
redirect-uri URI Igen Visszahívási URI, ahol a Képmetsző eszköz elküldi a rögzítési választ. Az alkalmazásnak regisztrálnia kell egy protokollkezelőt ehhez az URI-sémához. Ha nincs megadva, a Képmetsző eszköz nem jeleníti meg a rögzítési felhasználói felületet, és nem ad vissza választ. nincs adat
user-agent karakterlánc Nem (erősen ajánlott) A hívó alkalmazás azonosítója, amelyet naplózáshoz és elemzéshez használnak. A problémák támogatási csatornákon keresztüli diagnosztizálásához szükséges; saját felelősségére kihagyhatja. nincs adat
api-version karakterlánc No Használandó protokollverzió, például "1.2". Ha nincs megadva, a rendszer verzióként 1.2dolgozza fel a kérést. 1.2
x-request-correlation-id karakterlánc No A kérés egyedi azonosítója, amely lehetővé teszi egy adott tranzakcióra vagy eseményláncra való hivatkozást. Automatikusan létrehozott GUID
enabledModes string (lista) No A rögzítési módokat szabályozó vezérlők a felhasználói felületen érhetők el. Lásd alább az EnabledModes című témakört . Csak az URI-ban megadott mód
auto-save jelölő No Jelen esetben a rendszer automatikusan menti a rögzített képernyőképet vagy felvételt a felhasználó eszközére. Nincs jelen (nincs automatikus mentés)

Megjegyzés:

Az alapértelmezett beállítás api-version1.2 nem változik az újabb protokollverziók kiadásakor. Az kihagyott api-version kérések feldolgozása mindig a 1.2következőképpen történik: . Ha egy későbbi verzióban hozzáadott funkciókat szeretne használni, állítsa az api-version adott verzióra. Javasoljuk, hogy minden kérésben explicit módon adja meg api-version , hogy az alkalmazás az implicit alapértelmezett helyett egy ismert protokollverzióhoz legyen kötve.

Megjegyzés:

Amikor megadja api-version, annak pontosan meg kell egyeznie a /discover válasz tömbjének egyik értékével supportedVersions (jelenleg 1.0, 1.1és 1.2). Bármely más érték – beleértve a köztes értékeket, például 1.151.0abc a hibásan formázott értékeket – választ ad 400 Bad Request vissza. Ha egy adott Snipping Tool-build által elfogadott verziókészletet szeretne felderíteni, hívja meg a felderítő gazdagépet.

Megjegyzés:

A auto-save jelölő tiszteletben tartja a felhasználó Snipping Tool beállításait. Ha a felhasználó letiltotta az automatikus mentést a Képmetsző eszközben, a rendszer akkor sem menti a rögzítést az eszközre, ha a kérés tartalmazza auto-save.

Hoszt felfedezése

A discover gazdagép segítségével lekérdezheti a Snipping Tool által támogatott képességeket, módokat és a protokoll verzióját futásidőben. Ez hasznos a kompatibilitás ellenőrzéséhez a rögzítési kérések végrehajtása előtt.

Lekérdezési paraméterek (felderítés)

Paraméter Típus Szükséges Description Alapértelmezett
redirect-uri URI Igen Visszahívási URI, ahol a Snipping Tool elküldi a képességekre adott választ. Az alkalmazásnak regisztrálnia kell egy protokollkezelőt ehhez az URI-sémához. Ha nincs megadva, a Képmetsző eszköz nem ad vissza választ. nincs adat
user-agent karakterlánc Nem (erősen ajánlott) A hívó alkalmazás azonosítója, amelyet naplózáshoz és elemzéshez használnak. nincs adat
x-request-correlation-id karakterlánc No A kérés egyedi azonosítója. Automatikusan létrehozott GUID

Fedezze fel a példát

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

Válaszformátum felderítése

A válasz egy JSON-objektum, amely a lekérdezési paraméterként hozzá van fűzve az discover átirányítási URI-hoz. A következőket tartalmazza:

  • version: A Snipping Tool build által támogatott legújabb protokollverzió.
  • defaultVersion: A protokoll verziója feltételezett, ha egy kérésben api-version hiányzik. Olvassa el ezt, hogy megértse, hogyan vannak értelmezve a nem rögzített kérések.
  • supportedVersions: A Snipping Tool build által elfogadott protokollverziók tömbje.
  • capabilities: Támogatott rögzítési műveletek tömbje, mindegyik a következőkkel:
    • path: A rögzítési végpont (pl. capture/image, capture/video).
    • methods: Támogatott HTTP-szerű metódusok.
    • parameters: Elérhető paraméterek a végponthoz.
    • description: A képesség leírása.
{
  "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."
    }
  ]
}

EngedélyezettMódok

A enabledModes paraméter segítségével szabályozhatja, hogy mely rögzítési módok érhetők el a Képmetsző eszköz felhasználói felületén. Ezzel korlátozhatja vagy bővítheti a felhasználó választási lehetőségeit az alkalmazás követelményeinek megfelelően.

Támogatott módok

Mode Description
RectangleSnip Téglalaprögzítési mód.
WindowSnip Ablakrögzítési mód.
FreeformSnip Szabadkézi rögzítési mód.
FullscreenSnip Teljes képernyős rögzítési mód.
SnippingAllModes Minden képrögzítési mód: RectangleSnip, WindowSnip, FreeformSnip, FullscreenSnip.
RectangleRecord Téglalap alakú rögzítési mód
RecordAllModes Minden rögzítési mód: jelenleg csak RectangleRecord.
All Minden támogatott mód: a SnippingAllModes és RecordAllModes egyesítése.

Tip

All, SnippingAllModesés RecordAllModes összesített értékek. Az általuk tartalmazott módok a Snipping Tool egyes kiadásaiban változhatnak. Az ilyen értékeket használó alkalmazások automatikusan felveszik a jövőbeli kiadásokban hozzáadott módokat. Ha az elérhető módok készletét a frissítések között szeretné rögzíteni, adja meg kifejezetten az adott módokat (például RectangleSnip,FreeformSnip).

Important

  • Ehhez /imageaz rectangle van egy módparaméterre (példáulfreeform, , window, ) akkor is, ha enabledModes meg van adva. A módparaméter határozza meg az eredetileg kiválasztott módot.
  • Az URI-ban megadott mód mindig elérhető a felhasználói felületen, még akkor is, ha nem szerepel a enabledModeslistában. Tegyük fel például, ?freeform&enabledModes=RectangleSnip hogy a szabadon formálható (URI-alapú) és téglalap kivágásokat is elérhetővé teszi, a szabadon formálható előre kijelölve van.
  • Ha enabledModes nincs megadva, csak az URI-ban megadott mód lesz elérhető a felhasználói felületen.
  • Ha /image nincs megadva módparaméter, a kérés érvénytelen, és mindenképp hibát eredményez, függetlenül a enabledModes-től.

EnabledModes példák

Csak téglalap kivágás engedélyezése:

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

Téglalap- és ablaksznip engedélyezése:

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

Az összes kivágási mód engedélyezése:

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

Csak a rögzítési mód engedélyezése:

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

Több képernyőkép készítési és felvételi mód engedélyezése:

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

Mivel a freeform meg van adva az URI-ban, automatikusan előre lesz kiválasztva. A felhasználók választhatnak szabadkézi, téglalap alakú snip és rögzítés között.

Responses

Miután a felhasználó befejezte vagy megszakította a rögzítést, a Snipping Tool választ küld az alkalmazásnak a redirect-uri-n keresztül. A válasz az átirányítási URI-hoz hozzáfűzött URI-lekérdezési paraméterekként van strukturálva.

Ha a redirect-uri már tartalmaz lekérdezési paramétereket (például my-app://response?sessionId=abc), ezeket a paramétereket megőrizzük, és a válaszparamétereket hozzáfűzzük &. Ezt használhatja arra, hogy a hívóspecifikus állapotot küldés-visszafogadási formában továbbítsa a visszahíváson keresztül — az érték sessionId=abc visszatér a válasz URI-jában, valamint code, reason, x-request-correlation-id és (sikeres rögzítés esetén) file-access-token.

Válasz paraméterei

Paraméter Típus Jelen Description
code int Always AZ eredményt jelző HTTP-stílusú állapotkód.
reason karakterlánc Always Az eredmény ember által olvasható leírása.
x-request-correlation-id karakterlánc Always Az eredeti kérés korrelációs azonosítója (vagy egy automatikusan létrehozott).
file-access-token karakterlánc Csak siker A SharedStorageAccessManager token, amely a rögzített média azonosítóját jelképezi. Ezzel lekérheti a fájlt.
discover karakterlánc Csak felfedezz A képességek válaszát tartalmazó, URL-kódolású JSON.

Állapotkódok

Code Jogcím Description
200 Success A rögzítés sikeresen befejeződött. A file-access-token része a válasznak.
400 Hibás kérelem – Érvénytelen vagy hiányzó paraméterek A kérés nem dolgozható fel. Ellenőrizze, hogy az összes szükséges paraméter jelen van-e és érvényes-e.
408 Várakozási idő túllépése – a művelet túl sokáig tartott A művelet a befejezés előtt túllépte az időkorlátot.
499 Ügyfél lezárt kérése – A felhasználó megszakította a Snip-t A felhasználó megszakította a rögzítést az Escape billentyű lenyomásával vagy az eltűnés gombra kattintva. Csak /image és /video esetén alkalmazható.
500 Belső kiszolgálóhiba – A feldolgozás sikertelen Váratlan hiba történt a rögzítés során.

Példaválaszok

Sikeres rögzítés:

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

A felhasználó törölte:

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

Érvénytelen kérelem (hiányzó módparaméter):

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

Teljes URI-példák

Használati eset URI Description
Téglalap képernyőképe ms-screenclip://capture/image?rectangle&user-agent=MyApp&redirect-uri=my-app://response Interaktív téglalaprögzítés. Az eredmény visszaadva a hívónak.
Szabadkézi képernyőkép ms-screenclip://capture/image?freeform&user-agent=MyApp&redirect-uri=my-app://response Interaktív szabadformájú rögzítés. A hívónak visszaadott eredmény.
Ablak képernyőképe ms-screenclip://capture/image?window&user-agent=MyApp&redirect-uri=my-app://response Interaktív ablakrögzítés. A hívónak visszaadott eredmény.
Képernyőfelvétel ms-screenclip://capture/video?user-agent=MyApp&redirect-uri=my-app://response Interaktív képernyőfelvétel. A hívónak visszaküldött eredmény.
Képességek felderítése ms-screenclip://discover?user-agent=MyApp&redirect-uri=my-app://response A lekérdezés által támogatott funkciók. A JSON által visszaadott képességek a hívónak.
A téglalap automatikus mentés funkcióval ms-screenclip://capture/image?rectangle&auto-save&user-agent=MyApp&redirect-uri=my-app://response Téglalap rögzítése automatikus mentéssel engedélyezve.
Téglalap az összes üzemmóddal ms-screenclip://capture/image?rectangle&enabledModes=All&user-agent=MyApp&redirect-uri=my-app://response Téglalap kiválasztása előre kijelölve, az összes mód elérhető a felhasználói felületen.

Indítás az alkalmazásból

A Launcher.LaunchUriAsync használatával indítsa el a Képmetsző eszközt a csomagolt alkalmazásból. Más indítási módszerek (például Process.Start vagy a shell futtatása) nem biztosítják az alkalmazás identitását, és a Snipping Tool nem ad majd választ.

1. lépés: Protokollkezelő regisztrálása

Regisztráljon egyéni protokollt a Package.appxmanifest-ban, hogy az alkalmazás megkaphassa a visszahívási választ. A protokoll nevének meg kell egyeznie a rendszerben használt sémával 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>

A protokollaktiválások regisztrálásával és kezelésével kapcsolatos további részletekért lásd: URI-aktiválás kezelése .

2. lépés: A Képmetsző eszköz elindítása

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

3. lépés: A válasz kezelése

Amikor a rögzítés befejeződött (vagy a felhasználó megszakítja), a Képmetsző eszköz aktiválja az alkalmazást a redirect-uri lekérdezési sztringekként hozzáfűzött eredményparaméterekkel. A legtöbb integráció már fut, amikor a válasz megérkezik – a hívó elindította a Képmetsző eszközt, majd megvárta a visszahívást –, így az alkalmazásnak kezelnie kell a hidegindításos aktiválást (az alkalmazás nem futott) és a meleg újraaktiválást (az alkalmazás már fut). Iratkozzon fel mindkét pathra a App.xaml.cs-ban.

Rögzítési válasz kezelése (kép vagy videó):

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

A felderítő válasz kezelése:

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

Tip

Ha a kéréssel együtt küldött egy x-request-correlation-id üzenetet, ellenőrizze, hogy a válasz ugyanazt az értéket adja-e vissza, így a válasz megfelelhet a megfelelő repülés közbeni kérésnek. Ha hagyja, hogy a Snipping Tool automatikusan generáljon egyet, a válasz hordozza a generált értéket – a legutóbbi repülés közbeni kérésnek megfelelőként kezelje.

Rögzített tartalom lekérdezése a jogkivonat használatával

Használja a SharedStorageAccessManager osztályt a file-access-token rögzített fájl beváltásához és eléréséhez.

Token korlátozások:

  • A tokenek csak egyszer válthatók be. A beváltás után már nem érvényes.
  • A token 14 nap után lejár.
  • Egy alkalmazás legfeljebb 1000 aktív tokennel rendelkezhet. A jogkivonat beváltása, eltávolítása vagy lejárata után már nem számít bele a kvótába.
// 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);

Biztonsági megfontolások

A Képmetsző eszköz az indítás előtt ellenőrzi az összes redirect-uri értéket. A rendszer a következő védelmi műveletet hajtja végre:

  • Packaged alkalmazáshívók: Ha az alkalmazás egy csomagolt Windows alkalmazás (MSIX), az operációs rendszer biztonságosan visszairányítja a rögzítés-választ az alkalmazásához, biztosítva, hogy csak az Ön alkalmazása fogadhatja azt. Ez az ajánlott integrációs útvonal.
  • Bemeneti ellenőrzés: A metszőeszköz elutasítja az UNC elérési utakat, kezdő/záró szóközöket vagy vezérlőkaraktereket tartalmazó átirányítási URI-kat.
  • Nincsenek töredékek: Az URL-töredékeket tartalmazó átirányítási URI-k (például my-app://response#section) elutasításra kerülnek. A Snipping Tool lekérdezési sztringként fűzi hozzá a válaszparamétereket, és egy töredék elnyeli őket.
  • Önhivatkozások elleni védelem: A rendszer letiltja az átirányítási URI-kat, amelyek a Snipping Tool rekurzív aktiválását okozzák.

Important

Alkalmazások hívásához:

  • Regisztráljon egy protokollkezelőt az átirányítási URI-sémához, hogy az alkalmazás megkapja a választ.
  • A feldolgozás előtt ellenőrizze és fertőtlenítse a válaszban kapott összes paramétert.
  • Ellenőrizze, hogy a válasz x-request-correlation-id megfelel-e a repülés közbeni kérésnek, hogy elkerülje az elavult válasz kezelését vagy az egyidejű kérések keveredését. A korrelációs azonosító megakadályozza a keveredéseket; nem hoz létre jogkivonat-eredetet – a biztonságos jogkivonat-útválasztás a csomagolt alkalmazás visszahívási csatornájából származik.