Microsoft.AI.Actions 0.1.0

Microsoft.AI.Actions NuGet Package

Overview

The Microsoft.AI.Actions NuGet package provides source generators, attributes, and helper classes to simplify creation and consumption of Windows App Actions.

For more information about Windows App Actions, visit the App Actions on Windows Overview documentation.

Features

• Source Generation: Automatic code generation for action providers using C# attributes
• Type-Safe Action Definition: Strongly-typed action methods with parameter validation
• Entity Support: Rich entity annotation system for action parameters
• Feedback Handling: Built-in support for action feedback and user interactions
• COM Server Generation: Automatic WinRT COM server generation for action registration

Quick Start

1. Define an Action Provider

Create a class and annotate it with the [ActionProvider] attribute:

using Microsoft.AI.Actions.Annotations;
using Windows.AI.Actions;

[ActionProvider]
public sealed class MyActionsProvider
{
    [WindowsAction(
        Description = "Send a message to a contact",
        Icon = "ms-resource://MyApp/Assets/MessageIcon.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; }
}

2. Build Your Project

The source generator will automatically create the necessary COM server infrastructure and action registration code during compilation.

Core Attributes

[ActionProvider]

Marks a class as an action provider. The source generator will create COM server registration code for this class.

Properties:

• ClsId: Optional custom CLSID for the COM server

[WindowsAction]

Defines a Windows action method that can be invoked by the system.

Properties:

• Id: Unique identifier for the action
• Description: Human-readable description of the action
• Icon: Path to the action's icon resource
• FeedbackHandler: Name of the method that handles action feedback
• UsesGenerativeAI: Indicates if the action uses AI/ML capabilities
• IsAvailable: Whether the action is currently available
• DisplaysUI: Whether the action shows user interface
• ContentAgeRating: Age rating for the action content
• PositiveFeedbackUri: URI for positive feedback
• NegativeFeedbackUri: URI for negative feedback

[WindowsActionInputCombination]

Defines valid input combinations for an action method. Multiple attributes can be applied to support different parameter combinations.

Properties:

• Inputs: Array of input parameter names
• Where: Optional conditions for the input combination
• Description: Description template for this input combination

[Entity]

Annotates action parameters to specify their semantic meaning and type.

Properties:

• Name: Semantic name of the entity
• Kind: Type of entity (from ActionEntityKind enumeration)

Advanced Features

Streaming Responses

Support real-time streaming of text responses:

[WindowsAction(Description = "Generate a story")]
public GetStoryResponse GenerateStory(string prompt, InvocationContext context)
{
    return new GetStoryResponse
    {
        StreamingText = new StreamingTextEntityWriter(
            ActionEntityTextFormat.Plain,
            textWriter => GenerateStoryAsync(textWriter, prompt)
        )
    };
}

private async Task GenerateStoryAsync(StreamingTextActionEntityWriter writer, string prompt)
{
    // Stream text as it's generated
    foreach (var chunk in GenerateTextChunks(prompt))
    {
        writer.SetText(chunk);
        await Task.Delay(100); // Simulate streaming delay
    }
}

Feedback Handling

Handle user feedback for your actions:

public async Task MyActionFeedback(ActionFeedback feedback, InvocationContext context)
{
    switch (feedback.Type)
    {
        case ActionFeedbackType.Positive:
            await LogPositiveFeedback(feedback);
            break;
        case ActionFeedbackType.Negative:
            await LogNegativeFeedback(feedback);
            break;
    }
}

Entity Factory Usage

Create various types of entities in your action responses:

public MyActionResult ProcessAction(InvocationContext context)
{
    var entityFactory = context.EntityFactory;
    
    return new MyActionResult
    {
        TextResult = entityFactory.CreateTextEntity("Processing complete"),
        NumberResult = entityFactory.CreateNumberEntity(42.0),
        // Add other entity types as needed
    };
}

Project Configuration

MSBuild Properties

The package supports several MSBuild properties for customization:

• GenerateActionRegistrationManifest: Generate action registration manifest
• ActionRegistrationManifest: Path to custom action registration manifest
• GenerateActionsWinRTComServer: Generate WinRT COM server code
• RootNamespace: Root namespace for generated code

Example in your .csproj file:

<PropertyGroup>
    <GenerateActionRegistrationManifest>true</GenerateActionRegistrationManifest>
    <GenerateActionsWinRTComServer>true</GenerateActionsWinRTComServer>
</PropertyGroup>

Requirements

• .NET 8.0 targeting Windows 10.0.26100.0 or later
• Windows 11 or later for full App Actions support
• Visual Studio 2022 or later (recommended)

Best Practices

1. Action Descriptions: Write clear, descriptive action descriptions that help users understand what the action does
2. Input Combinations: Define multiple input combinations to support different user scenarios
3. Entity Naming: Use semantic entity names that clearly indicate the parameter's purpose
4. Feedback Handling: Always implement feedback handlers to improve user experience
5. Error Handling: Implement robust error handling in your action methods
6. Performance: Keep action methods lightweight and responsive
7. Icons: Provide meaningful icons for better visual recognition

Troubleshooting

Common Issues

Build Errors: Ensure you're targeting the correct Windows SDK version. You might need to manually specify <WindowsSdkPackageVersion> for your project:

1. For projects targeting .NET 8.0 use <WindowsSdkPackageVersion>10.0.26100.59-preview</WindowsSdkPackageVersion>.
2. For projects targeting .NET 9.0 use <WindowsSdkPackageVersion>10.0.26100.60-preview</WindowsSdkPackageVersion>.

Actions Not Appearing: Verify that your action provider class is properly annotated and that the COM server registration is successful.

Entity Resolution: Check that entity names match between the [Entity] attribute and input combination definitions.

Support

For issues, questions, and contributions, please visit the Windows App Actions documentation or file issues in the appropriate GitHub repository.

License

This package is licensed under the MIT License. © Microsoft Corporation. All rights reserved.