Iniciar herramienta de recorte y captura

En este artículo se especifica el protocolo para integrar aplicaciones de primera y de terceros con la herramienta de Windows Snipping mediante el esquema ms-screenclip: URI (identificador uniforme de recursos). El protocolo admite la captura de imágenes y vídeo (con audio) a través del Snipping Tool, y los usuarios de la aplicación pueden elegir qué características del Snipping Tool se mostrarán.

Importante

Este protocolo requiere una aplicación de Windows empaquetada (MSIX). Cuando tu aplicación está paquetizada, el sistema operativo proporciona automáticamente la identidad de tu aplicación a Snipping Tool, que la utiliza para enrutar de forma segura la respuesta de captura de vuelta a tu aplicación. Los llamadores sin empaquetar (Win32) no pueden recibir respuestas a través de redirect-uri. Si una aplicación desempaquetada proporciona un redirect-uri, Snipping Tool no entregará la respuesta y puede cerrar sin mostrar la interfaz de captura.

Nota:

Este protocolo sustituye a la experiencia documentada en Captura de la pantalla de inicio (obsoleta), que ahora está obsoleta.

Características soportadas

El protocolo Snipping Tool admite las siguientes características:

  • Captura de rectángulo
  • Captura de forma libre
  • Captura de ventana
  • Grabación de pantalla
  • Personalización de los modos de captura disponibles
  • Guardado automático (opcional)

Especificación del protocolo

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

Componente Description Valores
Scheme El esquema personalizado para la Herramienta de recorte ms-screenclip
Host La operación de la Herramienta de recorte que se va a realizar capture o discover
Camino Tipo de medio que se va a capturar (solo se aplica al capture host; el discover host no tiene ruta de acceso) /image o /video
Query Parámetros de la operación Consulte las tablas siguientes.

Nota:

Las rutas de acceso y los nombres de parámetro de consulta no distinguen mayúsculas de minúsculas. Por ejemplo, ms-screenclip://capture/Image?Redirect-Uri=my-app://response se comporta igual que ms-screenclip://capture/image?redirect-uri=my-app://response.

Servidor de captura

Utilice el capture host para iniciar la superposición de captura de la Herramienta de recorte.

Camino

Camino Description
/image Inicia la captura de imagen (captura de pantalla). Requiere un parámetro de modo.
/video Inicia la captura de vídeo (grabación de pantalla). Siempre usa el modo rectángulo.

Parámetros del modo (captura/imagen)

Para la /image ruta de acceso, debe especificar exactamente un parámetro de modo. Los parámetros de modo son parámetros de consulta sin ningún valor.

Parámetro Description
rectangle Modo de captura de rectángulo interactivo.
freeform Modo de captura de forma libre interactiva.
window Modo de captura de ventana interactiva.

Importante

Los parámetros de modo deben especificarse sin un valor. Por ejemplo, use &rectangle, no&rectangle=value. Si se proporciona un valor, se producirá una respuesta de error.

Para /image, debe especificar exactamente un parámetro de modo. Si se especifica cero o más de un modo, se producirá una 400 Bad Request respuesta de error. Para /video, se omite cualquier parámetro de modo.

Parámetros de consulta (captura)

Nota:

Los parámetros de consulta se pueden proporcionar en cualquier orden.

Parámetro Tipo Obligatorio Description Predeterminado
redirect-uri URI Sí URI de devolución de llamada donde Snipping Tool envía la respuesta de captura. La aplicación debe registrar un controlador de protocolo para este esquema de URI. Si se omite, Snipping Tool no muestra la interfaz de usuario de captura y no devuelve una respuesta. n/a
user-agent string No (se recomienda encarecidamente) Identificador de la aplicación que llama, que se usa para el registro y el análisis. Necesario para diagnosticar problemas a través de canales de soporte técnico; omita en su propio riesgo. n/a
api-version string No Versión del protocolo que se va a usar, por ejemplo "1.2". Si se omite, la solicitud se procesa como versión 1.2. 1.2
x-request-correlation-id string No Identificador único de la solicitud, lo que permite hacer referencia a una transacción o cadena de eventos determinada. GUID generado automáticamente
enabledModes cadena (lista) No Controla qué modos de captura están disponibles en la interfaz de usuario. Consulte EnabledModes a continuación. Solo el modo especificado en el URI
auto-save flag No Cuando está presente, la captura de pantalla capturada o la grabación se guarda automáticamente en el dispositivo del usuario. No está presente (sin guardar automáticamente)

Nota:

El valor predeterminado api-version de 1.2 no cambia cuando se publican versiones de protocolo más recientes. Las solicitudes que omiten api-version siempre se procesan como 1.2. Para usar las funcionalidades agregadas en una versión posterior, establezca api-version en dicha versión. Se recomienda especificar api-version explícitamente en cada solicitud para que la aplicación permanezca vinculada a una versión de protocolo conocida en lugar del valor predeterminado implícito.

Nota:

Cuando proporcione api-version, debe coincidir exactamente con uno de los valores de la matriz /discover de la respuesta supportedVersions (actualmente 1.0, 1.1, y 1.2). Cualquier otro valor, incluidos los valores intermedios como 1.15 o los valores con formato incorrecto como 1.0abc, devuelve una respuesta 400 Bad Request. Para detectar el conjunto de versiones que acepta una compilación específica de Snipping Tool, llame al host de detección.

Nota:

El indicador auto-save respeta la configuración de la Herramienta de recorte del usuario. Si el usuario ha deshabilitado el guardado automático en Snipping Tool, la captura no se guarda en el dispositivo incluso cuando la solicitud incluye auto-save.

Descubrir host

Use el discover host para consultar las funcionalidades, modos y versión de protocolo admitidos de Snipping Tool en tiempo de ejecución. Esto resulta útil para comprobar la compatibilidad antes de realizar una solicitud de captura.

Parámetros de consulta (detección)

Parámetro Tipo Obligatorio Description Predeterminado
redirect-uri URI Sí URI de devolución de llamada a la que la Herramienta de recorte envía la respuesta de capacidades. La aplicación debe registrar un controlador de protocolo para este esquema de URI. Si se omite, Snipping Tool no devuelve una respuesta. n/a
user-agent string No (se recomienda encarecidamente) Identificador de la aplicación que llama, que se usa para el registro y el análisis. n/a
x-request-correlation-id string No Identificador único de la solicitud. GUID generado automáticamente

Descubrir ejemplo

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

Detección del formato de respuesta

La respuesta es un objeto JSON anexado al URI de redirección como parámetro de discover consulta. Contiene:

  • version: versión más reciente del protocolo que admite esta compilación de Snipping Tool.
  • defaultVersion: versión del protocolo que se supone cuando una solicitud omite api-version. Lee esto para comprender cómo se interpretan tus solicitudes no fijadas.
  • supportedVersions: matriz de versiones de protocolo que acepta esta compilación de Snipping Tool.
  • capabilities: matriz de operaciones de captura admitidas, cada una con:
    • path: el punto de conexión de captura (por ejemplo, capture/image, capture/video).
    • methods: Métodos compatibles similares a HTTP.
    • parameters: parámetros disponibles para el punto de conexión.
    • description: descripción de la funcionalidad.
{
  "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."
    }
  ]
}

ModosActivados

El enabledModes parámetro permite controlar qué modos de captura están disponibles en la interfaz de usuario de la herramienta de recorte. Úselo para restringir o expandir las opciones del usuario para que coincidan con los requisitos de la aplicación.

Modos soportados

Modo Description
RectangleSnip Modo de captura de rectángulo.
WindowSnip Modo de captura de ventana.
FreeformSnip Modo de captura de forma libre.
FullscreenSnip Modo de captura de pantalla completa.
SnippingAllModes Todos los modos de captura de imágenes: RectangleSnip, WindowSnip, FreeformSnip, FullscreenSnip.
RectangleRecord Modo de grabación rectangular.
RecordAllModes Todos los modos de grabación: actualmente solo RectangleRecord.
All Todos los modos admitidos: la unión de SnippingAllModes y RecordAllModes.

Tip

All, SnippingAllModesy RecordAllModes son valores agregados. Los modos que incluyen pueden cambiar en las versiones de Snipping Tool. Una aplicación que usa uno de estos valores selecciona automáticamente los modos agregados en futuras versiones. Para mantener el conjunto de modos disponibles fijos en las actualizaciones, enumere los modos específicos explícitamente (por ejemplo, RectangleSnip,FreeformSnip).

Importante

  • Para /image, se requiere un parámetro de modo (por ejemplo, rectangle, freeform, window) en la URI, incluso cuando se especifica. El parámetro mode determina el modo seleccionado inicialmente.
  • El modo especificado en el URI siempre está disponible en la interfaz de usuario, incluso si no aparece en enabledModes. Por ejemplo, ?freeform&enabledModes=RectangleSnip habilita tanto el recorte de forma libre (desde la URI) como el recorte rectangular, con el de forma libre preseleccionado.
  • Si enabledModes se omite, solo el modo especificado en el URI estará disponible en la interfaz de usuario.
  • Para /image, si no se especifica ningún parámetro de modo, la solicitud no es válida y producirá un error, independientemente de enabledModes.

Ejemplos de EnabledModes

Habilitar solo recorte de rectángulo:

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

Habilitar captura de rectángulo y de ventana:

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

Habilite todos los modos de recorte:

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

Habilitar solo el modo de grabación:

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

Habilite varios modos de recorte y grabación:

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

Puesto que la forma libre se especifica en el URI, se seleccionará previamente. Los usuarios pueden cambiar entre el recorte de forma libre, el recorte rectangular y la grabación de pantalla en modo rectángulo.

Responses

Una vez que el usuario complete o cancele una captura, Snipping Tool devuelve una respuesta a la aplicación a través de redirect-uri. La respuesta se estructura como parámetros de consulta de URI anexados al URI de redirección.

redirect-uri Si ya incluye parámetros de consulta (por ejemplo, my-app://response?sessionId=abc), esos parámetros se conservan y los parámetros de respuesta se anexan con &. Puede utilizar esto para transmitir el estado específico del solicitante a través de la llamada de retorno: el valor sessionId=abc se devuelve en la URI de respuesta junto con code, reason, x-request-correlation-id y (en caso de captura correcta) file-access-token.

Parámetros de respuesta

Parámetro Tipo Presente Description
code int Siempre Código de estado de estilo HTTP que indica el resultado.
reason string Siempre Descripción legible del resultado.
x-request-correlation-id string Siempre Identificador de correlación de la solicitud original (o uno generado automáticamente).
file-access-token string Solo éxito Token SharedStorageAccessManager que representa el medio capturado. Úselo para recuperar el archivo.
discover string Solo descubrir JSON con codificación URL que contiene la respuesta de funcionalidades.

Códigos de estado

Código Reason Description
200 Success La captura se completó correctamente. Se incluye un file-access-token en la respuesta.
400 Solicitud incorrecta: parámetros no válidos o que faltan No se pudo procesar la solicitud. Compruebe que todos los parámetros necesarios están presentes y válidos.
408 Tiempo de espera de la solicitud agotado: la operación tardó demasiado La operación agotó el tiempo de espera antes de completarse.
499 Solicitud cerrada por el cliente: el usuario canceló el recorte El usuario canceló la captura presionando Escape o haciendo clic fuera. Se aplica solo a /image y /video .
500 Error interno del servidor: error de procesamiento Error inesperado durante la captura.

Respuestas de ejemplo

Captura correcta:

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

Usuario cancelado:

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

Solicitud no válida (parámetro de modo que falta):

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

Ejemplos de URI completos

Caso de uso URI Description
Captura de pantalla rectangular ms-screenclip://capture/image?rectangle&user-agent=MyApp&redirect-uri=my-app://response Captura interactiva del rectángulo. Resultado devuelto al autor de la llamada.
Captura de pantalla de forma libre ms-screenclip://capture/image?freeform&user-agent=MyApp&redirect-uri=my-app://response Captura interactiva de forma libre. Resultado devuelto al autor de la llamada.
Captura de pantalla de la ventana ms-screenclip://capture/image?window&user-agent=MyApp&redirect-uri=my-app://response Captura de ventana interactiva. Resultado devuelto al autor de la llamada.
Grabación de pantalla ms-screenclip://capture/video?user-agent=MyApp&redirect-uri=my-app://response Grabación de pantalla interactiva. Resultado devuelto al autor de la llamada.
Descubrir capacidades ms-screenclip://discover?user-agent=MyApp&redirect-uri=my-app://response Consultar características compatibles. Funcionalidades JSON devueltas al autor de la llamada.
Rectángulo con guardado automático ms-screenclip://capture/image?rectangle&auto-save&user-agent=MyApp&redirect-uri=my-app://response Captura de rectángulo con guardado automático activado.
Rectángulo con todos los modos ms-screenclip://capture/image?rectangle&enabledModes=All&user-agent=MyApp&redirect-uri=my-app://response Captura de rectángulo seleccionada previamente, todos los modos disponibles en la interfaz de usuario.

Inicio desde la aplicación

Debes usar Launcher.LaunchUriAsync para iniciar Snipping Tool desde la aplicación empaquetada. Otros métodos de inicio (como Process.Start o la ejecución del shell) no proporcionarán la identidad de la aplicación y Snipping Tool no entregará la respuesta.

Paso 1: Registrar un controlador de protocolo

Registra un protocolo personalizado en tu Package.appxmanifest para que tu aplicación pueda recibir la respuesta de devolución de llamada. El nombre del protocolo debe coincidir con el esquema usado en 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>

Consulte Controlar la activación de URI para obtener más información sobre el registro y el control de las activaciones de protocolo.

Paso 2: Iniciar la herramienta de recorte

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

Paso 3: Control de la respuesta

Cuando finaliza la captura (o el usuario la cancela), la Herramienta de recorte activa tu aplicación a través de tu redirect-uri con los parámetros del resultado añadidos como cadenas de consulta. La mayoría de las integraciones ya se están ejecutando cuando llega la respuesta —el usuario que realizó la llamada inició la Herramienta de recorte y, a continuación, esperó a la llamada de retorno—, por lo que tu aplicación debe administrar tanto la activación en frío (la aplicación no se estaba ejecutando) como la reactivación en caliente (la aplicación ya se está ejecutando). Suscríbase a ambas rutas en App.xaml.cs.

Controlar una respuesta de captura (imagen o vídeo):

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

Controle una respuesta de detecció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
    }
}

Tip

Si enviaste un x-request-correlation-id con la solicitud, comprueba que la respuesta refleje el mismo valor para que puedas asociar la respuesta a la solicitud en curso correcta. Si deja que la Herramienta de recorte genere uno automáticamente, la respuesta incluirá el valor generado; considérelo como correspondiente a su solicitud en curso más reciente.

Recuperación de medios capturados mediante el token

Utilice la clase SharedStorageAccessManager para canjear el file-access-token y acceder al archivo capturado.

Restricciones de token:

  • Un token solo se puede canjear una vez. Después del canje, ya no es válido.
  • Un token expira después de 14 días.
  • Una aplicación no puede tener más de 1000 tokens activos. Después de canjear, quitar o expirar un token, ya no cuenta con la cuota.
// 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);

Consideraciones de seguridad

Snipping Tool valida todos los redirect-uri valores antes de iniciarlos. Se aplican las siguientes protecciones:

  • Llamadas de aplicaciones empaquetadas: cuando la aplicación es una aplicación de Windows empaquetada (MSIX), el sistema operativo enruta de forma segura la respuesta de captura a la aplicación, lo que garantiza que solo la aplicación pueda recibirla. Esta es la ruta de integración recomendada.
  • Validación de entrada: Snipping Tool rechaza los URI de redirección que contienen rutas de acceso UNC, espacios en blanco iniciales o finales, o caracteres de control.
  • Sin fragmentos: se rechazan los URI de redirección que contienen un fragmento de dirección URL (por ejemplo, my-app://response#section). La Herramienta de recorte añade los parámetros de respuesta como una cadena de consulta, y un fragmento los omitiría.
  • Protección de referencia automática: se bloquean los URI de redirección que provocarían la activación recursiva de la herramienta de recorte.

Importante

Para llamar a aplicaciones:

  • Registre un controlador de protocolo para el esquema de URI de redirección para que la aplicación pueda recibir la respuesta.
  • Valide y sane todos los parámetros recibidos en la respuesta antes de procesarlos.
  • Compruebe que el x-request-correlation-id de la respuesta coincida con su solicitud en curso para evitar administrar una respuesta obsoleta o confundir solicitudes simultáneas. El ID de correlación evita confusiones; no establece la procedencia del token: el enrutamiento seguro de los tokens proviene del canal de devolución de llamada de la aplicación empaquetada.

Contenido relacionado

  • Last updated on