The Assistant Extension Interface, represented by IAssistantExtension, defines the structure and behavior of Assistant extensions. It is a fundamental part of developing custom tasks that enhance Assistant's functionality. This guide explains how to implement this interface and leverage it to create powerful extensions for Assistant.
The IAssistantExtension interface includes the following key components:
Args: A class that represents the input parameters for your extension. This class defines the data your extension requires to execute it's task.RunAsync: A method that encapsulates the logic of your extension. When Assistant invokes your extension, it calls the RunAsync method.Here's a basic example of an Assistant extension implementation:
namespace MyFirstExtension;
public class MyFirstExtensionCommand : IAssistantExtension<MyFirstExtensionArgs>
{
public async Task<IExtensionResult> RunAsync(IAssistantExtensionContext context, MyFirstExtensionArgs args, CancellationToken cancellationToken)
{
if (string.IsNullOrEmpty(args.TextInput))
return Result.Text.Failed("No input text provided");
// Create a message with the input text
var message = $"Input = {args.TextInput}";
// Await some delay to simulate async work
await Task.Delay(300, cancellationToken);
// Return a result with the message
return Result.Text.Succeeded(message);
}
}
In this example:
MyFirstExtensionArgs: Represents the input arguments needed by the extension.Result.Text.Succeeded and Result.Text.Failed: Represents the result of the extension's execution, indicating success or failure.To implement the IAssistantExtension interface in your extension:
Define a class for your extension. Make sure it specifies the input arguments.
Implement the RunAsync method, where you define the core logic of your extension. This method takes in an instance of the IAssistantExtensionContext, the input arguments, and a cancellation token.
Return an instance of the result class that you defined, providing the necessary data. The returned result should implement the IExtensionResult interface, allowing flexibility in choosing an appropriate result class.
This approach enables you to select the result class that best suits your extension's needs. It can be any class that adheres to the IExtensionResult interface.
One of the essential aspects of developing Assistant extensions is the ability to customize the input and output parameters to tailor them to the specific requirements of your task. This customization is achieved through two classes: the Args class, which represents input parameters, and the IExtensionResult interface, which represents the output of your extension.
The Args class allows you to define the input parameters required by your extension. It's where you specify the data that your extension needs to perform its task. You can further customize this class by adding properties to include extra input fields.
[Description] attribute to provide a human-readable description of the field. Additionally, you can use the [ControlData] attribute to specify a tooltip or define a custom input type. This is particularly useful when you need to customize the input fields to something other than the default control for the data type.For comprehensive documentation on customizing the Args class and the available attributes, refer to the Extension Args Class page.
To customize the output of your Assistant extension tasks, you can implement the IExtensionResult interface. This interface defines the structure and content of your extension's result. You can create custom result classes that fit your specific requirements, ensuring that the output aligns perfectly with your task's objectives.
IExtensionResult interface, you have the flexibility to create custom result classes. These classes allow you to define the structure and content of the output, set the result's success or failure status, and provide a text representation of the result.For comprehensive documentation on customizing the IExtensionResult interface and creating custom result classes, please refer to the IExtensionResult page.
By leveraging the IExtensionResult interface, you can ensure that the output of your Assistant extensions is tailored to your exact needs, offering meaningful results that seamlessly integrate with Assistant's environment. This flexibility is fundamental to building powerful and versatile extensions.
To build your Assistant extension, you have a couple of options:
It's important to note that you must have the "Automatic save" option enabled or manually save your changes before you reload or run the extension. This ensures that your extension is up-to-date and functions correctly during execution.
Debugging your Assistant extension is straightforward. Follow these steps:
Open your project in Visual Studio Code.
Press F5 or use the "Run and Debug" option in Visual Studio Code.
The debugger will attach to the open instance of Assistant, and you can start debugging your extension.
By following these steps, you can set breakpoints, inspect variables, and troubleshoot any issues in your extension's code effectively.
These building and debugging procedures streamline your development process, allowing you to create and test your extensions efficiently. Whether you're building new functionalities or modifying existing ones, debugging is a critical part of ensuring your extension works as expected.
In Assistant extensions, you can utilize variables to share data and settings across multiple tasks within a single action run. These variables allow you to pass information from one task to another, making it easier to orchestrate complex actions in Assistant.
To access a variable from a previous task within the same action run, you can use the AssistantExtensionContext. This context has methods to get and set variables.
Here's how you can access a variable in a subsequent task:
var myVariableValue = context.GetVariableValue("MyVariableName");
In this example, replace "MyVariableName" with the name of the variable you want to access.
Setting Variables
To set a variable in one task and use it in another, you can simply assign a value to a variable in the AssistantExtensionContext.
Here's an example of how to set a variable in one task and access it in another:
Task 1: Setting the Variable
context.SetVariableValue("MyVariableName","NewValue");
Task 2: Accessing the Variable
var myVariableValue = context.GetVariableValue("MyVariableName");
In this example, "MyVariableName" represents the variable name, and "NewValue" is the value set in Task 1. Task 2 can access this value.
Using variables across tasks enables you to create workflows where information flows seamlessly between different steps of an action run, making your extensions more powerful and versatile.
For more details on using variables in Assistant, you can refer to the Assistant Documentation on Variables.
Note: Variables persist for the duration of an action run in Assistant and can be accessed and updated across all tasks within that action.
Assistant simplifies the authorization process by enabling you to preconfigure an IExtensionHttpClient with built-in support for various logins. This feature provides you with pre-authorized HTTP clients, streamlining the integration of authentication into your extensions.
For detailed instructions on utilizing this feature within your Assistant extension, please refer to the dedicated Pre-Authorized HTTP Clients page.
This page will guide you through the process of leveraging logins and configuring your extensions to work seamlessly with Assistant's supported login mechanisms.
In this guide, you've explored the world of Assistant .NET Extension Development. Here's a quick recap of what you've learned:
Prerequisites: You've discovered the essential prerequisites for developing Assistant extensions, including .NET, Visual Studio Code, and the C# extension for Visual Studio Code.
Creating Your Extension: You've learned to determine the type of extension you want to create, be it an Assistant Extension, Revit Extension, Tekla Extension, AutoCAD Extension, or Navisworks Extension.
Customizing Input and Output: You've delved into customizing the Args and Result classes, adding extra input and output fields, and using Attributes for more control.
Building Your Extension: Building your extension is essential, and you've understood how to do it manually or through Assistant's automation.
Debugging Your Extension: Debugging is vital for a smooth development process, and you've set up your debugging environment in Visual Studio Code.
Publishing Your Extension: Once your extension is ready, you've learned the process of publishing it to Assistant's Extension Repository.
Now, if you're eager to put your knowledge into practice and see the development process in action, dive into our "Sample Extension Walkthrough." It's a hands-on example where you'll create a simple "Hello World" extension step-by-step.