启动截图工具

本文规定了将第一方和第三方应用程序与Windows截屏工具集成的协议，使用ms-screenclip： URI（统一资源标识符）方案。 该协议支持通过截图工具捕获图像和视频（含音频），应用调用方可以选择其应用将显示的截图工具功能。

支持的功能

截图工具协议支持以下功能：

• 矩形捕获
• 自由捕获
• 窗口捕获
• 屏幕录制
• 自定义可用的捕获模式
• 自动保存（可选）

协议规范

URI 格式：ms-screenclip://{host}/{path}?{query parameters}

捕获主机

使用 capture 主机启动截图工具的捕获界面。

路径

模式参数 （捕获模式/图像模式）

必须为/image路径准确指定恰好一个模式参数。 模式参数是 没有值的空查询参数。

查询参数（捕获参数）

发现主机

使用 discover 主机在运行时查询 Snipping 工具支持的功能、模式和协议版本。 这对于在发出捕获请求之前检查兼容性非常有用。

查询参数 （发现功能）

发现示例

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

发现响应格式

响应是作为查询参数追加到重定向 URI 的 discover JSON 对象。 该结构包含：

• version：此 Snipping 工具版本支持的最新协议版本。
• defaultVersion：请求省略时假定的 api-version协议版本。 阅读此内容，了解未固定的请求是如何解析的。
• supportedVersions：此截图工具版本接受的协议版本的数组。
• capabilities：支持的捕获操作数组，其中每个操作包括：
  • path：捕获终结点（例如，capture/imagecapture/video）。
  • methods：支持的类似 HTTP 的方法。
  • parameters：终结点的可用参数。
  • description：功能说明。

{
  "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 参数允许你控制在“截图工具”UI 中可用的捕获模式。 使用它来限制或扩展用户的选择，以满足应用程序的要求。

支持的模式

EnabledModes 示例

仅启用矩形截图：

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

启用矩形和窗口截图：

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

启用所有狙击模式：

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

仅启用录制模式：

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

启用多个截图和录制模式：

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

由于在 URI 中指定了自由形式，因此将预先选择它。 用户可以在自由形式截图、矩形截图和矩形录制之间切换。

Responses

用户完成或取消捕获后，Snipping 工具会通过 redirect-uri 将响应发送回您的应用程序。 响应结构为 URI 查询参数附加到您的重定向 URI。

redirect-uri如果已包含查询参数（例如my-app://response?sessionId=abc），则保留这些参数，并追加&响应参数。 可以使用此方法通过回调来往返调用者特定的状态，该值 sessionId=abc 会和 code、reason、x-request-correlation-id 一起在响应 URI 中回显，并且对于成功的捕获还包括 file-access-token。

响应参数

状态代码

示例响应

成功捕获：

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

用户已取消：

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

请求无效（缺少模式参数）：

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

完整 URI 示例

从应用启动

必须使用 Launcher.LaunchUriAsync 从已打包的应用程序启动 Snipping Tool。 其他启动方法（例如 Process.Start 或 shell 执行）不会提供应用的标识，并且 Snipping 工具不会提供响应。

步骤 1：注册协议处理程序

在应用中 Package.appxmanifest 注册自定义协议，以便应用可以接收回调响应。 协议名称必须与在 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>

有关注册和处理协议激活的更多详细信息，请参阅 “处理 URI 激活”。

步骤 2：启动截图工具

// 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：处理响应

捕获完成后（或用户取消），Snipping Tool 会通过你的 redirect-uri，附加查询字符串形式的结果参数来激活应用。 响应到达时，大多数集成都已在运行（调用方启动 Snipping 工具，然后等待回调），因此你的应用必须处理冷启动激活（应用未运行）和热重新激活（应用已运行）。 在 App.xaml.cs 中订阅这两个路径。

处理捕获响应（图像或视频）：

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

处理发现响应：

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

使用令牌检索捕获的媒体

使用 SharedStorageAccessManager 类兑换 file-access-token 并访问捕获的文件。

令牌限制：

• 令牌只能兑换 一次。 兑换后，它不再有效。
• 令牌在 14 天后过期。
• 应用不能超过 1000 个 活动令牌。 令牌兑换、删除或过期后，不再计入配额。

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

安全注意事项

截图工具在启动之前会验证所有 redirect-uri 值。 强制执行以下保护：

• Packaged 应用调用方：当你的应用是打包的 Windows 应用（MSIX）时，操作系统会将捕获的响应安全地路由回你的应用，确保只有你的应用能接收它。 这是建议的集成路径。
• 输入验证：截图工具不接受包含 UNC 路径、前导/尾随空格或控制字符的重定向 URI。
• 无片段：拒绝包含 URL 片段（例如） my-app://response#section的重定向 URI。 狙击工具将响应参数追加为查询字符串，片段会吞下它们。
• 自我引用保护：阻止导致截图工具递归激活的重定向 URI。

相关内容

• 处理 URI 激活
• SharedStorageAccessManager 类
• 使用截图工具来捕捉屏幕画面