Начните работу с функциями приложений в Windows

В этой статье описаны шаги по созданию действий приложений и описаны компоненты приложения поставщика действий приложений. Действия приложений — это отдельные единицы поведения, которые приложение Windows может реализовать и зарегистрировать, чтобы они могли быть доступны из других приложений и возможностей, легко интегрируясь в рабочие процессы пользователей. Дополнительные сведения о действиях приложений в Windows см. в разделе "Действия приложений" в Обзоре Windows

Интерфейс IActionProvider — это основной интерфейс, используемый поставщиками действий приложения для взаимодействия с платформой действий Windows. Однако корпорация Майкрософт предоставляет пакет NuGet Microsoft.AI.Actions , который автоматически создает реализацию IActionProvider на основе атрибутов .NET в коде, что позволяет создавать строго типизированные классы для представления действий. Это рекомендуемый способ реализации приложения для приложения поставщика действий и является методом, описанным в этой статье. Для некоторых сценариев пограничных сценариев разработчики могут напрямую реализовать IActionProvider . Дополнительные сведения см. в руководстве по реализации IActionProvider вручную.

Вы также можете реализовать поставщик действий приложения с помощью активации запуска URI, а не активации COM, хотя некоторые более сложные сценарии, такие как потоковая передача текстовых ответов из действия, не поддерживаются. Дополнительные сведения см. в разделе "Реализация URI" для действий приложений в Windows.

  1. Выполните приведенную ниже команду в терминале (будь то разработчик C# или C++). При этом запускается файл конфигурации WinGet , выполняющий следующие задачи (уже установленные зависимости будут пропущены):

    • Включает режим разработчика.
    • Установка Visual Studio Community Edition
    • Включите рабочие нагрузки для разработки приложений Windows и нагрузки C++ или .NET/C#
    • Включите средства упаковки MSIX
winget configure https://raw.githubusercontent.com/microsoft/winget-dsc/refs/heads/main/samples/Configuration%20files/Learn%20tutorials/Windows%20AI/app_actions_cs.winget

Создание проекта приложения Windows в Visual Studio

Функция "Действия приложений в Windows" поддерживается для нескольких платформ приложений, но приложения должны иметь удостоверение пакета для регистрации в системе. В этом пошаговом руководстве будет реализован поставщик действий для приложений Windows в упакованном настольном приложении C# WinUI 3.

  1. В Visual Studio создайте проект.

  2. В диалоговом окне "Создание проекта " задайте для фильтра языка значение "C#", а фильтр платформы — "WinUI", а затем выберите шаблон проекта "Пустое приложение, упакованое (WinUI 3 в desktop)".

  3. Назовите новый проект ExampleAppActionProvider.

  4. Когда проект загрузится, в Обозревателе решений щелкните правой кнопкой мыши по имени проекта и выберите Свойства. На странице общего прокрутите страницу вниз до целевой ОС и выберите "Windows". Для целевой версии ОС и поддерживаемой версии ОС выберите версию 10.0.26100.0 или более поздней.

  5. Чтобы обновить проект для поддержки API поставщика действий, в обозревателе решений щелкните правой кнопкой мыши имя проекта и выберите "Изменить файл проекта". В PropertyGroup добавьте следующий элемент WindowsSdkPackageVersion .

    <WindowsSdkPackageVersion>10.0.26100.75</WindowsSdkPackageVersion>

Добавление ссылки на пакет Nuget Microsoft.AI.Actions

В примере в этой статье используются функции создания кода пакета Nuget Microsoft.AI.Actions.

  1. В обозревателе решений щелкните правой кнопкой мыши имя проекта и выберите пункт "Управление пакетами NuGet...
  2. Убедитесь, что вы находитесь на вкладке "Обзор " и найдите Microsoft.AI.Actions.
  3. Выберите Microsoft.AI.Actions и нажмите кнопку "Установить".

Добавление класса ActionProvider для обработки операций действия

В следующем разделе показано, как реализовать настраиваемый класс поставщика действий, использующий атрибуты .NET из пространства имен Microsoft.AI.Actions.Annotations для идентификации компонентов действия. Пакет NuGet Microsoft.AI.Actions использует эти атрибуты для автоматического создания базовой реализации интерфейса IActionProvider . Это позволяет создавать строго типизированные классы для действий без необходимости напрямую взаимодействовать с ИНТЕРФЕЙСами API поставщика действий низкого уровня.

  1. В Visual Studio щелкните правой кнопкой мыши проект ExampleAppActionProvider в обозревателе решений и выберите Добавить ->Класс.
  2. В диалоговом окне "Добавить класс " назовите класс MyActionProvider и нажмите кнопку "Добавить".
  3. Замените содержимое MyActionProvider.cs следующим кодом.
using Microsoft.AI.Actions.Annotations;
using System.Threading.Tasks;
using Windows.AI.Actions;

namespace ExampleAppActionProvider
{
    [ActionProvider]
    public sealed class MyActionsProvider
    {
        [WindowsAction(
            Description = "Send a message to a contact",
            Icon = "ms-resource://Files/Assets/StoreLogo.png",
            FeedbackHandler = nameof(SendMessageFeedback),
            UsesGenerativeAI = false
        )]
        [WindowsActionInputCombination(
            Inputs = ["Contact"],
            Description = "Send message to '${Contact.Text}'"
        )]
        [WindowsActionInputCombination(
            Inputs = ["Contact", "Message"],
            Description = "Send '${Message.Text}' to '${Contact.Text}'"
        )]

        public async Task<SendMessageResult> SendMessage(
            [Entity(Name = "Contact")] string contact,
            [Entity(Name = "Message")] string? message,
            InvocationContext context)
        {
            // Your action logic here
            string result = await ProcessMessageAsync(contact, message);

            return new SendMessageResult
            {
                Text = context.EntityFactory.CreateTextEntity(result)
            };
        }
        
        public Task SendMessageFeedback(ActionFeedback feedback, InvocationContext context)
        {
            // Handle user feedback for the action
            return Task.CompletedTask;
        }

        public record SendMessageResult
        {
            public required TextActionEntity Text { get; init; }
        }

        public async Task<string> ProcessMessageAsync(string contact, string? message)
        {
            if (message != null)
            {
                return await Task.Run(() => $"Processed {contact}, {message}");
            }
            else
            {
                return await Task.Run(() => $"Processed {contact}");
            }
        }
    }
}

Функции создания кода пакета Nuget Microsoft.AI.Actions используют атрибуты .NET в коде для определения сведений о действиях, предоставляемых приложением. В этом примере используются следующие атрибуты:

Свойство Description
ActionProviderAttribute Этот атрибут определяет класс, реализующий одно или несколько действий.
WindowsActionAttribute Этот атрибут предоставляет метаданные о действии, например о удобочитаемом описании приложения и файле значка, который потребители действий могут отображать пользователям.
WindowsActionInputCombinationAttribute Этот атрибут объявляет набор входных сущностей, которые действие может принимать в качестве входных данных. Одно действие может поддерживать несколько сочетаний входных данных.
EntityAttribute Указывает, что класс представляет ActionEntity

Большинство поддерживаемых атрибутов сопоставляют непосредственно с полями в json-файле определения действия, который система использует для обнаружения действий. На самом деле, как показано далее в этой статье, функция создания кода Microsoft.AI.Actions использует эти атрибуты для автоматического создания JSON-файла определения действия во время сборки. При обновлении класса поставщика действий, добавлении или изменении этих атрибутов пакет Nuget повторно создаст файл определения действия, чтобы отразить изменения. Дополнительные сведения об JSON-файле определения действия см. в схеме JSON определения действия для действий приложений в Windows.

Список поддерживаемых атрибутов см. в файле readme для пакета Nuget Microsoft.AI.Actions .

Обновление файла манифеста пакета приложения

Файл Package.appmanifest содержит сведения о пакете MSIX для приложения. Чтобы зарегистрировать систему в качестве поставщика действий приложений Windows, приложение должно включать элемент uap3:Extension с параметром "Категория ", равным "windows.appExtension". Этот элемент используется для указания расположения JSON-файла Действия приложения, который определяет действия приложения. Необходимо также указать com.microsoft.windows.ai.actionsимя элементаuap3:AppExtension . Дополнительные сведения о формате манифеста пакета приложения поставщика действий см. в формате XML манифеста пакета для приложения Windows App Action.

В данном учебном примере используется активация COM для запуска провайдера действий приложения. Чтобы включить активацию COM, используйте элемент com2:Extension в манифесте пакета приложения. Значение invocation.clsid , указанное в JSON-файле определения действия, должно соответствовать идентификатору класса, указанному в элементе com:Class в манифесте пакета приложения.

  1. Щелкните правой кнопкой мыши файл Package.appxmanifest и выберите команду View Code
  2. Добавьте следующие пространства имен в элемент Package в корне файла.
xmlns:uap3="http://schemas.microsoft.com/appx/manifest/uap/windows10/3"
xmlns:com="http://schemas.microsoft.com/appx/manifest/com/windows10"
xmlns:com2="http://schemas.microsoft.com/appx/manifest/com/windows10/2"
xmlns:com3="http://schemas.microsoft.com/appx/manifest/com/windows10/3"
  1. Добавьте следующий элемент Extensions в элемент Application и после элемента VisualElements .
<Extensions>
  <com2:Extension Category="windows.comServer">
    <com2:ComServer>
        <com3:ExeServer Executable="ExampleAppActionProvider.exe" DisplayName="ExampleAppActionProvider">
            <com:Class Id="00001111-aaaa-2222-bbbb-3333cccc4444" DisplayName="ExampleAppActionProvider" />
        </com3:ExeServer>
      </com2:ComServer>
    </com2:Extension>
    <uap3:Extension Category="windows.appExtension">
        <uap3:AppExtension Name="com.microsoft.windows.ai.actions" DisplayName="Example App Action Provider" Id="appactionprovider" PublicFolder="Assets">
        <uap3:Properties>
            <Registration>registration.json</Registration>
        </uap3:Properties>
    </uap3:AppExtension>
</uap3:Extension>
</Extensions>

Реализуйте пользовательский метод "Main"

В шаблоне проекта по умолчанию точка входа основного метода автоматически создается компилятором. Этот пример отключит автоматическое создание Main , чтобы при запуске можно было запустить необходимый код активации.

  1. В обозревателе решений щелкните правой кнопкой мыши значок проекта и выберите "Изменить файл проекта".
  2. В элементе PropertyGroup добавьте следующий дочерний элемент, чтобы отключить автоматически созданную главную функцию.
<DefineConstants>$(DefineConstants);DISABLE_XAML_GENERATED_MAIN</DefineConstants>

Затем в обозревателе решений щелкните правой кнопкой мыши значок проекта и выберите "Добавить новый> элемент". Выберите файл кода. Измените имя файла на "Program.cs" и нажмите кнопку "Добавить".

В файле Program.cs мы добавим строку кода, которая приведет к автоматическому созданию активации COM-сервера, которая позволяет системе вызывать поставщика действий.

ComServerRegisterActions.RegisterActions();

Остальная часть кода в методе Main в этом примере — это просто стандартный код для запуска приложения WinUI. Замените содержимое Program.cs приведенным ниже кодом.

namespace ExampleAppActionProvider;

public static class Program
{

    [global::System.STAThreadAttribute]
    static void Main(string[] args)
    {
        global::WinRT.ComWrappersSupport.InitializeComWrappers();
        ComServerRegisterActions.RegisterActions();
        global::Microsoft.UI.Xaml.Application.Start((p) =>
        {
            var context = new global::Microsoft.UI.Dispatching.DispatcherQueueSynchronizationContext(global::Microsoft.UI.Dispatching.DispatcherQueue.GetForCurrentThread());
            global::System.Threading.SynchronizationContext.SetSynchronizationContext(context);
            new App();
        });
    }
}

Добавление свойств конфигурации Microsoft.AI.Actions в файл проекта

Функция создания кода пакета Nuget Microsoft.AI.Actions использует значения свойств, определенные в файле проекта, для настройки его поведения во время сборки. Добавьте следующие свойства в первый элемент PropertyGroup в CSPROJ-файле.

<GenerateActionRegistrationManifest>true</GenerateActionRegistrationManifest>
<ActionRegistrationManifest>Assets\registration.json</ActionRegistrationManifest>
<GenerateActionsWinRTComServer>true</GenerateActionsWinRTComServer>
<RootNamespace>ExampleAppActionProvider</RootNamespace>

Эти свойства рассматриваются в таблице ниже.

Недвижимость Description
GenerateActionRegistrationManifest Если задано значение true , пакет действий автоматически создаст JSON-файл определения действия на основе атрибутов .NET в определении класса поставщика действий. Обратите внимание, что изменения вручную, внесенные в созданный файл определения действия, будут перезаписаны при сборке проекта. Таким образом, если необходимо сохранить внесенные вручную изменения, можно задать для этого значения значение false.
ActionRegistrationManifest Относительный путь пакета к файлу JSON определения автоматически созданного действия. Обратите внимание, что система будет выглядеть в папке, указанной в атрибуте PublicFolder элемента uap3:AppExtension в файле манифеста пакета приложения. Поэтому убедитесь, что путь к этому свойству и общедоступной папке, объявленной в файле манифеста, совпадают.
GenerateActionsWinRTComServer Задайте для этого значение true , чтобы включить автоматическое создание кода активации COM-сервера из вызова ComServerRegisterActions.RegisterActions , показанного ранее в Program.cs этой статье. Если для этого значения задано значение false , необходимо реализовать собственную активацию COM-сервера.
RootNamespace Задает корневое пространство имен автоматически созданного кода, чтобы получить доступ к нему из собственного кода.

Создание обновлений на основе созданного файла registration.json

После создания проекта можно просмотреть созданный registration.json файл в папке "Активы " в обозревателе решений.

{
  "version": 2,
  "actions": [
    {
      "id": "ExampleAppActionProvider.MyActionsProvider.SendMessage",
      "description": "Send a message to a contact",
      "icon": "ms-resource://Files/Assets/StoreLogo.png",
      "usesGenerativeAI": false,
      "hasFeedbackHandler": true,
      "inputs": [
        {
          "name": "Contact",
          "kind": "Text"
        },
        {
          "name": "Message",
          "kind": "Text"
        }
      ],
      "inputCombinations": [
        {
          "inputs": [
            "Contact"
          ],
          "description": "Send message to '${Contact.Text}'"
        },
        {
          "inputs": [
            "Contact",
            "Message"
          ],
          "description": "Send '${Message.Text}' to '${Contact.Text}'"
        }
      ],
      "outputs": [
        {
          "name": "Text",
          "kind": "Text"
        }
      ],
      "invocation": {
        "type": "COM",
        "clsid": "11112222-bbbb-3333-cccc-4444dddd5555"
      }
    }
  ]
}

Обновление CLSID в файле манифеста пакета приложения

При первом создании приложения поставщика действий вы получите предупреждение: warning WASDK0012: The Action Provider type ExampleAppActionProvider.MyActionsProvider is not registering a ComServer with Class Id '00000000-0000-0000-0000-0000000' Это связано с тем, что автоматически созданный registration.json файл объявляет clsid COM-сервера для действия с уникальным ИДЕНТИФИКАТОРом GUID. После создания проекта откройте registration.json файл и обратите внимание, что файл объявляет, что действие использует активацию COM и указывает значение clsid . Замените значение атрибута Id в элементе com:Class в файле манифеста пакета приложения, чтобы использовать созданный GUID.

Например, если значение clsid в созданном registration.json файле имеет значение 11112222-bbbb-3333-cccc-4444dddd5555, обновленный элемент com:Class будет выглядеть следующим образом:

<com:Class Id="11112222-bbbb-3333-cccc-4444dddd5555" DisplayName="ExampleAppActionProvider" />

Разрешенные вызывающие приложения

Новое поле, которое было добавлено в схему JSON определения действия, разрешеноAppInvokers , указывающее список идентификаторов пользовательской модели приложения (AppUserModelIDs), которые могут обнаруживать действие с помощью вызова GetActionsForInputs или GetAllActions. Поддерживаются подстановочные знаки. "*" будет соответствовать всем AppUserModelIDs. Это рекомендуется для большинства действий, если не существует определенной причины ограничения вызывающих, которые могут вызывать действие. Если allowedAppInvokers опущен или является пустым списком, приложения не смогут обнаружить действие. Дополнительные сведения об идентификаторах AppUserModelID см. в разделе Идентификаторы пользовательской модели приложений.

В следующем примере показана рекомендуемая практика настройки allowAppInvokers , чтобы разрешить всем приложениям обнаруживать связанное действие.

"actions": [
    {
      "id": "ExampleAppActionProvider.MyActionsProvider.SendMessage",
      "description": "Send a message to a contact",
      "icon": "ms-resource://Files/Assets/StoreLogo.png",
      "usesGenerativeAI": false,
      "hasFeedbackHandler": true,
      "allowedAppInvokers" : ["*"],
    ...

Это важно

В текущем выпуске Microsoft.AI.Actionsразрешенные ПриложенияAppInvoker будут перезаписаны при повторном создании файла определения действия. После добавления разрешенныхAppInvokers в JSON-файл определения действия необходимо задать значение GenerateActionRegistrationManifestзначение false в файле проекта. Если вы измените код и хотите снова включить создание JSON-файла, обязательно добавьте разрешенные приложенияAppInvokers обратно в файл и снова отключите создание JSON-файла.

Проверка действия приложения Windows

Приложение "Тестовый игровой полигон для действий приложений" позволяет проверить регистрацию и функциональные возможности вашего приложения-поставщика действий для Windows. Для получения дополнительной информации об использовании этого инструмента см. App Actions Testing Playground.

  • Last updated on