# Getting Started

When creating an OpenTAP plugin you are essentially creating a dll that implements specific OpenTAP plugin types, such as the test step or DUT types. The dll can enforce one or more plugin types and it can be packaged and versioned, thus creating an OpenTAP package with the .TapPackage file extension that you can share with the community using the package manager.

To make it easier to develop plugins we created two options you can choose from when creating a project and plugin templates:

  • Using the OpenTAP NuGet Package - This is the recommended way to get OpenTAP if you are developing plugin projects. The NuGet package is available on nuget.org (opens new window).
  • Using the OpenTAP SDK Package - This provides templates for many types of common OpenTAP plugins and can be used via:
    • The OpenTAP Visual Studio Integration - This allows you to use Visual Studio to create your plugins. You need Visual Studio 2022 or newer. If you are using the KS8400A PathWave Test Automation Developer's System, this is already included. Otherwise, it can be downloaded from the the Visual Studio Marketplace (opens new window).
    • The Command Line - This allows you to create project code templates from the command line. You can learn how in The OpenTAP SDK Templates section.

# NuGet Package

The OpenTAP NuGet Package has several helpful features for plugin development. You can start a new project or you can turn an existing project into a plugin. Any C# project (*.csproj) can be turned into a plugin project by adding a reference to the OpenTAP NuGet package.

# Create a Project

You need a C# project to hold your plugin classes. This can be an existing project, or you can start a new one. To start a new one we recommend choosing "Class Library (.NET Standard)" in the Visual Studio "Create a new project" wizard.

# Reference OpenTAP

Since the OpenTAP NuGet package is available on nuget.org (opens new window) Visual Studio lists it in the "Browse" tab of the NuGet package manager. You can get to that by right clicking your project in the Solution Explorer and selecting "Manage NuGet Packages...". In the NuGet package manager, search for OpenTAP, and click install.

# NuGet Features

The OpenTAP NuGet package has a couple of additional built-in MSBuild features. These are discussed below.

# Installation

When your project references the NuGet package, OpenTAP will automatically be installed in your project's output directory (e.g. bin/Debug/). The installation will be the version of OpenTAP specified in your project file (e.g. using the VS NuGet package manager as described above). This feature makes it easier to manage several plugins that may target different versions of OpenTAP. The version of OpenTAP is recorded in the *.csproj file, which should be managed by version control (e.g. git), so all developers use the same version.

# Package Creation

The NuGet package also adds build features to help packaging your plugins as a *.TapPackage for distribution through OpenTAP's package management system (e.g. by publishing it on packages.opentap.io (opens new window)). To take advantage of these features, your project needs a package definition file (normally named package.xml). You can use the command line tap sdk new packagexml to generate a skeleton file. As soon as a file named package.xml is in your project, a TapPackage will be generated when it is built in Release mode. You can customize this behavior using these MSBuild properties in your csproj file:

<OpenTapPackageDefinitionPath>package.xml</OpenTapPackageDefinitionPath>
<CreateOpenTapPackage>true</CreateOpenTapPackage>
<InstallCreatedOpenTapPackage>true</InstallCreatedOpenTapPackage>
1
2
3

# Reference Other OpenTAP Packages

When using the OpenTAP NuGet package, you can reference other TapPackages you need directly. TapPackages referenced like this will be installed into your projects output directory (usually ./bin/Debug/) along with OpenTAP itself.

You can specify an OpenTAP package that your project should reference. You do this by adding the following to your csproj file:

<ItemGroup>
  <!-- OpenTAP package sources -->
  <OpenTapPackageRepository Include="packages.opentap.io"/>
  <OpenTapPackageRepository Include="$HOME/Downloads;$HOME/Documents"/>

  <!-- Packages to reference  -->
  <OpenTapPackageReference Include="DMM API" Version="2.1.2" UnpackOnly="false" IncludeAssemblies="pattern1;pattern2" ExcludeAssemblies="pattern3;pattern4" />
</ItemGroup>
1
2
3
4
5
6
7
8

This is similar to the way you add a NuGet package using <PackageReference/>. The <OpenTapPackageRepository/> element is similar to the concept of NuGet Sources (opens new window). It specifies from where OpenTAP packages should be resolved. The element can be specified multiple times, or the repository sources can be separated by a semicolon (;). All instances of this element will be joined during compilation. Http repositories and directory names are both valid sources. packages.opentap.io is always included by default, and cannot be excluded. It is included here only as an example.

When referencing a package in this way, assemblies belonging to that package are automatically referenced in your project.

All attributes except Include are optional. Version defaults to the latest release if omitted. UnpackOnly defaults to false, and can be used to suppress any install actions from running as part of the package being installed in the output dir.

The IncludeAssemblies and ExcludeAssemblies attributes control which assemblies are referenced. The supplied value is interpreted as one or more glob patterns, separated by semicolons (;). If not specified, they use the default values IncludeAssemblies="**" and ExcludeAssemblies="Dependencies/**", meaning that all DLLs from the package are referenced if they are not in a subdirectory of the Dependencies folder. By leveraging glob patterns, your project can target specific dependencies of other packages.

Glob patterns are tested in order of specificity, meaning that the evaluation order of patterns in IncludeAssemblies and ExcludeAssemblies can be interleaved. Specificity is measured by the number of tokens used in the expression. By tokens, we mean the components of the expression, and not the characters. The components of "Dependencies/**" are ["Dependencies", "/", "**"], for instance. Because Dependencies/** is more specific than **, no DLLs in the Dependencies folder are referenced by default.

Building on this, the pattern Dependencies/*AspNet*/** will match all ASP.NET dependencies that the referenced package contains, and will take precedence over the default exclude pattern because it contains more components, and is thus more specific. In case of ties, Include patterns take precedence over Exclude patterns.

There is one exception to this rule: any pattern ending with .dll, except patterns ending with *.dll, are considered literal expressions, and will always take precedence regardless of the number of tokens, thus allowing for easily targeting a specific dll by using a pattern like **NameOfDll.dll. Note however that specifying an empty pattern, e.g. ExcludeAssemblies="", will not override the default value of this attribute, and will still exclude Dependencies/**. In order to not include or exclude anything, you must provide a placeholder value instead.

Note that OpenTAP uses the DotNet.Glob (opens new window) library to generate matches, which uses unix-like globbing syntax.

You can also specify a package that you just want installed (in e.g. bin/Debug/) but don't want your project to reference. This can be useful for defining a larger context in which to debug. It is done as follows:

<ItemGroup>
  <AdditionalOpenTapPackage Include="DMM Instruments" Version="2.1.2"/>
</ItemGroup>
1
2
3

# SDK Package

The Software Development Kit (SDK) package demonstrates the core capabilities of OpenTAP and makes it faster and simpler to develop your solutions. It also contains the Developer Guide which contains documentation relevant for developers.

The package is available on packages.opentap.io (opens new window). You can use the CLI install the package with the following command:

tap package install SDK
1

If you are using the Keysight Developer's System (Community or Enterprise Edition) you already have the SDK package.

# SDK Templates

The OpenTAP SDK makes it easy to create plugin templates using the tap sdk new group of subcommands. From the command line you can call the following subcommands:

Commands Description
tap sdk gitversion Calculates a semantic version number for a specific git commit.
tap sdk new cliaction Create a C# template for a CliAction plugin. Requires a project.
tap sdk new dut Create a C# template for a DUT plugin. Requires a project.
tap sdk new instrument Create C# template for an Instrument plugin. Requires a project.
tap sdk new packagexml Create a package definition file (package.xml).
tap sdk new resultlistener Create a C# template for a ResultListener plugin. Requires a project.
tap sdk new settings Create a C# template for a ComponentSetting plugin. Requires a project.
tap sdk new testplan OBSOLETED: Use an editor (opens new window) to create a TestPlan.
tap sdk new teststep Create a C# template for a TestStep plugin. Requires a project.
tap sdk new project Create a C# Project (.csproj). Including a new TestStep, solution file (.sln) and package.xml.
tap sdk new integration gitlab-ci Create a GitLab CI build script. For building and publishing the .TapPackage in the given project.
tap sdk new integration gitversion Configure automatic version of the package using version numbers generated from git history.
tap sdk new integration vs Create files that enable building and debugging with Visual Studio.
tap sdk new integration vscode Create files to enable building and debugging with vscode.

The following example shows how to create a new project using the SDK:

tap sdk new project MyAwesomePlugin
1

This command creates a new project called MyAwesomePlugin with a .csproj file, a test step class, a solution file, and a package.xml file.

Once you created a project you can easily add other templates. To add a DUT for example simply call the following command:

tap sdk new dut MyNewDut
1

Use an editor to create a testplan to use your new teststep and DUT! See https://doc.opentap.io/User%20Guide/Editors/ for more info on the different editors!

# SDK Examples

Before you start to create your own project, look at the projects and files in TAP_PATH\Packages\SDK\Examples. This folder provides code for example DUT, instrument and test step plugins. First-time OpenTAP developers should browse and build the projects, then use e.g. the Editor GUI to view the example DUTs, instruments and test steps.

SDK Examples contains the following projects:

Folder Description
ExamplePlugin\ExamplePlugin.csproj Creates a plugin package that contains one DUT resource, one instrument resource, and one test step.
PluginDevelopment\PluginDevelopment.csproj Creates a plugin package that contains several test steps, DUT resources, instrument resources, and result listeners.
TestPlanExecution\BuildTestPlan.Api\BuildTestPlan.Api.csproj Shows how to build, save and execute a test plan using the OpenTAP API.
TestPlanExecution\RunTestPlan.Api\RunTestPlan.Api.csproj Shows how to load and run a test plan using the OpenTAP API.