Using the .NET Workflow SDK with VertiGIS Studio Workflow Server

VertiGIS Studio Workflow Server can be extended by augmenting your on-premises installation with additional custom .NET assemblies.

Requirements

Extending VertiGIS Studio Workflow Server requires administrative access to your on-premises installation of workflow.

Development Environment

Visual Studio 2022 is the only officially supported development environment for extending VertiGIS Studio Workflow Server.

Setting up a VertiGIS Studio Workflow Server Extension Project

Extending VertiGIS Studio Workflow Server requires you to produce a separate assembly with your custom activities, and copy that into your on-premises deployment of VertiGIS Studio Workflow. We first need to set up a project using Visual Studio that references the workflow runtime.

1. Launch Microsoft Visual Studio 2022.
2. Create a new project of type Class Library (.NET Standard)
   • You can also create a project of type .NET to take advantage of its larger feature set. If so, you need to go into the project settings and change the output type to Class Library
3. Edit the .csproj file in a text editor and add the CopyLocalLockFileAssemblies attribute to the PropertyGroup.

<PropertyGroup>
    <TargetFramework>netstandard2.1</TargetFramework>
    <RootNamespace>CustomWorkflow</RootNamespace>
    <CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>
</PropertyGroup>

• This will copy the referenced nuget assemblies to the build output folder, which will be important for later.

1. Add a reference to the VertiGIS.Workflow.Runtime assembly. By default, this is located inC:\Program Files\VertiGIS\VertiGIS Studio Workflow\Deployment\service

Important

.NET Standard projects must target .NET Standard 2.1, and .NET projects must target .NET 6.0, or else the assembly will be incompatible with VertiGIS Studio Workflow Server.

note

We recommend that you only implement the IActivityHandler interface examples provided in the Developer Center. These examples have been verified and are provided to help you customize your VertiGIS Studio product to suit your needs. You should not reference other classes and functions from the various VertiGIS Studio Workflow assemblies. Doing so could risk breaking functionality and/or unexpected results as a result of future changes.

Next, learn how to implement a custom activity for VertiGIS Studio Workflow Server.

Deploying VertiGIS Studio Workflow Server Activities

For VertiGIS Studio Workflow Server to find your custom activities, you need to copy the build output to a particular folder.

1. Build the project.
2. Find the build output on disk.
   1. In Visual Studio, right-click on your project in Solution Explorer and choose "Open Folder in File Explorer".
   2. Open the bin folder. If you do not see abin folder, it is possible you right-clicked on the solution instead of the project.
   3. In the bin folder, open either Debug or Release, depending on which build configuration you used.
   4. In the bin\Debug or bin\Release folder, there will be one final sub-directory which will be netstandard2.1 or net6.0. Open this folder.
   5. You should now see a number of files including VertiGIS.Workflow.Runtime.dll and your own project, such as AssemblyNamespace.dll.
3. Find the CustomAssemblies folder on disk.
   1. VertiGIS Studio Workflow looks in a folder called CustomAssemblies for assemblies that contain custom activities. This is located in the folder that you chose when installing VertiGIS Studio Workflow. The default location is C:\Program Files\VertiGIS\VertiGIS Studio Workflow\CustomAssemblies
4. Copy the relevant files from the build output to the CustomAssemblies folder.
   1. Copy your project's assembly. (e.g. AssemblyNamespace.dll)
   2. Copy any third-party libraries that your project relies on (these should have been output to the build folder)
   3. Copy any other configuration files or resources that your project relies on.
   4. Do not copy any files that start with VertiGIS.Workflow. They are not required in this folder.

note

If you created a .NET Project and see AssemblyNamespace.exe, you need to change the project output type to Class Library.

Important

You may need to stop VertiGIS Studio Workflow Server in IIS in order to copy your copy your custom code.

Debugging Server Workflow Activities

You can debug custom VertiGIS Studio Workflow Server activities by attaching to the VertiGIS Studio Workflow Server process from the VertiGIS Studio Workflow extension project you created.

1. Start Visual Studio 2022 with administrator privileges.
2. Attach the debugger to the w3wp.exe process that is running as the VertiGISStudioWorkflow user.
   • You may need to check 'show processes from all users' to see it.
   • If you have customized the application pool assigned to your installation of VertiGIS Studio Workflow, the username may be different.
3. Set a breakpoint in your custom activity.
4. Run your server workflow that uses the custom activity. Your breakpoint should be hit.

Automating Deployment of Server Workflow Activities

To automate the deployment to VertiGIS Studio Workflow Server, we have to add a post build step to the project that copies the build output.

1. Locate the Custom Assemblies folder in the VertiGIS Studio Workflow Server installation. The default location is C:\Program Files\VertiGIS\VertiGIS Studio Workflow\CustomAssemblies
2. Create a file excluded_files.txt at the root of the project that excludes the appropriate build output files as described in the deployment section.

VertiGIS.Workflow.Runtime.dll
VertiGIS.Workflow.Runtime.xml

2. Edit the post build event in the project properties.
   • Add a command which copies the build output to the Custom Assemblies folder.
   • xcopy "$(OutDir)*" "C:\Program Files\VertiGIS\VertiGIS Studio Workflow\CustomAssemblies" /Exclude:$(ProjectDir)excludedFiles.txt /y
3. Run a rebuild and ensure all appropriate files are copied.

Important

You may need to stop then restart VertiGIS Studio Workflow Server in order for the post build step to copy your custom code.

Next Steps

Check out the tutorials to learn how to build custom activities for VertiGIS Studio Workflow Server and augment them with third party libraries.

Implement a Custom Activity

Implement a custom activity for VertiGIS Studio Workflow Server

Get Started

Reference a Third Party Library

Reference a third party library in custom code.

Get Started