Windows'da Uygulama Eylemlerini kullanmaya başlama

Bu makalede uygulama eylemleri oluşturma adımları açıklanır ve Uygulama Eylemi sağlayıcı uygulamasının bileşenleri açıklanır. Uygulama eylemleri, bir Windows uygulamasının uygulayabileceği ve kaydedebildiği ve diğer uygulamalardan ve deneyimlerden erişilebilmeleri ve kullanıcı iş akışlarıyla sorunsuz bir şekilde tümleştirilebilmeleri için tek tek davranış birimleridir. Windows'ta Uygulama Eylemleri hakkında daha fazla bilgi için bkz. Windows'ta Uygulama Eylemlerine Genel Bakış

IActionProvider arabirimi, uygulama eylem sağlayıcılarının Windows eylemler çerçevesiyle iletişim kurmak için kullandığı birincil arabirimdir. Ancak Microsoft, kodunuzdaki .NET özniteliklerini temel alarak IActionProvider uygulamasını otomatik olarak oluşturan Microsoft.AI.Actions NuGet Paketi'ni sağlar ve eylemlerinizi temsil etmek için kesin olarak yazılan sınıflar oluşturmanıza olanak sağlar. Bu, uygulama eylem sağlayıcısı uygulamasını uygulamanın önerilen yoludur ve bu makalede açıklanan tekniktir. Bazı uç durum senaryolarında geliştiriciler doğrudan IActionProvider uygulamak isteyebilir. Daha fazla bilgi için bkz. IActionProvider'ı el ile uygulama.

Ayrıca, bir eylemden metin yanıtları akışı gibi bazı daha gelişmiş senaryolar desteklenmese de, COM etkinleştirmesi yerine URI başlatma etkinleştirmesini kullanarak bir uygulama eylem sağlayıcısı uygulayabilirsiniz. Daha fazla bilgi için bkz. Windows'da Uygulama Eylemleri için URI başlatmayı uygulama.

  1. Terminal'de aşağıdaki komutu çalıştırın (ister C# ister C++ geliştiricisi olun). Bu, aşağıdaki görevleri gerçekleştiren bir WinGet Yapılandırma dosyası çalıştırır (zaten yüklü olan bağımlılıklar atlanır):

    • Geliştirici Modunu etkinleştirir.
    • Visual Studio Community Edition'ı yükler
    • Windows Uygulaması geliştirme iş yükünü ve C++ veya .NET/C# İş Yüklerini dahil etme
    • MSIX Paketleme araçlarını dahil et
winget configure https://raw.githubusercontent.com/microsoft/winget-dsc/refs/heads/main/samples/Configuration%20files/Learn%20tutorials/Windows%20AI/app_actions_cs.winget

Visual Studio'da yeni bir Windows uygulaması projesi oluşturma

Windows'ta Uygulama Eylemleri özelliği birden çok uygulama çerçevesi için desteklenir, ancak uygulamaların sisteme kaydolabilmesi için paket kimliğine sahip olması gerekir. Bu kılavuz, paketlenmiş bir C# WinUI 3 masaüstü uygulamasında bir Windows Uygulama Eylemi sağlayıcısı uygular.

  1. Visual Studio'da yeni bir proje oluşturun.

  2. Yeni proje oluştur iletişim kutusunda dil filtresini "C#" ve platform filtresini "WinUI" olarak ayarlayın, ardından "Boş Uygulama, Paketlenmiş (Masaüstünde WinUI 3)" proje şablonunu seçin.

  3. Yeni projeyi "ExampleAppActionProvider" olarak adlandırın.

  4. Proje yüklendiğinde, Çözüm Gezgini'nde proje adına sağ tıklayın ve Özelliklerseçin. Genel sayfasında, aşağı kaydırarak Hedef İşletim Sistemi'ne gelin ve "Windows" seçeneğini belirleyin. Hedef işletim sistemi sürümü ve Desteklenen işletim sistemi sürümü için sürüm 10.0.26100.0 veya üzerini seçin.

  5. Projenizi Eylem Sağlayıcısı API'lerini destekleyecek şekilde güncelleştirmek için Çözüm Gezgini'nde proje adına sağ tıklayın ve Proje Dosyasını Düzenle'yi seçin. PropertyGroup'un içine aşağıdaki WindowsSdkPackageVersion öğesini ekleyin.

    <WindowsSdkPackageVersion>10.0.26100.75</WindowsSdkPackageVersion>

Microsoft.AI.Actions Nuget paketine başvuru ekleme

Bu makaledeki örnekte Microsoft.AI.Actions Nuget paketinin kod oluşturma özellikleri kullanılmaktadır.

  1. Çözüm Gezgini'nde proje adına sağ tıklayın ve NuGet Paketlerini Yönet... öğesini seçin.
  2. Gözat sekmesinde olduğunuzdan emin olun ve Microsoft.AI.Actions araması yapın.
  3. Microsoft.AI.Actions'ı seçin ve Yükle'ye tıklayın.

Eylem işlemlerini işlemek için bir ActionProvider sınıfı ekleme

Aşağıdaki bölümde, bir eylemin bileşenlerini tanımlamak için Microsoft.AI.Actions.Annotations ad alanından .NET özniteliklerini kullanan bir özel eylem sağlayıcısı sınıfının nasıl uygulandığını gösterilmektedir. Microsoft.AI.Actions NuGet paketi, IActionProvider arabiriminin temel bir uygulamasını otomatik olarak oluşturmak için bu öznitelikleri kullanır. Bu, alt düzey eylem sağlayıcısı API'leriyle doğrudan etkileşim kurmak zorunda kalmadan eylemler için kesin olarak belirlenmiş sınıflar oluşturmanıza olanak tanır.

  1. Visual Studio'da, Çözüm Gezgini menüsünden projeye sağ tıklayın veSınıfekle-seçeneğini seçin.
  2. Sınıf ekle iletişim kutusunda sınıfı "MyActionProvider" olarak adlandırın ve Ekle'ye tıklayın.
  3. öğesinin içeriğini MyActionProvider.cs aşağıdaki kodla değiştirin.
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}");
            }
        }
    }
}

Microsoft.AI.Actions Nuget paketinin kod oluşturma özellikleri, uygulamanızın sağladığı eylemlerin ayrıntılarını belirlemek için kodunuzda .NET özniteliklerini kullanır. Bu örnekte aşağıdaki öznitelikler kullanılır:

Özellik Description
ActionProviderAttribute Bu öznitelik, bir veya daha fazla eylem uygulayan bir sınıfı tanımlar.
WindowsActionAttribute Bu öznitelik, uygulamanın insan tarafından okunabilen açıklaması ve eylemlerinizi kullananların kullanıcılara görüntüleyebileceği bir simge dosyası gibi bir eylemle ilgili meta veriler sağlar.
WindowsActionInputCombinationAttribute Bu öznitelik, bir eylemin giriş olarak kabul edebildiği bir dizi giriş varlığı bildirir. Tek bir eylem birden çok giriş bileşimini destekleyebilir.
EntityAttribute Sınıfın bir ActionEntity'yi temsil ettiğini gösterir

Desteklenen özniteliklerin çoğu, sistemin eylemleri bulmak için kullandığı eylem tanımı JSON dosyasındaki alanlarla doğrudan eşler. Aslında, bu makalenin devamında da gösterileceği gibi, Microsoft.AI.Actions kod oluşturma özelliği, derleme zamanında eylem tanımı JSON dosyasını otomatik olarak oluşturmak için bu öznitelikleri kullanır. Eylem sağlayıcısı sınıfınızı güncelleştirdiğinizde ve bu öznitelikleri eklediğinizde veya değiştirdiğinizde, Nuget paketi değişikliklerinizi yansıtacak şekilde eylem tanımı dosyasını yeniden oluşturur. Eylem tanımı JSON dosyası hakkında daha fazla bilgi için bkz. Windows'da Uygulama Eylemleri için eylem tanımı JSON şeması.

Desteklenen özniteliklerin listesi için Microsoft.AI.Actions Nuget paketi için benioku dosyasına bakın.

Uygulama paketi bildirim dosyasını güncelleştirme

Package.appmanifest dosyası, bir uygulamanın MSIX paketinin ayrıntılarını sağlar. Sistem tarafından Bir Windows Uygulama Eylemi sağlayıcısı olarak kaydedilebilmesi için, uygulamanın Category değeri "windows.appExtension" olarak ayarlanmış bir uap3:Extension öğesi içermesi gerekir. Bu öğe, uygulamanın eylemlerini tanımlayan Uygulama Eylemi JSON dosyasının konumunu belirtmek için kullanılır. uap3:AppExtension öğesinin Adı olarak da belirtmelisinizcom.microsoft.windows.ai.actions. Eylem sağlayıcısı uygulama paketi bildirim biçimi hakkında daha fazla bilgi için bkz. Windows Uygulama Eylemi sağlayıcı paketi bildirim XML biçimi.

Bu kılavuzdaki örnek, uygulama eylem sağlayıcısını başlatmak için COM etkinleştirmesini kullanır. COM etkinleştirmeyi etkinleştirmek için uygulama paketi bildirimindeki com2:Extension öğesini kullanın. Eylem tanımı JSON dosyasında belirtilen invocation.clsid değeri, uygulama paketi bildirimindeki com:Class öğesinde belirtilen sınıf kimliğiyle eşleşmelidir.

  1. Package.appxmanifest dosyasına sağ tıklayın ve Kodu Görüntüle'yi seçin
  2. Dosyanın kökündeki Package öğesine aşağıdaki ad alanlarını ekleyin.
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. Aşağıdaki Extensions öğesini Application öğesinin içine ve VisualElements öğesinin arkasına ekleyin.
<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>

Özel bir Main yöntemi uygulama

Varsayılan proje şablonunda , Main yöntemi giriş noktası derleyici tarafından otomatik olarak oluşturulur. Bu örnek, gerekli etkinleştirme kodunun başlangıçta çalıştırılabilmesi için Main'ın otomatik olarak yenilenmesini devre dışı bırakır.

  1. Çözüm Gezgini'nde proje simgesine sağ tıklayın ve Proje Dosyasını Düzenle'yi seçin.
  2. PropertyGroup öğesinde, otomatik olarak oluşturulan ana işlevi devre dışı bırakmak için aşağıdaki alt öğeyi ekleyin.
<DefineConstants>$(DefineConstants);DISABLE_XAML_GENERATED_MAIN</DefineConstants>

Ardından, Çözüm Gezgini'nde proje simgesine sağ tıklayın ve Yeni Öğe Ekle'yi> seçin. Kod Dosyası'na tıklayın. Dosya adını "Program.cs" olarak değiştirin ve Ekle'ye tıklayın.

Program.cs dosyasında, nuget eylemleri paketinin sistemin eylem sağlayıcısını çağırmasına olanak tanıyan COM sunucusu etkinleştirmesini otomatik olarak oluşturmasına neden olacak bir kod satırı ekleyeceğiz.

ComServerRegisterActions.RegisterActions();

Bu örnekte Main yöntemindeki kodun geri kalanı, winUI uygulamasını başlatmaya yönelik ortak koddur. Program.cs içeriğini aşağıdaki kodla değiştirin.

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 yapılandırma özelliklerini proje dosyasına ekleme

Microsoft.AI.Actions Nuget paketinin kod oluşturma özelliği, derleme zamanında davranışını yapılandırmak için proje dosyasında tanımlanan özellik değerlerini kullanır. .csproj dosyanızdaki ilk PropertyGroup öğesinin içine aşağıdaki özellikleri ekleyin.

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

Aşağıdaki tabloda bu özellikler açıklanmaktadır.

Mülkiyet Description
GenerateActionRegistrationManifest True olarak ayarlandığında, eylem paketi eylem sağlayıcısı sınıf tanımınızdaki .NET özniteliklerini temel alan bir eylem tanımı JSON dosyasını otomatik olarak oluşturur. Oluşturulan eylem tanımı dosyasında el ile yaptığınız değişikliklerin, projeyi her derlediğinizde üzerine yazılacağını unutmayın. Bu nedenle, el ile yaptığınız değişiklikleri korumanız gerekiyorsa, bu değeri false olarak ayarlayabilirsiniz.
ActionRegistrationManifest Otomatik oluşturulan eylem tanımı JSON dosyasının paket göreli yolu. Sistemin, uygulama paketi bildirim dosyasındaki uap3:AppExtension öğesinin PublicFolder özniteliğinde belirtilen klasöre bakacağını unutmayın. Bu nedenle, bu özelliğin yolunun ve bildirim dosyasında bildirilen ortak klasörün eşleştiğinden emin olun.
GenerateActionsWinRTComServer Bu makalenin önceki bölümlerinde gösterilen ComServerRegisterActions.RegisterActions çağrısından Program.cs COM Sunucusu etkinleştirme kodunun otomatik olarak yenilenmesini etkinleştirmek için bunu true olarak ayarlayın. Bu değer false olarak ayarlanırsa, kendi COM Sunucusu etkinleştirmenizi uygulamanız gerekir.
RootNamespace Otomatik olarak oluşturulan kodun kök ad alanını, kendi kodunuzdan erişebilmeniz için ayarlar.

Oluşturulan registration.json dosyasını temel alarak güncelleştirmeler yapma

Projenizi oluşturduktan sonra, oluşturulan registration.json dosyayı Çözüm Gezgini'ndekiVarlıklar klasöründe görüntüleyebilirsiniz.

{
  "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"
      }
    }
  ]
}

Uygulama paketi bildirim dosyasında CLSID'yi güncelleştirme

Eylem sağlayıcısı uygulamanızı ilk kez oluşturduğunuzda şu uyarıyı alırsınız: warning WASDK0012: The Action Provider type ExampleAppActionProvider.MyActionsProvider is not registering a ComServer with Class Id '00000000-0000-0000-0000-0000000'. Bunun nedeni, otomatik oluşturulan registration.json dosyanın eylemin COM sunucusunun clsid değerini benzersiz bir GUID ile bildirmesidir. Projenizi derledikten sonra dosyasını açın registration.json ve dosyanın eylemin COM etkinleştirmesi kullandığını bildirdiğini ve bir clsid değeri belirttiğini unutmayın. Oluşturulan GUID'yi kullanmak için uygulama paketi bildirim dosyanızdaki com:Class öğesindeki Id özniteliğinin değerini değiştirin.

Örneğin, oluşturulan registration.json dosyadaki clsid değeri ise11112222-bbbb-3333-cccc-4444dddd5555, güncelleştirilmiş com:Class öğesi aşağıdaki gibi görünür:

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

İzin verilen uygulama çağırıcıları

Eylem tanımı JSON şemasına eklenen yeni bir alan, GetActionsForInputs veya GetAllActions çağrısı aracılığıyla eylemi bulabilen Uygulama Kullanıcı Modeli Kimliklerinin (AppUserModelIDs) listesini belirten AllowedAppInvokers'dır. Joker karakterler desteklenir. "*" tüm AppUserModelID'lerle eşleşir. Bu, bir eylemi çağırabilecek arayanları sınırlamak için belirli bir neden olmadığı sürece çoğu eylem için önerilir. allowedAppInvokers atlanırsa veya boş bir listeyse, hiçbir uygulama eylemi keşfedemez. AppUserModelID'ler hakkında daha fazla bilgi için bkz. Uygulama Kullanıcı Modeli Kimlikleri.

Aşağıdaki örnekte, tüm uygulamaların ilişkili eylemi bulmasına izin vermek için allowedAppInvokers ayarının önerilen uygulaması gösterilmektedir.

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

Önemli

Geçerli Microsoft.AI.Actions sürümünde, eylem tanımı dosyası her yeniden oluşturulduğunda allowedAppInvokers'ın üzerine yazılır. Eylem tanımı JSON dosyanıza allowedAppInvokers ekledikten sonra, proje dosyanızda GenerateActionRegistrationManifest değerini false olarak ayarlamanız gerekir. Kodunuzu değiştirirseniz ve JSON dosya oluşturmayı yeniden etkinleştirmeniz gerekiyorsa, allowedAppInvokers'ı dosyaya geri eklediğinizden ve JSON dosya oluşturmayı yeniden devre dışı bırakdığınızdan emin olun.

Windows Uygulaması Eylemini Test Edin

Uygulama Eylemleri Test Oyun Alanı uygulaması, Windows Uygulama Eylemi sağlayıcı uygulamanızın kaydını ve işlevselliğini doğrulamanıza olanak tanır. Bu aracı kullanma hakkında daha fazla bilgi için bkz. Uygulama Eylemleri Test Oyun Alanı.

  • Last updated on