Avvia lo strumento di ritaglio

Questo articolo specifica il protocollo per l'integrazione di applicazioni di prima e di terze parti con lo strumento di spostamento di Windows tramite lo schema ms-screenclip: URI (Uniform Resource Identifier). Il protocollo supporta l'acquisizione di immagini e video (con audio) tramite lo strumento di ritaglio e i chiamanti dell'app possono scegliere quali funzionalità dello strumento di ritaglio verranno visualizzate dall'app.

Importante

Questo protocollo richiede un'app Windows confezionata (MSIX). Quando l'app viene inserita in un pacchetto, il sistema operativo fornisce automaticamente l'identità dell'app allo strumento di ritaglio, che lo usa per instradare in modo sicuro la risposta di acquisizione all'app. I chiamanti non impacchettati (Win32) non possono ricevere risposte tramite redirect-uri. Se un'app non impacchettata fornisce redirect-uri, lo Strumento di cattura non fornirà la risposta e potrebbe chiudersi senza visualizzare l'interfaccia utente di acquisizione.

Note

Questo protocollo sostituisce l'esperienza documentata nello snipping della schermata di avvio (deprecato) che è ora deprecata.

Funzionalità supportate

Il protocollo Snipping Tool supporta le funzionalità seguenti:

  • Cattura del rettangolo
  • Acquisizione a mano libera
  • Acquisizione di finestre
  • Registrazione dello schermo
  • Personalizzazione delle modalità di acquisizione disponibili
  • Salvataggio automatico (facoltativo)

Specifica del protocollo

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

Componente Descrzione Valori
Schema Schema personalizzato per Snipping Tool ms-screenclip
Host Operazione di snipping tool da eseguire capture oppure discover
Percorso Tipo di supporto multimediale da acquisire (si applica solo all'host capture; l'host discover non ha alcun percorso) /image oppure /video
query Parametri per l'operazione Vedere le tabelle seguenti

Note

I percorsi e i nomi dei parametri di query non fanno distinzione tra maiuscole e minuscole. Ad esempio, ms-screenclip://capture/Image?Redirect-Uri=my-app://response si comporta come ms-screenclip://capture/image?redirect-uri=my-app://response.

Host di acquisizione

Usare l'host capture per avviare l'interfaccia di acquisizione di Snipping Tool.

Path

Path Descrzione
/image Avvia l'acquisizione di immagini (screenshot). Richiede un parametro modalità.
/video Avvia l'acquisizione video (registrazione dello schermo). Usa sempre la modalità rettangolo.

Parametri della modalità (cattura/immagine)

Per il /image percorso, è necessario specificare esattamente un parametro di modalità. I parametri mode sono parametri di query bare senza valore.

Parametro Descrzione
rectangle Modalità di acquisizione del rettangolo interattivo.
freeform Modalità di cattura interattiva libera.
window Modalità di acquisizione della finestra interattiva.

Importante

I parametri mode devono essere specificati senza un valore. Ad esempio, usare &rectangle, non&rectangle=value . Se si specifica un valore, verrà restituita una risposta di errore.

Per /image, è necessario specificare esattamente un parametro di modalità. Se si specifica zero o più modalità, verrà restituita una 400 Bad Request risposta di errore. Per /video, qualsiasi parametro di modalità viene ignorato.

Parametri di query (acquisizione)

Note

I parametri di query possono essere forniti in qualsiasi ordine.

Parametro Tipo Obbligatorio Descrzione Default
redirect-uri URI Sì URI di callback in cui lo strumento di intercettazione invia la risposta di acquisizione. L'app deve registrare un gestore di protocollo per questo schema URI. Se omesso, Snipping Tool non visualizza l'interfaccia utente di acquisizione e non restituisce una risposta. non disponibile
user-agent string No (fortemente consigliato) Identificatore per l'applicazione chiamante, usata per la registrazione e l'analisi. Necessario per diagnosticare i problemi tramite canali di supporto; omettere a proprio rischio. non disponibile
api-version string No Versione del protocollo da usare, ad esempio "1.2". Se omesso, la richiesta viene elaborata come versione 1.2. 1.2
x-request-correlation-id string No Identificatore univoco per la richiesta, consentendo il riferimento a una determinata transazione o catena di eventi. GUID generato automaticamente
enabledModes string (list) No Controlla le modalità di acquisizione disponibili nell'interfaccia utente. Vedere EnabledModes di seguito. Solo la modalità specificata nell'URI
auto-save flag No Quando presente, lo screenshot o la registrazione acquisiti vengono salvati automaticamente nel dispositivo dell'utente. Non presente (nessun salvataggio automatico)

Note

Il valore predefinito api-version di 1.2 non cambia quando vengono rilasciate versioni più recenti del protocollo. Le richieste che omettono api-version vengono sempre elaborate come 1.2. Per usare le funzionalità aggiunte in una versione successiva, impostare api-version su tale versione. È consigliabile specificare api-version in modo esplicito in ogni richiesta in modo che l'app rimanga associata a una versione del protocollo nota anziché all'impostazione predefinita implicita.

Note

Quando si specifica api-version, deve corrispondere esattamente a uno dei valori nella /discover matrice della supportedVersions risposta (attualmente 1.0, 1.1e 1.2). Qualsiasi altro valore — inclusi valori intermedi come 1.15 o valori malformati come 1.0abc — restituisce una risposta 400 Bad Request. Per individuare il set di versioni accettate da una compilazione specifica dello strumento di ritaglio, chiamare l'host di individuazione.

Note

Il auto-save flag rispetta le impostazioni dello strumento di ritaglio dell'utente. Se l'utente ha disabilitato il salvataggio automatico nello strumento di ritaglio, l'acquisizione non viene salvata nel dispositivo anche quando la richiesta include auto-save.

Individuare l'host

Usare l'host discover per eseguire query sulle funzionalità, le modalità e la versione del protocollo supportate dallo strumento di intercettazione in fase di esecuzione. Ciò è utile per verificare la compatibilità prima di effettuare una richiesta di acquisizione.

Parametri di query (scoperta)

Parametro Tipo Obbligatorio Descrzione Default
redirect-uri URI Sì URI di callback in cui lo strumento di intercettazione invia la risposta alle funzionalità. L'app deve registrare un gestore di protocollo per questo schema URI. Se omesso, Snipping Tool non restituisce una risposta. non disponibile
user-agent string No (fortemente consigliato) Identificatore per l'applicazione chiamante, usata per la registrazione e l'analisi. non disponibile
x-request-correlation-id string No Identificatore univoco per la richiesta. GUID generato automaticamente

Esempio di scoperta

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

Individuare il formato della risposta

La risposta è un oggetto JSON aggiunto all'URI di reindirizzamento come parametro di discover query. Contiene:

  • version: versione più recente del protocollo supportata da questa build dello strumento di ritaglio.
  • defaultVersion: versione del protocollo presunta quando una richiesta omette api-version. Leggi questo per comprendere come vengono interpretate le richieste non fissate.
  • supportedVersions: matrice di versioni del protocollo accettate da questa compilazione dello strumento di ritaglio.
  • capabilities: matrice di operazioni di acquisizione supportate, ognuna con:
    • path: endpoint di acquisizione (ad esempio, capture/image, capture/video).
    • methods: metodi simili a HTTP supportati.
    • parameters: parametri disponibili per l'endpoint.
    • description: Descrizione della funzionalità.
{
  "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."
    }
  ]
}

Modalità Abilitate

Il enabledModes parametro consente di controllare le modalità di acquisizione disponibili nell'interfaccia utente dello strumento di ritaglio. Usarlo per limitare o espandere le scelte dell'utente in base ai requisiti dell'applicazione.

Modalità supportate

Mode Descrzione
RectangleSnip Modalità di acquisizione rettangolare.
WindowSnip Modalità di acquisizione della finestra.
FreeformSnip Modalità acquisizione libera.
FullscreenSnip Modalità di acquisizione a schermo intero.
SnippingAllModes Tutte le modalità di acquisizione di immagini: RectangleSnip, WindowSnip, FreeformSnip, FullscreenSnip.
RectangleRecord Modalità di registrazione a rettangolo.
RecordAllModes Tutte le modalità di registrazione: attualmente solo RectangleRecord.
All Tutte le modalità supportate: unione di SnippingAllModes e RecordAllModes.

Tip

All, SnippingAllModese RecordAllModes sono valori aggregati. Le modalità che sono inclusi possono cambiare nelle versioni di Snipping Tool. Un'app che usa uno di questi valori seleziona automaticamente le modalità aggiunte nelle versioni future. Per mantenere fisso il set di modalità disponibili tra gli aggiornamenti, elencare in modo esplicito le modalità specifiche , ad esempio RectangleSnip,FreeformSnip.

Importante

  • Per /image, un parametro mode (ad esempio , rectanglefreeform, , window) è obbligatorio nell'URI, anche quando enabledModes viene specificato. Il parametro mode determina la modalità inizialmente selezionata.
  • La modalità specificata nell'URI è sempre disponibile nell'interfaccia utente, anche se non è elencata in enabledModes. Ad esempio, ?freeform&enabledModes=RectangleSnip rende disponibili sia il ritaglio a forma libera (dall'URI) che il ritaglio del rettangolo, con il ritaglio a forma libera pre-selezionato.
  • Se enabledModes viene omesso, nell'interfaccia utente sarà disponibile solo la modalità specificata nell'URI.
  • Per /image, se non viene specificato alcun parametro mode, la richiesta non è valida e genererà un errore, indipendentemente da enabledModes.

Esempi di modalità abilitate

Abilita solo il ritaglio rettangolare:

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

Abilitare il ritaglio rettangolare e della finestra:

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

Abilitare tutte le modalità di ritaglio:

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

Abilita solo la modalità di registrazione:

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

Abilitare più modalità di registrazione e di intercettazione:

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

Poiché "freeform" è specificato nell'URI, verrà pre-selezionato. Gli utenti possono passare dal ritaglio libero, al ritaglio rettangolare e alla registrazione rettangolare.

Responses

Al termine o all'annullamento di un'acquisizione, Snipping Tool invia una risposta all'applicazione tramite redirect-uri. La risposta è strutturata come parametri di query URI aggiunti all'URI di reindirizzamento.

Se l'oggetto redirect-uri include già parametri di query (ad esempio, my-app://response?sessionId=abc), tali parametri vengono mantenuti e i parametri di risposta vengono aggiunti con &. È possibile utilizzarlo per gestire il passaggio di stato specifico del chiamante tramite il callback. Il valore sessionId=abc viene restituito nell'URI della risposta insieme a code, reason, x-request-correlation-id, e file-access-token (in caso di acquisizione riuscita).

Parametri di risposta

Parametro Tipo Presente Descrzione
code int Sempre Codice di stato in stile HTTP che indica il risultato.
reason string Sempre Descrizione leggibile del risultato.
x-request-correlation-id string Sempre ID di correlazione della richiesta originale (o uno generato automaticamente).
file-access-token string Solo successo Un token SharedStorageAccessManager che rappresenta i media acquisiti. Utilizzare questa opzione per recuperare il file.
discover string Scopri solo JSON con codifica URL contenente la risposta alle funzionalità.

Codici di stato

Codice Motivo Descrzione
200 Operazione completata L'acquisizione è stata completata correttamente. Un file-access-token elemento è incluso nella risposta.
400 Richiesta non valida- Parametri non validi o mancanti Impossibile elaborare la richiesta. Verificare che tutti i parametri obbligatori siano presenti e validi.
408 Timeout della richiesta - L'operazione ha richiesto troppo tempo L'operazione è scaduta prima del completamento.
499 Richiesta chiusa dal sistema client - L'utente ha annullato lo Snip L'utente ha annullato l'acquisizione premendo Escape o facendo clic via. Si applica solo a /image e /video .
500 Errore interno del server - Elaborazione non riuscita Si è verificato un errore imprevisto durante l'acquisizione.

Risposte di esempio

Acquisizione riuscita:

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

L'utente ha annullato:

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

Richiesta non valida (parametro modalità mancante):

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

Esempi di URI completi

Caso d'uso URI Descrzione
Screenshot rettangolare ms-screenclip://capture/image?rectangle&user-agent=MyApp&redirect-uri=my-app://response Cattura interattiva del rettangolo. Risultato restituito al chiamante.
Screenshot della figura a mano libera ms-screenclip://capture/image?freeform&user-agent=MyApp&redirect-uri=my-app://response Acquisizione interattiva a mano libera. Risultato restituito al chiamante.
Screenshot della finestra ms-screenclip://capture/image?window&user-agent=MyApp&redirect-uri=my-app://response Acquisizione di finestre interattive. Risultato restituito al chiamante.
Registrazione dello schermo ms-screenclip://capture/video?user-agent=MyApp&redirect-uri=my-app://response Registrazione interattiva dello schermo. Risultato restituito al chiamante.
Scoprire capacità ms-screenclip://discover?user-agent=MyApp&redirect-uri=my-app://response Funzionalità supportate dalle query. Funzionalità JSON restituite al chiamante.
Rettangolo con salvataggio automatico ms-screenclip://capture/image?rectangle&auto-save&user-agent=MyApp&redirect-uri=my-app://response Acquisizione di rettangoli con salvataggio automatico abilitato.
Rettangolo con tutte le modalità ms-screenclip://capture/image?rectangle&enabledModes=All&user-agent=MyApp&redirect-uri=my-app://response Acquisizione rettangolo pre-selezionata, tutte le modalità disponibili nell'interfaccia utente.

Avvio dall'app

Devi usare Launcher.LaunchUriAsync per avviare lo strumento di ritaglio dall'app in pacchetto. Altri metodi di avvio (ad esempio Process.Start o l'esecuzione della shell) non forniranno l'identità dell'app e lo strumento di cattura non fornirà la risposta.

Passaggio 1: Registrare un gestore di protocollo

Registrare un protocollo personalizzato in Package.appxmanifest affinché l'app possa ricevere la risposta di callback. Il nome del protocollo deve corrispondere allo schema usato nell'oggetto 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>

Per altre informazioni sulla registrazione e sulla gestione delle attivazioni dei protocolli, vedere Gestire l'attivazione dell'URI .

Passaggio 2: Avviare lo strumento di ritaglio

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

Passaggio 3: Gestire la risposta

Al termine dell'acquisizione (o l'utente annulla), lo Strumento di cattura attiva l'app tramite i redirect-uri con i parametri di risultato aggiunti come stringhe di query. La maggior parte delle integrazioni è già in esecuzione quando arriva la risposta — il chiamante ha avviato Snipping Tool, poi ha aspettato il callback — dunque l'app deve gestire sia l'attivazione a freddo (l'app non è in esecuzione) sia la riattivazione a caldo (l'app è già in esecuzione). Iscriviti a entrambi i percorsi in App.xaml.cs.

Gestire una risposta di acquisizione (immagine o 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}");
    }
}

Gestire una risposta di individuazione:

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

Se hai inviato un x-request-correlation-id con la richiesta, verifica che la risposta riporti lo stesso valore in modo da poter associare correttamente la risposta alla richiesta attualmente in corso. Se permetti allo Strumento di cattura di generarne uno automaticamente, la risposta contiene il valore generato — consideralo come corrispondente alla tua richiesta più recente in corso.

Recupero di supporti acquisiti tramite il token

Usare la classe SharedStorageAccessManager per riscattare e file-access-token accedere al file acquisito.

Restrizioni dei token:

  • Un token può essere riscattato una sola volta. Dopo il riscatto, non è più valido.
  • Un token scade dopo 14 giorni.
  • Un'app non può avere più di 1000 token attivi. Dopo che un token viene riscattato, rimosso o scaduto, non viene più conteggiato rispetto alla quota.
// 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);

Considerazioni relative alla sicurezza

Lo strumento di ritaglio convalida tutti i redirect-uri valori prima di avviarli. Vengono applicate le protezioni seguenti:

  • Chiamanti che utilizzano app confezionate: quando la tua app è un'app Windows confezionata (MSIX), il sistema operativo instrada in modo sicuro la risposta di acquisizione alla tua app, assicurando che solo la tua app possa riceverla. Questo è il percorso di integrazione consigliato.
  • Convalida dell'input: lo strumento di ritaglio rifiuta gli URI di reindirizzamento che contengono percorsi UNC, spazi vuoti iniziali/finali o caratteri di controllo.
  • Nessun frammento: gli URI di reindirizzamento che contengono un frammento di URL (ad esempio, my-app://response#section) vengono rifiutati. Lo strumento di ritaglio aggiunge i parametri di risposta come stringa di query e un frammento li ingoierebbe.
  • Protezione self-referencing: gli URI di reindirizzamento che causano l'attivazione ricorsiva dello strumento di ritaglio vengono bloccati.

Importante

Per le chiamate alle applicazioni:

  • Registrare un gestore di protocollo per lo schema URI di reindirizzamento in modo che l'app possa ricevere la risposta.
  • Convalidare e purificare tutti i parametri ricevuti nella risposta prima di elaborarli.
  • Verificare che il tag x-request-correlation-id della risposta corrisponda alla vostra richiesta in corso per evitare di gestire una risposta obsoleta o di confondere richieste simultanee. Correlation-id impedisce confusioni; non stabilisce la provenienza dei token — il routing sicuro dei token proviene dal canale di callback dell'applicazione confezionata.

Contenuti correlati

  • Last updated on