Table of Contents

Developing Automation scripts as Visual Studio solutions

  • An Automation script solution can contain multiple scripts, whereas a connector solution can only contain one single connector.

  • C# projects that contain the code for the C# Exe blocks of an Automation script can contain multiple .cs files. At compilation, the contents of those files will be combined into one Exe block.

  • DLL imports need to be configured on the C# project itself by adding references to the external components. These can be external DLL files (located in C:\DataMiner\ProtocolScripts or C:\DataMiner\Files) or other scripts in the same solution.

    Note

    If you want an external DLL file to be placed in a specific folder instead of C:\DataMiner\ProtocolScripts, then specify the full path to that folder in the DataMiner DLL Path property of that DLL file.

    As from DIS v2.42, this feature has been removed. If this is required for a particular use case, please contact Data Acquisition.

  • ​Up to DIS v2.40, it was only possible to refer to a library script Exe from within the same Automation script. As from DIS v2.41, in a Visual Studio solution, you can also add a reference to a project from another Automation script in the solution. DIS will then automatically add a scriptRef.

    See the following example, in which {SCRIPTNAME} is the name of the other script containing the library and {LIBRARYNAME} is the name of the library:

    <Param type="scriptRef">{SCRIPTNAME}:{LIBRARYNAME}</Param>

    As DIS will automatically add a scriptRef, developers will only need to add a reference to the project that represents the library.

Tip

For a video course on creating Visual Studio Automation script solutions, see DataMiner Automation on DataMiner Dojo.

Creating an Automation script solution

To create a new Automation script solution containing an initial Automation script, follow the instructions below.

In Visual Studio 2022, perform the following steps:

  1. Select File > New > Project.
  2. In the Create a new project pop-up window, select DataMiner Automation Script Solution.
  3. Enter the name and location of the solution, then click Next.
  4. Provide the name of the Automaton script and the author, and click Create.

In Visual Studio 2019, perform the following steps:

  1. Select File > New > DataMiner Automation Script Solution.

  2. Enter the name of the solution.

  3. Select the target folder.

    Note

    The default protocol solution folder and the default Automation script folder can both be specified in DIS Settings > Solutions.

  4. Select Create initial Automation script if you want the solution to contain a basic script with one Exe block.

  5. Click OK.

Note

If another solution is open when you perform step 1, you will be asked whether you want to save unsaved changes.

Creating a new script in a solution

To create a new script in an Automation script solution, do the following:

  1. Open the Automation script solution.
  2. Select File > New > New DataMiner Automation Script... or right-click a solution folder in the Solution Explorer and select Add > New DataMiner Automation Script...
  3. Enter the name of the new script.
  4. Click OK.

Importing an existing script that is stored on your local computer

To import an existing Automation script stored on your local computer into an Automation script solution, do the following:

  1. Right-click a solution folder in the Solution Explorer.
  2. Select Add > Existing DataMiner Automation Script.
  3. Select a least one Automation script file.
  4. Click Open.
Note

When you add existing scripts to an Automation script solution, they are automatically converted to the correct format. For each C# Exe block, a C# project is created, and the code in that C# Exe block is transferred to the newly created C# project.

Importing an existing script that is stored on the DataMiner Agent you are connected to

To import an existing Automation script stored on the DMA you are connected to into an Automation script solution, do the following:

  1. Right-click a solution folder in the Solution Explorer.
  2. Select Add > Import DataMiner Automation Script.
  3. Select a least one Automation script file.
  4. Click Open.
Note
  • This new Import DataMiner Automation Script option will only be available if DIS is connected to a DataMiner Agent.
  • When you add existing scripts to an Automation script solution, they are automatically converted to the correct format. For each C# Exe block, a C# project is created, and the code in that Exe block is transferred to the newly created C# project.

Saving a compiled script as a .dmapp package

A compiled Automation script can be saved as a .dmapp package.

To save a compiled Automation script

  1. Open the XML file containing the Automation script that you want to compile.
  2. Select File > Save Compiled Script As...
  3. In the Save As window, select a folder, enter a file name, and click Save.

The package will contain the Automation script as well as all required DLL files (e.g. DLL files of NuGet packages that are used in the Automation script).

Note

Prior to DIS 2.41, you can also save a compiled Automation script as an .xml file, by setting the type in the Save As window to *.xml.

Saving all compiled scripts in a solution in a .dmapp package

To save a compiled version of all Automation scripts in a solution in a .dmapp package (with all C# code in their Exe blocks and required DLL files), do the following:

  1. Open the XML files containing the Automation scripts that you want to compile.
  2. Select File > Save All Compiled Scripts As...
  3. Enter a file name and a folder.
  4. Click Save.
Note

Prior to DIS 2.41, the scripts are saved in a .zip file instead.

Uploading a script to a DataMiner Agent

To upload an Automation script to a DataMiner Agent, do the following:

  1. Open the XML file containing the Automation script.
  2. Click Publish to compile the script and publish it to the DataMiner Agent that was set as default DMA in the DMA tab of the DIS Settings dialog box.
Note

If you want to publish the script to another, non-default DMA, click the drop-down button at the right of the Publish button, and click the DMA to which you want the file to be published.

Structure of an Automation script solution

An Automaton script Visual Studio solution is organized into various folders, each serving a specific purpose:

  • CompanionFiles: This folder allows you to add additional files that need to be installed along with the Automation script as part of an installation package.

  • Dlls: This folder contains the additional assemblies used by the Automation scripts. These assemblies are not part of DataMiner but are essential for one of the Automation scripts. Placing them in this folder ensures that the required assemblies are readily available in the repository alongside the Automation script XML files.

  • Documentation: This folder allows you to add documentation related to the solution.

  • Internal: This folder contains the C# Class Library Visual Studio project for the class library code (AutomationScript_ClassLibrary). Obsolete from DIS v2.41 onwards. This folder is hidden by default as the code within it is generated automatically and should not be modified.

    Note

    From DIS v2.41 onwards, an information bar will appear when a Class Library project (i.e. a project named "AutomationScript_ClassLibrary") is detected in an Automation script solution. This information bar provides the option to convert existing solutions that use of the Class Library generation feature. By clicking Fix, the Class Library project will be removed, and references to the project will be replaced with references to the automatically generated Class Library project (default ID 63000).

  • Scripts: This folder contains subfolders, with each subfolder representing an individual Automation script. The name of each subfolder corresponds with the name of the Automation script. Inside each subfolder, you will find the XML file for the Automation script and a subfolder named "Actions". The Actions folder contains the C# projects for each C# Exe block present in the Automation script.

  • Tests: This folder is intended for test projects.

    Note

    Test projects should only be integrated into Automation script solutions for the purpose of testing Automation script functionality. They should not be used for system tests that include e.g. other Automation scripts, among other things.

Propose changes