Obsługa plików zdalnych za pomocą akcji aplikacji w systemie Windows

W tym artykule opisano sposób implementowania obsługi plików zdalnych hostowanych przez dostawcę usług w chmurze z poziomu akcji aplikacji w aplikacji dostawcy systemu Windows. Typ jednostki RemoteFile reprezentowany w języku C# przez klasę RemoteFileActionEntity udostępnia właściwości, które są używane przez wielu dostawców magazynu plików w chmurze, takich jak unikatowe identyfikatory plików i dysków. W przykładach na tej stronie pokazano, jak uzyskać dostęp do właściwości pliku w chmurze, ale nie pobierać ani przetwarzać plików zdalnych, ponieważ te procesy będą się różnić między różnymi aplikacjami i dostawcami. Aby uzyskać więcej informacji na temat różnych typów jednostek, które mogą być używane jako dane wejściowe i wyjściowe dla akcji, zobacz Schemat JSON definicji akcji dla akcji aplikacji w systemie Windows.

Przetwarzanie plików zdalnych przy użyciu generowania kodu Microsoft.AI.Actions

W poniższym przykładzie pokazano, jak zaimplementować zdalną obsługę plików u dostawcy akcji, który używa pakietu NuGet Microsoft.AI.Actions , który automatycznie generuje implementację IActionProvider na podstawie atrybutów platformy .NET w kodzie, umożliwiając tworzenie silnie typiowanych klas reprezentujących akcje. Aby uzyskać informacje na temat tworzenia aplikacji dostawcy akcji przy użyciu pakietu NuGet **Microsoft.AI.Actions, zobacz Wprowadzenie do akcji aplikacji w systemie Windows.

Należy pamiętać, że klauzula Where jest używana w atrybucie WindowsActionInputCombination w celu określenia dostawców usług w chmurze obsługiwanych przez tę akcję. Zawsze dobrym pomysłem jest użycie takich klauzul, aby zapobiec wyświetlaniu akcji użytkownikom w scenariuszach, których akcja nie obsługuje.

[ActionProvider]
public sealed class MyActionsProvider
{
    [WindowsAction(Description = "Summarize a remote file", Icon = "ms-resource://Files/Assets/LockScreenLogo.png", UsesGenerativeAI = false)]

    [WindowsActionInputCombination(Description = "Summarize ${RemoteFileToSummarize}", 
        Inputs = ["RemoteFileToSummarize"], 
        Where = ["${RemoteFileToSummarize.SourceId} == 'Contoso.Cloud' || ${RemoteFileToSummarize.SourceId} == 'Fabrikam.Cloud'"])]
    public async Task<SummarizeRemoteFileResult> SummarizeRemoteFile([Entity(Name = "RemoteFileToSummarize")] RemoteFileActionEntity remoteFile, InvocationContext context)
    {
        var summary = "";
        var remoteFileContents = "";

        switch (remoteFile.SourceId)
        {
            case "Contoso.Cloud":
                // Retrieve the file contents using the properties used by the "Contoso" service 
                remoteFileContents = GetContosoCloudFile(remoteFile.AccountId, remoteFile.DriveId, remoteFile.FileId);
                summary = SummarizeFile(remoteFileContents);
                break;

            case "Fabrikam.Cloud":
                // Retrieve the file contents using the properties used by the "Fabrikam" service 
                remoteFileContents = GetFabrikamCloudFile(remoteFile.AccountId, remoteFile.SourceUri);
                summary = SummarizeFile(remoteFileContents);
                break;

        }

        
        var entityFactory = context.EntityFactory;

        return new SummarizeRemoteFileResult
        {
            Text = entityFactory.CreateTextEntity(summary)
        };
    }

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

Definicja akcji JSON z danymi wejściowymi pliku zdalnego

Poniższy przykład kodu przedstawia plik JSON definicji akcji, który deklaruje akcję korzystającą z jednostki RemoteFile . Jeśli używasz narzędzia NuGet Microsoft.AI.Actions do automatycznego generowania pliku definicji akcji JSON, będzie on wyglądać podobnie po zaimplementowaniu akcji, jak pokazano w poprzedniej sekcji.

{
  "version": 3,
  "actions": [
    {
      "id": "ExampleAppActionProvider.MyActionsProvider.SummarizeRemoteFile",
      "description": "Summarize a remote file",
      "icon": "ms-resource://Files/Assets/LockScreenLogo.png",
      "usesGenerativeAI": false,
      "allowedAppInvokers" :  ["*"],
      "inputs": [
        {
          "name": "RemoteFileToSummarize",
          "kind": "RemoteFile"
        }
      ],
      "inputCombinations": [
        {
          "inputs": [
            "RemoteFileToSummarize"
          ],
          "where": [
            "${RemoteFileToSummarize.SourceId} == 'Contoso.Cloud' || ${RemoteFileToSummarize.SourceId} == 'Fabrikam.Cloud'"
          ],
          "description": "Summarize ${RemoteFileToSummarize}"
        }
      ],
      "outputs": [
        {
          "name": "Text",
          "kind": "Text"
        }
      ],
      "invocation": {
        "type": "COM",
        "clsid": "00001111-aaaa-2222-bbbb-3333cccc4444"
      }
    }
  ]
}

Przetwarzanie plików zdalnych za pomocą elementu IActionProvider

W tej sekcji pokazano, jak zaimplementować akcję, która akceptuje jednostkę RemoteFile jako dane wejściowe podczas ręcznego implementowania interfejsu IActionProvider . Musisz również ręcznie dodać plik JSON definicji akcji, taki jak plik pokazany w poprzedniej sekcji do projektu. Aby uzyskać więcej informacji na temat implementowania dostawcy akcji opartego na modelu COM bez używania funkcji generowania kodu Microsoft.AI.Actions, zobacz Ręczne implementowanie elementu IActionProvider.

public IAsyncAction InvokeAsync(ActionInvocationContext context)
{
    return InvokeAsyncHelper(context).AsAsyncAction();
}

async Task InvokeAsyncHelper(ActionInvocationContext context)
{
    NamedActionEntity[] inputs = context.GetInputEntities();

    var actionId = context.ActionId;
    switch (actionId)
    {
        case "ExampleAppActionProvider.MyActionsProvider.SummarizeRemoteFile":
            var summary = "";
            var remoteFileContents = "";

            foreach (NamedActionEntity inputEntity in inputs)
            {
                if (inputEntity.Name.Equals("RemoteFileToSummarize", StringComparison.Ordinal))
                {
                    var remoteFile = (RemoteFileActionEntity)inputEntity.Entity;
                    switch (remoteFile.SourceId)
                    {
                        case "Contoso.Cloud":
                            // Retrieve the file contents using the properties used by the "Contoso" service 
                            remoteFileContents = GetContosoCloudFile(remoteFile.AccountId, remoteFile.DriveId, remoteFile.FileId);
                            summary = SummarizeFile(remoteFileContents);
                            break;

                        case "Fabrikam.Cloud":
                            // Retrieve the file contents using the properties used by the "Fabrikam" service 
                            remoteFileContents = GetFabrikamCloudFile(remoteFile.AccountId, remoteFile.SourceUri);
                            summary = SummarizeFile(remoteFileContents);
                            break;

                    }
                }
            }
            
            TextActionEntity result = context.EntityFactory.CreateTextEntity(summary);
            context.SetOutputEntity("Text", result);


            break;

        default:
            break;

    }
}