스크린 캡처 도구 시작

이 문서에서는 ms-screenclip: URI(Uniform Resource Identifier) 체계를 사용하여 자사 및 타사 애플리케이션을 Windows 코드 조각 도구와 통합하는 프로토콜을 지정합니다. 프로토콜은 코드 조각 도구를 통해 이미지 및 비디오(오디오 포함)의 캡처를 지원하며 앱 호출자는 앱이 표시할 코드 조각 도구 기능을 선택할 수 있습니다.

지원되는 기능

캡처 도구 프로토콜은 다음 기능을 지원합니다.

• 사각형 캡처
• 자유 형식 캡처
• 창 캡처
• 화면 녹화
• 사용 가능한 캡처 모드 사용자 지정
• 자동 저장(선택 사항)

프로토콜 사양

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

호스트 디바이스 캡처

호스트 capture를 사용하여 스니핑 도구의 캡처 오버레이를 실행합니다.

Path

모드 매개 변수(캡처/이미지)

경로의 /image 경우 정확히 하나의 모드 매개 변수 를 지정해야 합니다. 모드 매개 변수는 값이 없는 베어 쿼리 매개 변수입니다.

쿼리 매개 변수(캡처)

호스트 검색

discover 호스트를 통해 런타임에 스크린 캡처 도구의 지원되는 기능, 모드 및 프로토콜 버전을 쿼리합니다. 이는 캡처 요청을 하기 전에 호환성을 확인하는 데 유용합니다.

쿼리 매개 변수(탐색)

예제 검색

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

응답 형식 검색

응답은 리디렉션 URI에 쿼리 매개 변수로 추가된 JSON 개체입니다 discover . 여기에는 다음이 포함됩니다.

• version: 이 스니핑 도구 빌드가 지원하는 최신 프로토콜 버전입니다.
• defaultVersion: 요청에서 api-version이 생략되면 프로토콜 버전이 가정됩니다. 고정되지 않은 요청이 해석되는 방식을 이해하려면 이 내용을 읽어봅니다.
• supportedVersions: 이 코드 조각 도구 빌드에서 허용하는 프로토콜 버전 배열입니다.
• 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

이 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 Tool은 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를 사용하여 패키지 앱에서 스크린 캡처 도구를 시작해야 합니다. 다른 시작 방법(예: Process.Start 셸 실행)은 앱의 ID를 제공하지 않으며, 코드 조각 도구는 응답을 제공하지 않습니다.

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단계: 응답 처리

캡처가 완료되거나 사용자가 취소하면, 스니핑 도구는 결과 매개 변수가 쿼리 문자열로 추가된 상태로 redirect-uri을 통해 귀하의 앱을 활성화합니다. 응답이 도착할 즈음에 대부분의 통합이 이미 실행 중입니다. 이는 호출자가 캡처 도구를 실행하고 콜백을 기다린 상황을 의미합니다. 그러므로 앱은 콜드 스타트 활성화(앱이 실행되지 않은 상태)와 웜 재활성화(앱이 이미 실행 중인 상태)를 모두 처리할 수 있어야 합니다. 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);

보안 고려 사항

Snipping Tool은 모든 redirect-uri 값을 시작하기 전에 유효성을 검사합니다. 다음과 같은 보호가 적용됩니다.

• 패키징된 앱 호출자: 앱이 패키지된 MSIX(Windows 앱)인 경우 운영 체제는 캡처 응답을 앱으로 안전하게 라우팅하여 앱만 수신할 수 있도록 합니다. 권장 통합 경로입니다.
• 입력 유효성 검사: 코드 조각 도구는 UNC 경로, 선행/후행 공백 또는 컨트롤 문자가 포함된 리디렉션 URI를 거부합니다.
• 조각 없음: URL 조각(예 my-app://response#section: )이 포함된 리디렉션 URI는 거부됩니다. 코드 조각 도구는 응답 매개 변수를 쿼리 문자열로 추가하고 조각은 이를 삼켜줍니다.
• 자체 참조 보호: 스니핑 도구의 재귀 활성화를 유발하는 리디렉션 URI가 차단됩니다.

관련 콘텐츠

• URI 활성화 처리
• SharedStorageAccessManager 클래스
• 캡처 도구를 사용하여 스크린샷 캡처