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 reemplaza la experiencia documentada en Iniciar recorte de pantalla (en desuso), que ahora está en desuso.

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 creación de particiones ms-screenclip
Host Operación de la herramienta de recortes 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

Utiliza el capture host para iniciar la superposición de captura de Snipping Tool.

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 supportedVersions de la respuesta /discover (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:

La auto-save marca respeta la configuración de la herramienta de snipping 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.

Detección del 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 donde Snipping Tool envía la respuesta de las funcionalidades. 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. Lea esto para comprender cómo se interpretan las 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 RectangleRecord solo.
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, freeform, window, ) en la URI, incluso cuando enabledModes 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 hace que tanto los recortes de forma libre (desde el URI) como los recortes de rectángulo estén disponibles, siendo la forma libre la opción preseleccionada.
  • 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 usar esto para pasar de ida y vuelta el estado específico del interlocutor a través de la devolución de llamada: el valor sessionId=abc se devuelve en el URI de respuesta junto con code, reason, x-request-correlation-id y file-access-token (para una captura exitosa).

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: la operación tardó demasiado tiempo El tiempo de espera de la operación se agotó antes de completarse.
499 Solicitud cerrada del cliente: el usuario canceló el Snip 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 Package.appxmanifest para que tu aplicación reciba la respuesta de callback. 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 se completa la captura (o el usuario la cancela), la herramienta Recortes activa tu aplicación a través de tu redirect-uri, con los parámetros de resultados añadidos como cadenas de consulta. La mayoría de las integraciones ya se están ejecutando cuando llega la respuesta — el llamador inició la Herramienta Recortes y luego esperó a la devolución de llamada — por lo que la aplicación debe controlar tanto la activación de arranque en frío (la aplicación no se estaba ejecutando) como la activació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 envió un x-request-correlation-id con la solicitud, compruebe que la respuesta devuelve el mismo valor para que pueda coincidir con la respuesta a la solicitud en curso correcta. Si deja que la herramienta Snipping Tool genere automáticamente uno, la respuesta contiene el valor generado; considérelo como una coincidencia con 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). Snipping Tool anexa los parámetros de respuesta como una cadena de consulta y un fragmento los tragarí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 la respuesta de x-request-correlation-id coincide con su solicitud en proceso para evitar manejar 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 tokens procede del canal de devolución de llamada de la aplicación empaquetada.

Contenido relacionado

  • Last updated on