切り取りツールを起動する

この記事では、ms-screenclip: URI (Uniform Resource Identifier) スキームを使用して、ファースト パーティおよびサード パーティのアプリケーションを Windows Snipping Tool と統合するためのプロトコルを指定します。 このプロトコルは、Snipping Tool を使用した画像とビデオのキャプチャ (オーディオ付き) をサポートしており、アプリの呼び出し元は、アプリで表示する Snipping Tool 機能を選択できます。

サポートされている機能

Snipping Tool プロトコルでは、次の機能がサポートされています。

• 矩形キャプチャー
• フリーフォーム キャプチャ
• ウィンドウ キャプチャ
• 画面の記録
• 使用可能なキャプチャ モードのカスタマイズ
• 自動保存 (省略可能)

プロトコルの仕様

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

ホストのキャプチャ

capture ホストを使用して、Snipping Tool のキャプチャ オーバーレイを起動します。

Path

モード パラメーター (キャプチャ/イメージ)

/image パスには、1 つのモード パラメーターを指定する必要があります。 モード パラメーターは、 値のないベア クエリ パラメーターです。

クエリ パラメーター (キャプチャ)

ホストの検出

discover ホストを使用して、実行時に Snipping Tool でサポートされている機能、モード、プロトコル バージョンに対してクエリを実行します。 これは、キャプチャ要求を行う前に互換性を確認する場合に便利です。

クエリ パラメーター (検出)

発見の例

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

応答形式を検出する

応答は、 discover クエリ パラメーターとしてリダイレクト URI に追加された JSON オブジェクトです。 その構成要素を次に示します。

• version: この Snipping Tool ビルドでサポートされている最新のプロトコル バージョン。
• defaultVersion: 要求が api-versionを省略した場合に想定されるプロトコル バージョン。 これを読んで、ピン留めされていない要求がどのように解釈されるかを理解してください。
• supportedVersions: この Snipping Tool ビルドで受け入れられるプロトコル バージョンの配列。
• capabilities: サポートされているキャプチャ操作の配列。それぞれ次の操作が含まれます。
  • path: キャプチャ エンドポイント (たとえば、 capture/image、 capture/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 パラメーターを使用すると、Snipping Tool 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 Tool は redirect-uriを介して応答をアプリケーションに送信します。 応答は、リダイレクト URI に追加された URI クエリ パラメーターとして構成されます。

redirect-uriにクエリ パラメーター (my-app://response?sessionId=abc など) が既に含まれている場合、それらのパラメーターは保持され、応答パラメーターには&が追加されます。 これを使用すると、コールバックを介して呼び出し元固有の状態をラウンドトリップできます。 sessionId=abc 値は、 code、 reason、 x-request-correlation-id、および (キャプチャを成功させるために) file-access-tokenと共に応答 URI にエコー バックされます。

応答パラメーター

状態コード

応答の例

成功したキャプチャ:

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 やシェルの実行など) はアプリの ID を提供せず、Snipping Tool は応答を提供しません。

手順 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 Tool を起動し、コールバックを待機しました)。そのため、アプリはコールドスタートのアクティブ化 (アプリが実行されていません) とウォーム再アクティブ化 (アプリが既に実行されています) の両方を処理する必要があります。 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を活用し、キャプチャされたファイルにアクセスします。

トークンの制限:

• トークンは 1 回だけ引き換えることができます。 引き換え後は無効になります。
• トークンは 14 日後に期限切れになります。
• アプリに 1,000 個を超えるアクティブ トークンを含めることはできません。 トークンが引き換えられたり、削除されたり、期限切れになったりすると、クォータに対してカウントされなくなります。

// 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 値を起動する前に検証します。 次の保護が適用されます。

• パッケージ化されたアプリの呼び出し元: アプリがパッケージ化されたWindows アプリ (MSIX) である場合、オペレーティング システムはキャプチャ応答をアプリに安全にルーティングし、アプリのみが受信できるようにします。 これは推奨される統合パスです。
• 入力検証: 切り取りツールは、UNC パス、先頭/末尾の空白文字、または制御文字を含むリダイレクト URI を拒否します。
• フラグメントなし: URL フラグメント ( my-app://response#section など) を含むリダイレクト URI は拒否されます。 Snipping Tool は応答パラメーターをクエリ文字列として追加し、フラグメントはそれらを飲み込みます。
• 自己参照保護: Snipping Tool の再帰的なアクティブ化を引き起こすリダイレクト URI はブロックされます。

関連するコンテンツ

• URI のアクティブ化を処理する
• SharedStorageAccessManager クラス
• 切り取りツールを使用してスクリーンショットをキャプチャする