Windows에서 앱 작업에 대한 URI 시작 구현

이 문서에서는 앱 작업을 만드는 단계를 설명하고 앱 작업 공급자 앱의 구성 요소를 설명합니다. 앱 동작은 Windows 앱이 구현하고 등록할 수 있는 개별 동작 단위이므로 다른 앱 및 환경에서 액세스하여 사용자 워크플로에 원활하게 통합할 수 있습니다. Windows의 앱 작업에 대한 자세한 내용은 Windows의 앱 작업 개요를 참조하세요.

COM 활성화 또는 URI 시작 활성화를 사용하도록 작업 공급자 앱을 구현할 수 있습니다. URI 시작 작업은 컨텍스트에서 UI를 표시하거나 텍스트 결과를 스트리밍하는 것과 같은 일부 고급 작업 기능을 지원하지 않지만 구현은 매우 간단하며 단일 요청 및 응답으로만 구성된 작업에 가장 적합할 수 있습니다.

COM 활성화를 사용하는 공급자 앱은 IActionProvider 인터페이스를 구현하여 작업 호출을 처리합니다. 이 방법을 사용하면 스트리밍 텍스트 지원과 같은 고급 작업 기능을 사용할 수 있지만 Windows 앱 작업 VSIX 확장을 사용하는 것보다 더 많은 코드가 필요합니다. 앱 공급자에서 COM 정품 인증을 사용하는 방법에 대한 자세한 내용은 Windows에서 앱 작업 시작을 참조하세요.

winget configure https://raw.githubusercontent.com/microsoft/winget-dsc/refs/heads/main/samples/Configuration%20files/Learn%20tutorials/Windows%20AI/app_actions_cs.winget

winget configure https://raw.githubusercontent.com/microsoft/winget-dsc/refs/heads/main/samples/Configuration%20files/Learn%20tutorials/Windows%20AI/app_actions_cpp.winget

Visual Studio에서 새 Windows 앱 프로젝트 만들기

앱 작업 기능은 여러 앱 프레임워크 및 언어에 대해 지원되지만 앱은 시스템에 등록할 수 있도록 패키지 ID가 있어야 합니다. 이 연습에서는 패키지된 C# WinUI 3 데스크톱 앱에서 Windows 앱 작업 공급자를 구현합니다.

1. Visual Studio에서 새 프로젝트를 만듭니다.

2. 새 프로젝트 만들기 대화 상자에서 언어 필터를 "C#"으로 설정하고 플랫폼 필터를 "WinUI"로 설정한 다음, "WinUI 빈 앱(패키지됨)" 프로젝트 템플릿을 선택합니다.

3. 새 프로젝트의 이름을 "ExampleAppActionProvider"로 지정합니다.

4. 프로젝트가 로드되면 솔루션 탐색기 에서 프로젝트 이름을 마우스 오른쪽 단추로 클릭하고 속성을 선택합니다. 일반 페이지에서 대상 OS까지 아래로 스크롤하고 "Windows"를 선택합니다. 대상 OS 버전 및 지원되는 OS 버전의 경우에는 버전 10.0.26100.0 이상을 선택하십시오.

5. 작업 공급자 API를 지원하도록 프로젝트를 업데이트하려면 솔루션 탐색기 에서 프로젝트 이름을 마우스 오른쪽 단추로 클릭하고 프로젝트 파일 편집을 선택합니다. PropertyGroup 내에서 다음 WindowsSdkPackageVersion 요소를 추가합니다.

   <WindowsSdkPackageVersion>10.0.26100.75</WindowsSdkPackageVersion>
   

Microsoft.AI.Actions nuget 패키지에 대한 참조 추가

Microsoft.AI.Actions nuget 패키지를 사용하면 앱 작업 런타임을 초기화할 수 있으며, 앱 작업에서 입력으로 전달되고 출력되는 엔터티 개체를 만들기 위한 API를 제공합니다.

1. 솔루션 탐색기에서 프로젝트 이름을 마우스 오른쪽 단추로 클릭하고 NuGet 패키지 관리를 선택합니다.
2. 찾아보기 탭에 있는지 확인하고 Microsoft.AI.Actions를 검색합니다.
3. Microsoft.AI.Actions를 선택하고 설치를 클릭합니다.

작업 정의 JSON 파일 추가

작업 공급자 앱은 앱이 구현하는 작업을 정의하는 작업 정의 파일을 제공해야 합니다. 이 파일은 각 작업에 대한 고유 식별자 및 설명과 같은 정보와 각 작업이 지원하는 입력 및 출력의 이름과 유형을 제공합니다. 앱 작업 JSON 파일 형식에 대한 자세한 내용은 Windows 앱 작업 공급자에 대한 작업 정의 JSON 스키마를 참조하세요.

이 예제에서는 단일 텍스트 엔터티를 입력으로 사용하고 단일 TextEntity를 출력으로 반환하는 SendMessage라는 작업을 정의합니다. JSON 파일은 작업을 정의하는 것 외에도 COM 활성화를 사용하여 또는 URI 시작을 통해 작업 공급자 앱을 시작할지 여부를 지정합니다. 이 예제에서는 URI 활성화를 사용합니다. URI 체계 urilaunchaction-protocol는 이 안내서의 이후 단계에서 등록될 것입니다.

1. 솔루션 탐색기에서 폴더를 마우스 오른쪽 단추로 Assets 클릭하고 새 항목 추가...를> 선택합니다.
2. 새 항목 추가 대화 상자에서 텍스트 파일을 선택합니다. 새 파일의 이름을 "registration.json"로 지정하고 확인을 클릭합니다.
3. 솔루션 탐색기에서 registration.json 파일을 마우스 오른쪽 단추로 클릭하고 속성을 선택합니다. 속성 창에서 빌드 작업을 "콘텐츠"로 설정하고 출력 디렉터리로 복사를 "최신인 경우 복사"로 설정합니다.
4. registration.json 파일에 다음 JSON 작업 정의를 추가합니다.

{
  "version": 3,
  "actions": [
    {
      "id": "ExampleActionProvider.SendMessage",
      "description": "Send a message (URI Launch)",
      "icon": "ms-resource://Files/Assets/LockScreenLogo.png",
      "usesGenerativeAI": false,
      "allowedAppInvokers": ["*"],
      "inputs": [
        {
          "name": "message",
          "kind": "Text"
        }
      ],
      "inputCombinations": [
        {
          "inputs": [
            "message"
          ],
          "description": "Send message '${message.Text}'"
        }
      ],
      "outputs": [
        {
          "name": "response",
          "kind": "Text"
        }
      ],
      "invocation": {
        "type": "Uri",
        "uri": "urilaunchaction-protocol://",
        "inputData": {
          "message": "${message.Text}"
        }
      }
    }
  ]
}

앱 패키지 매니페스트 파일 업데이트

Package.appmanifest 파일은 앱에 대한 MSIX 패키지의 세부 정보를 제공합니다. 시스템에서 Windows 앱 작업 공급자로 등록하려면 범주가 "windows.appExtension"으로 설정된uap3:Extension 요소를 앱에 포함해야 합니다. 이 요소는 앱의 작업을 정의하는 앱 작업 JSON 파일의 위치를 지정하는 데 사용됩니다. 작업 공급자 앱 패키지 매니페스트 형식에 대한 자세한 내용은 Windows 패키지 매니페스트 XML 형식의 App Actions를 참조하세요.

앱 작업 공급자가 URI를 통해 시작되려면 프로토콜을 시스템에 등록해야 합니다. 이 등록은 앱 패키지 매니페스트에 com2:Extension 요소를 제공하여 수행됩니다. Protocol 요소의 Name 특성은 작업 정의 JSON 파일에 지정된 invocation.uri 값과 일치해야 합니다. 이 예에서는 다음과 같습니다urilaunchaction-protocol. URI 시작 활성화에 대한 자세한 내용은 결과를 보려면 앱 시작을 참조하세요.

1. Package.appxmanifest 파일을 마우스 오른쪽 단추로 클릭하고 코드 보기를 선택합니다.
2. 파일의 루트에 있는 Package 요소에 다음 네임스페이스를 추가합니다.

xmlns:uap3="http://schemas.microsoft.com/appx/manifest/uap/windows10/3"

3. Application 요소 내부와 VisualElements 요소 다음에 다음 Extensions 요소를 추가합니다.

<Extensions>
  <uap:Extension Category="windows.protocol">
    <uap:Protocol Name="urilaunchaction-protocol" ReturnResults="always">
      <!-- app-defined protocol name -->
      <uap:DisplayName>URI Launch Action Scheme</uap:DisplayName>
    </uap:Protocol>
  </uap:Extension>
  <uap3:Extension Category="windows.appExtension">
    <uap3:AppExtension Name="com.microsoft.windows.ai.actions" DisplayName="URILaunchAction" Id="UriLaunchActionId" PublicFolder="Assets">
      <uap3:Properties>
        <Registration xmlns="">registration.json</Registration>
      </uap3:Properties>
    </uap3:AppExtension>
  </uap3:Extension>
</Extensions>

앱 활성화 처리

앱 작업 공급자가 등록된 URI 스키마에서 시작되면 AppInstance.GetActivatedEventArgs를 호출하여 가져온 AppActivationArguments 개체를 통해 작업에 대한 입력에 액세스할 수 있습니다. 활성화가 등록된 프로토콜에서 시작되었는지 확인하려면 먼저 Kind 속성의 값이 ExtendedActivationKind.ProtocolForResults인지 확인해야 합니다. 이 경우 인수 개체를 ProtocolForResultsActivatedEventArgs 개체로 캐스팅할 수 있습니다.

작업에 대한 입력은 각 입력 엔터티에 대한 키/값 쌍을 포함하는 ValueSet인 이벤트 인수의 데이터 속성을 통해 액세스됩니다. 이 예제에서는 registration.json 파일에 정의된 입력 엔터티를 가져옵니다 message . 이 입력의 값은 텍스트 문자열입니다.

작업에 대한 결과를 반환하려면 앱 작업 공급자가 하나 이상의 출력 엔터티를 인스턴스화해야 합니다. 이 예제에서는 입력 메시지에 대한 응답을 포함하는 단일 TextActionEntity 를 반환합니다.

새 출력 엔터티를 인스턴스화하려면 ActionRuntime 개체의 EntityFactory 속성에서 ActionEntityFactory 클래스의 인스턴스를 가져옵니다. 팩터리 개체는 다양한 유형의 작업 엔터티를 모두 인스턴스화하는 메서드를 제공합니다. 응답 메시지를 포함하는 텍스트 엔터티를 만든 후 새 ValueSet에 항목을 만듭니다. 여기서 키는 registrationl.json 파일에 지정된 출력 이름인 "response"이고 값은 TextActionEntity의 ID입니다. CreateTextEntity를 호출하여 엔터티를 만들 때 엔터티는 작업 런타임에 등록됩니다. 따라서 엔터티의 ID 를 ValueSet의 값으로 추가합니다. 작업의 소비자는 이 ID를 사용하여 작업 런타임에서 엔터티 개체를 검색합니다.

URI 활성화를 처리하는 마지막 단계는 새 ProtocolForResultsOperation 을 만들고 ReportCompleted 메서드를 호출하여 출력 엔터티 참조가 포함된 ValueSet 을 전달하는 것입니다.

App.xaml.cs OnLaunched 의 기본 구현을 다음 코드로 바꿉 있습니다.

  ProtocolForResultsOperation? _operation;
  protected override void OnLaunched(Microsoft.UI.Xaml.LaunchActivatedEventArgs args)
  {
      var eventargs = Microsoft.Windows.AppLifecycle.AppInstance.GetCurrent().GetActivatedEventArgs();

      if ((eventargs != null) && (eventargs.Kind == ExtendedActivationKind.ProtocolForResults))
      {
          ProtocolForResultsActivatedEventArgs? protocolForResultsArgs = eventargs.Data as ProtocolForResultsActivatedEventArgs;
      
          if (protocolForResultsArgs.CallerPackageFamilyName.EndsWith("_cw5n1h2txyewy"))
          {
              using (ActionRuntime runtime = ActionRuntimeFactory.CreateActionRuntime())
              {
                  if (protocolForResultsArgs != null)
                  {
                      ValueSet inputData = protocolForResultsArgs.Data;
                      var message = inputData["message"];
      
                      Windows.AI.Actions.ActionEntityFactory source = runtime.EntityFactory;
                      Windows.AI.Actions.ActionEntity textEntity = source.CreateTextEntity("Message response.");
      
                      ValueSet result = new ValueSet();
                      result["response"] = textEntity.Id;
      
                      _operation = protocolForResultsArgs.ProtocolForResultsOperation;
                      _operation.ReportCompleted(result);
                  }
              }
          }
      }

      _window = new MainWindow();
      _window.Activate();
  }

Windows 앱 작업 테스트

앱 작업 테스트 플레이그라운드 앱을 사용하면 Windows 앱 작업 공급자 앱의 등록 및 기능의 유효성을 검사할 수 있습니다. 이 도구를 사용하는 방법에 대한 자세한 내용은 앱 작업 테스트 플레이그라운드 앱을 참조하세요.

Windows 기능에서 추가 앱 작업

다음 문서에서는 Windows에서 App Actions의 추가 기능에 대한 정보를 제공합니다.

• Windows용 앱 작업의 가용성 설정/해제

관련 콘텐츠