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.
Assistant extensions can work with two different kinds of variables:
These two kinds of variables serve different purposes, and it is useful to treat them separately when building extensions.
Built-in variables are values that Assistant already knows when your extension starts. They are read-only from the extension's point of view, which means an extension can access them but cannot modify them. They are not created with SetVariableValue. Instead, you access them through dedicated methods on IAssistantExtensionContext.
Typical examples include:
You can access these built-in values directly from IAssistantExtensionContext, for example:
var integrationAutoCAD = context.GetIntegration(Integration.AutoCAD);
var mainRun = context.GetMainRun();
var currentRun = context.GetCurrentRun();
var trigger = context.GetTrigger();
var fileTrigger = trigger as IFileTrigger;
You can use the same pattern to read more detailed built-in values, for example groups, actions, tasks, and file-trigger metadata.
Use built-in variables when your extension needs information about the current Assistant environment, run, integration, or trigger that caused the extension to run, but does not need to change that information.
For more details on built-in variables in Assistant, refer to the Built-In Variables page.
User variables are values that you store yourself during an action run so later tasks can reuse them. These variables persist for the duration of the current action run and can be accessed and updated across all tasks within that run.
To read a user variable:
string? myVariableValue = context.GetVariableValue("MyVariableName");
To set a user variable:
context.SetVariableValue("MyVariableName", "NewValue");
Example flow:
Task 1 sets the variable:
context.SetVariableValue("MyVariableName", "NewValue");
Task 2 reads the variable:
string? myVariableValue = context.GetVariableValue("MyVariableName");
Use user variables when one task produces a value that another task in the same action should consume.
For more details on user variables in Assistant, refer to the User Variables page.
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.