스크린 캡처 도구 시작

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

Important

이 프로토콜에는 패키지된 Windows 앱(MSIX)이 필요합니다. 앱이 패키지되면 운영 체제는 캡처 응답을 앱으로 안전하게 라우팅하는 데 사용하는 Snipping Tool에 앱의 ID를 자동으로 제공합니다. 패키지되지 않은(Win32) 호출자는 redirect-uri를 통해 응답을 받을 수 없습니다. 패키지되지 않은 앱이 제공하는 redirect-uri경우 캡처 도구는 응답을 전달하지 않으며 캡처 UI를 표시하지 않고 종료될 수 있습니다.

메모

이 프로토콜은 이제 사용되지 않는 시작 화면 캡처(사용되지 않음)에 설명된 환경을 대체합니다.

지원되는 기능

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

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

프로토콜 사양

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

구성 요소 Description 가치들
구성표 스니핑 도구에 대한 사용자 지정 스키마 ms-screenclip
Host 수행할 스니핑 도구 작업 capture 또는 discover
Path 캡처할 미디어 형식(호스트에 capture 만 적용되며 호스트에 discover 경로가 없음) /image 또는 /video
Query 작업에 대한 매개 변수 아래 표를 참조하세요.

메모

경로 및 쿼리 매개 변수 이름은 대/소문자를 구분하지 않습니다. 예를 들어, ms-screenclip://capture/Image?Redirect-Uri=my-app://response는 ms-screenclip://capture/image?redirect-uri=my-app://response과 동일하게 작동합니다.

호스트 디바이스 캡처

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

Path

Path Description
/image 이미지 캡처를 시작합니다(스크린샷). 모드 매개 변수가 필요합니다.
/video 비디오 캡처(화면 녹화)를 시작합니다. 항상 사각형 모드를 사용합니다.

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

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

매개 변수 Description
rectangle 대화형 사각형 캡처 모드입니다.
freeform 대화형 자유형 캡처 모드입니다.
window 대화형 창 캡처 모드입니다.

Important

모드 매개 변수는 값 없이 지정해야 합니다. 예를 들어 &rectangle, 사용하지 마세요&rectangle=value. 값을 제공하면 오류 응답이 발생합니다.

의 경우 /image정확히 하나의 모드 매개 변수를 지정해야 합니다. 0개 이상의 모드를 지정하면 오류 응답이 발생합니다 400 Bad Request . 의 경우 /video모든 모드 매개 변수는 무시됩니다.

쿼리 매개 변수(캡처)

메모

쿼리 매개 변수는 순서에 따라 제공될 수 있습니다.

매개 변수 유형 필수 Description Default
redirect-uri URI 예 캡처 도구가 캡처 응답을 보내는 콜백 URI는 다음과 같습니다. 앱은 이 URI 체계에 대한 프로토콜 처리기를 등록해야 합니다. 생략될 경우, 캡처 도구가 캡처 인터페이스를 표시하지 않으며 응답을 반환하지 않습니다. n/a
user-agent string 아니요(강력하게 권장) 로깅 및 분석에 사용되는 호출 애플리케이션의 식별자입니다. 지원 채널을 통해 문제를 진단하는 것이 필요합니다. 자신의 책임 하에 생략해도 됩니다. n/a
api-version string No 사용할 프로토콜 버전(예 "1.2": .) 생략하면 요청이 버전 1.2으로 처리됩니다. 1.2
x-request-correlation-id string No 특정 트랜잭션 또는 이벤트 체인에 대한 참조를 허용하는 요청에 대한 고유 식별자입니다. 자동 생성된 GUID
enabledModes 문자열(리스트) No UI에서 사용할 수 있는 캡처 모드를 제어합니다. 아래 의 EnabledModes를 참조하세요. URI에 지정된 모드만
auto-save 플래그 No 있는 경우 캡처된 스크린샷 또는 녹화가 자동으로 사용자의 디바이스에 저장됩니다. 존재하지 않음(자동 저장 없음)

메모

기본값 api-version1.2 은 최신 프로토콜 버전이 릴리스될 때 변경되지 않습니다. 생략 api-version 하는 요청은 항상 .로 1.2처리됩니다. 이후 버전에서 추가된 기능을 사용하려면 해당 버전으로 설정합니다 api-version . 앱이 암시적 기본값이 아닌 알려진 프로토콜 버전에 연결되도록 모든 요청에서 명시적으로 지정하는 api-version 것이 좋습니다.

메모

api-version를 제공할 때는 반드시 응답 /discover 배열에 있는 값들(supportedVersions, 1.0, 1.1) 중 하나와 정확히 일치해야 합니다. 중간 값 1.15 또는 형식이 잘못된 값 1.0abc을 포함한 다른 모든 값은 400 Bad Request 응답을 반환합니다. 특정 코드 조각 도구 빌드에서 허용하는 버전 집합을 검색하려면 검색 호스트를 호출합니다.

메모

플래그는 auto-save 사용자의 캡처 도구 설정을 존중합니다. 사용자가 Snipping Tool에서 자동 저장을 사용하지 않도록 설정한 경우 요청에 포함 auto-save되는 경우에도 캡처가 디바이스에 저장되지 않습니다.

호스트 검색

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

쿼리 매개 변수(탐색)

매개 변수 유형 필수 Description Default
redirect-uri URI 예 코드 조각 도구가 기능 응답을 보내는 콜백 URI입니다. 앱은 이 URI 체계에 대한 프로토콜 처리기를 등록해야 합니다. 생략하면 Snipping Tool은 응답하지 않습니다. n/a
user-agent string 아니요(강력하게 권장) 로깅 및 분석에 사용되는 호출 애플리케이션의 식별자입니다. n/a
x-request-correlation-id string No 요청에 대한 고유 식별자입니다. 자동 생성된 GUID

예제 검색

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에서 사용할 수 있는 캡처 모드를 제어할 수 있습니다. 애플리케이션의 요구 사항에 맞게 사용자의 선택을 제한하거나 확장하는 데 사용합니다.

지원되는 모드

모드 Description
RectangleSnip 사각형 캡처 모드입니다.
WindowSnip 창 캡처 모드입니다.
FreeformSnip 자유형 캡처 모드입니다.
FullscreenSnip 전체 화면 캡처 모드입니다.
SnippingAllModes 모든 이미지 캡처 모드: RectangleSnip, WindowSnip, FreeformSnipFullscreenSnip.
RectangleRecord 사각형 기록 모드입니다.
RecordAllModes 모든 기록 모드: 현재 RectangleRecord 만.
All 지원되는 모든 모드: SnippingAllModes 및 RecordAllModes의 합집합.

Tip

All, SnippingAllModes및 RecordAllModes 집계 값입니다. 포함된 모드는 Snipping Tool 릴리스에서 변경될 수 있습니다. 이러한 값 중 하나를 사용하는 앱은 이후 릴리스에 추가된 모드를 자동으로 선택합니다. 업데이트에서 사용 가능한 모드 집합을 고정하려면 특정 모드를 명시적으로 나열합니다(예 RectangleSnip,FreeformSnip: ).

Important

  • 의 경우 /image지정된 경우에도 rectangle URI에 모드 매개 변수(예: freeform, , window)가 enabledModes. 모드 매개 변수는 처음에 선택한 모드를 결정합니다.
  • URI에 지정된 모드는 UI에 나열되지 않더라도 항상 UI에서 사용할 수 있습니다 enabledModes. 예를 들어 ?freeform&enabledModes=RectangleSnip 자유형(URI에서) 및 사각형 스니핑을 모두 사용할 수 있으며, 자유형 옵션이 기본적으로 선택되어 있습니다.
  • 생략하면 enabledModes URI에 지정된 모드만 UI에서 사용할 수 있습니다.
  • 에 대해 /image 모드 매개 변수를 지정하지 않으면 요청이 유효하지 않으며 enabledModes에 관계없이 오류가 발생합니다.

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도 포함됩니다.

응답 매개 변수

매개 변수 유형 현재 Description
code 정수 (int) 늘 결과를 나타내는 HTTP 스타일 상태 코드입니다.
reason string 늘 결과에 대한 사람이 읽을 수 있는 설명입니다.
x-request-correlation-id string 늘 원래 요청(또는 자동 생성된 요청)의 상관 관계 ID입니다.
file-access-token string 성공만 이루기 SharedStorageAccessManager 캡처된 미디어를 나타내는 토큰입니다. 파일을 검색하는 데 사용합니다.
discover string 검색만 기능 응답을 포함하는 URL로 인코딩된 JSON입니다.

상태 코드

Code Reason Description
200 성공 캡처가 성공적으로 완료되었습니다. A file-access-token 는 응답에 포함됩니다.
400 잘못된 요청 - 잘못되었거나 누락된 매개 변수 요청을 처리할 수 없습니다. 필요한 모든 매개 변수가 있고 유효한지 확인합니다.
408 요청 시간 제한 - 작업이 너무 오래 걸렸습니다. 작업이 완료되기 전에 제한 시간이 초과되었습니다.
499 클라이언트 닫힘 요청 - 사용자가 스니핑을 취소했습니다. 사용자가 이스케이프를 누르거나 클릭하여 캡처를 취소했습니다. 적용 대상 /image 및 /video 전용입니다.
500 내부 서버 오류 - 처리 실패 캡처하는 동안 예기치 않은 오류가 발생했습니다.

예제 응답

캡처 성공:

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 예제

사용 사례 URI Description
사각형 스크린샷 ms-screenclip://capture/image?rectangle&user-agent=MyApp&redirect-uri=my-app://response 대화형 사각형 캡처. 호출자에게 반환된 결과입니다.
자유형 스크린샷 ms-screenclip://capture/image?freeform&user-agent=MyApp&redirect-uri=my-app://response 대화형 자유형 캡처. 호출자에게 반환된 결과입니다.
창 스크린샷 ms-screenclip://capture/image?window&user-agent=MyApp&redirect-uri=my-app://response 대화형 창 캡처. 호출자에게 반환된 결과입니다.
화면 녹화 ms-screenclip://capture/video?user-agent=MyApp&redirect-uri=my-app://response 대화형 화면 녹화. 호출자에게 반환된 결과입니다.
기능 검색 ms-screenclip://discover?user-agent=MyApp&redirect-uri=my-app://response 지원되는 기능을 쿼리합니다. 호출자에게 반환된 기능 JSON입니다.
자동 저장이 있는 사각형 ms-screenclip://capture/image?rectangle&auto-save&user-agent=MyApp&redirect-uri=my-app://response 자동 저장을 사용하도록 설정된 사각형 캡처
모든 모드가 있는 사각형 ms-screenclip://capture/image?rectangle&enabledModes=All&user-agent=MyApp&redirect-uri=my-app://response 사각형 캡처가 미리 선택되어 있으며, UI에서 사용할 수 있는 모든 모드입니다.

앱에서 시작

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

Tip

요청과 함께 x-request-correlation-id을 보낸 경우, 응답에서 동일한 값이 에코되는지 확인하여 응답이 올바른 진행 중인 요청과 일치하는지 검증하십시오. Snipping Tool에서 자동으로 생성하도록 하면 응답에 생성된 값이 전달됩니다. 이 값은 가장 최근의 기내 요청과 일치하는 것으로 처리됩니다.

토큰을 사용하여 캡처된 미디어 검색

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가 차단됩니다.

Important

애플리케이션 호출의 경우:

  • 앱이 응답을 받을 수 있도록 리디렉션 URI 체계에 대한 프로토콜 처리기를 등록합니다.
  • 응답에서 받은 모든 매개 변수의 유효성을 검사하고 삭제한 후 처리합니다.
  • 부실 응답을 처리하거나 동시 요청을 혼합하지 않도록 응답 x-request-correlation-id 이 기내 요청과 일치하는지 확인합니다. 상관 관계 ID는 혼합을 방지합니다. 토큰 출처를 설정하지 않습니다. 보안 토큰 라우팅은 패키지된 앱 콜백 채널에서 제공됩니다.