Tutorial Create Plugin

Tutorial - Creating a Plugin/Extension

⮜ Extensibility | ⮨ Back to the Index | ➤ Contributing

Note: If you want to create a language pack for the Interpreter, check out the previous article about the Interpreter's extensibility.

This page explains how the AutoIt Interpreter may be extended using custom plugins. [TODO]

Plugin Providers

Plugin providers are assembly files (.dll or .exe) which define a set of classes which implement a standardized interface. When starting the AutoIt Interpreter, the internal plugin loader module searches for all .dlls in the plugin/-directory and instantiates the defined classes. The following steps describe how a plugin provider is created:

1. Download the newest version of the AutoIt Interpreter from the release page or build the Interpreter from the source cloned code. The following tutorials assume that the Interpreter has been downloaded to C:/Programs/AutoIt3/.

2. Start Visual Studio and click Create a new .NET Core project. Select a class library as the project type. The language can be C#, F#, VB.NET or any .NET Core-compatible language. The following steps assume the C# language.

3. Click on Next and give the plugin a (recognizable) name.

4. Click again on Next and select .NET Core 5.0 (or above) as the target framework. Click on Finish to create the project.

5. Inside the Solution Explorer, go to your project file (e.g. MyAutoIt3Plugin) and open the XML representation of the project file using a double click.
   

6. Replace the existing XML code with the following:

   <Project Sdk="Microsoft.NET.Sdk">
       <PropertyGroup>
           <TargetFramework>net5.0</TargetFramework>
           <Nullable>enable</Nullable>
           <OutDir><!--
               Replace this comment with the path to the "plugin/"-directory of the AutoIt Interpeter
               downloaded from https://github.com/Unknown6656/AutoIt-Interpreter/releases.
               This tutorial assumes the path to be "C:/Programs/AutoIt3/plugin/".
           --></OutDir>
           <LangVersion>preview</LangVersion>
           <Deterministic>true</Deterministic>
           <PublishTrimmed>true</PublishTrimmed>
           <AutoGenerateBindingRedirects>false</AutoGenerateBindingRedirects>
           <ProduceReferenceAssembly>false</ProduceReferenceAssembly>
           <GenerateSerializationAssemblies>Auto</GenerateSerializationAssemblies>
           <DisableWinExeOutputInference>true</DisableWinExeOutputInference>
           <AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
           <AppendRuntimeIdentifierToOutputPath>false</AppendRuntimeIdentifierToOutputPath>
           <SatelliteResourceLanguages>en</SatelliteResourceLanguages>
       </PropertyGroup>
       <ItemGroup>
         <Reference Include="autoit3">
           <HintPath><!--
               Replace this comment with the path to the "autoit3.dll"-file of the AutoIt Interpeter
               downloaded from https://github.com/Unknown6656/AutoIt-Interpreter/releases.
               This tutorial assumes the path to be "C:/Programs/AutoIt3/autoit3.dll".
           --></HintPath>
         </Reference>
       </ItemGroup>
   </Project>

7. Open the existing Class1.cs file or a new class file using Add > New Item > Class. You may rename the code file e.g. to Plugin.cs. Replace the existing C# code with the following lines:

   using Unknown6656.AutoIt3.Extensibility;
   
   [assembly: AutoIt3Plugin]

   These lines indicate that the plugin loader shall inspect the generated .dll plugin file and search for compatible plugin providers.

8. Click on Compile Project.

You now have an empty .dll, which will be accepted by the AutoIt Interpreter as a valid plugin provider. Please refer to the following sections for the creation of custom functions, macros, and syntaxes.

Custom Functions

Custom (native, aka. "built-in") functions can be provided as follows:

1. Right-click the project file and use Add > New Item > Class to create a new class. Give this class a name, e.g. MyFunctions.

2. Replace the existing C# code with the following code lines:

   using Unknown6656.AutoIt3.Extensibility;
   using Unknown6656.AutoIt3.Runtime.Native;
   using Unknown6656.AutoIt3.Runtime;
   
   namespace MyAutoIt3Plugin
   {
       public class MyFunctions
           : AbstractFunctionProvider
       {
           public MyFunctions(Interpreter interpreter)
               : base(interpreter)
           {
           }
       }
   }

   This file now represents a function provider, which does not yet define a new function.

3. To define and register a new function, create a new function with the following signature:

   private static FunctionReturnValue MyFunction(CallFrame frame, Variant[] arguments)
   {
       // function logic goes here
   }

   Call the RegisterFunction method from the constructor to register the defined function:

   public MyFunctions(Interpreter interpreter)
       : base(interpreter)
   {
       RegisterFunction(nameof(MyFunction), 0, MyFunction);
   }

   The RegisterFunction method has the following overloads:

   • void RegisterFunction(string, int, Func<CallFrame, Variant[], FunctionReturnValue>):
     This method takes 3 arguments: The function's name, the number of arguments which the function takes, and the function pointer.
   • void RegisterFunction(string, int, Func<CallFrame, Variant[], FunctionReturnValue>, OS):
     This method takes 4 arguments: The function's name, the number of arguments which the function takes, the function pointer, and the operating systems which the function supports (e.g. OS.Any, OS.Windows, OS.UnixLike, OS.MacOS, or OS.Linux).
   • void RegisterFunction(string, int, int, Func<CallFrame, Variant[], FunctionReturnValue>, params Variant[]):
     This method takes 5 arguments: The function's name, the minimum number of arguments which the function takes, the maximum number of function arguments, the function pointer, and the default parameters. The size of the default parameters array must match the difference between the minimum and maximum argument count.
   • void RegisterFunction(string, int, int, Func<CallFrame, Variant[], FunctionReturnValue>, OS, params Variant[]):
     This method takes 6 arguments: The function's name, the minimum number of arguments which the function takes, the maximum number of function arguments, the function pointer, the operating systems which the function supports (e.g. OS.Any, OS.Windows, OS.UnixLike, OS.MacOS, or OS.Linux), and the default parameters. The size of the default parameters array must match the difference between the minimum and maximum argument count.

4. Extend the function logic, e.g. as follows:

   private static FunctionReturnValue MyFunction(CallFrame frame, Variant[] arguments)
   {
       frame.Print($"This is my first custom function!\nThe current time is {DateTime.Now}.\n");
   
       return Variant.Zero;
   }

   Errors can be return using:

   return FunctionReturnValue.Error(-1, Variant.FromString("extended value"));
   //                                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^--- the value to be stored in the @extended macro
   //                               ^^----------------------------------------- the error code to be stored in the @error macro

   The @extended macro can also be set using:

   return FunctionReturnValue.Success("return value", "extended value");
   //                                                 ^^^^^^^^^^^^^^^^--- the value to be stored in the @extended macro
   //                                 ^^^^^^^^^^^^^^--------------------- the regular return value

5. Compile the project and place the resulting .dll file into the plugins/ folder. The defined function is now available from .au3-scripts and from the interactive shell:
   
   

Custom Macros

Macros are provided analogously to functions using a custom provider class.

1. Create a new C# class file and replace the existing code with the following snippet:

   using Unknown6656.AutoIt3.Extensibility;
   using Unknown6656.AutoIt3.Runtime;
   
   namespace MyAutoIt3Plugin
   {
       public class MyMacros
           : AbstractKnownMacroProvider
       {
           public MyMacros(Interpreter interpreter)
               : base(interpreter)
           {
               RegisterMacro(nameof(MyMacro), MyMacro);
           }
   
           private static Variant MyMacro(CallFrame frame)
           {
               Variant value = "Hello, World!"; // macro logic goes here
   
               return value;
           }
       }
   }

   This code creates a new macro provider called MyMacros. The constructor of this macro provider registers the MyMacro function as a new macro. Macros with a constant value may also be registered with the RegisterMacro(string name, Variant value) method.

2. Compile the project and place the resulting .dll file into the plugins/ folder. The defined macro is now available from .au3-scripts and from the interactive shell:
   

Custom Include Resolvers

[TODO]

Custom #pragma Preprocessors

[TODO]

Custom Directives

[TODO]

Custom Syntaxes

[TODO]

1. Create a new C# code file and name it MySyntaxes.

2. Replace the existing code with the following:

   using System.Text.RegularExpressions;
   using Unknown6656.AutoIt3.Extensibility;
   using Unknown6656.AutoIt3.Runtime;
   
   namespace MyAutoIt3Plugin
   {
       public class MyCustomSyntax
           : AbstractStatementProcessor
       {
           public override Regex Regex { get; } = new(@"^:-?[\(\)]$", RegexOptions.Compiled);
   
   
           public MyCustomSyntax(Interpreter interpreter)
               : base(interpreter)
           {
           }
   
           public override FunctionReturnValue ProcessStatement(CallFrame frame, string statement)
           {
               if (statement is ":)" or ":-)")
                   frame.Print("I'm happy!");
               else if (statement is ":(" or ":-(")
                   frame.Print("I'm sad!");
   
               return Variant.Zero;
           }
       }
   }

   This class provides a custom syntax for expression statements. A statement processor must define the public property Regex which returns a regular expression for the recognized statement. The method ProcessStatement is invoked by the interpreter every time a statement matches the specified regular expression. The example above prints the strings "I'm happy!" or "I'm sad!" depending on the processed line.

3. Compile the project and place the resulting .dll file into the plugins/ folder. The defined syntax is now available from .au3-scripts and from the interactive shell:
   

   The following screenshot shows the error message encountered when no plugin has been loaded handling the syntax ^:-?[\(\)]$: