Setting up the Worker SDK in C#

Requirements

Prerequisites

• Follow the SpatialOS tools installation guide (Windows / macOS / Linux). This is a prerequisite for using the Worker SDK.

• (Windows only) Visual C++ Redistributable for Visual Studio 2015, required for running workers locally.

• (if using generated build scripts) A 64-bit version of Mono.

Supported runtimes

The Worker SDK in C# is built to target .NET Framework 3.5. In practice, this means that it should be compatible with most runtimes including .NET Framework 3.5+ on Windows, Mono 4.0+ and .NET Core 2.0 (via compatibility mode). The C# assembly depends on a 64-bit native component called CoreSdkDll, which means that the C# runtime needs to be running in 64-bit mode to avoid a DllNotFoundException.

Note that the generated build scripts use the older MSBuild format designed for Visual Studio 2015 or Mono 5+. To use the new MSBuild format with .NET Core or Visual Studio 2017, you’ll need to create your own project file and either disable generated build scripts or use the flexible project layout.

Mono

If using Mono, make sure that you have the 64-bit version installed on your machine, and that it is present in your PATH environment variable. This should include the mono executable, the Mono runtime, and a build toolset, such as xbuild or msbuild. The SpatialOS deployment clusters have version 5.2.0.215 or newer installed, which is the environment managed workers will run in.

Install Mono using the mono-project.com installation guides (Windows / macOS / Linux).

Packages

You can obtain packages through worker packages, our package management framework. You can specify these packages in a spatialos_worker_packages.json if using the spatial build system, or, if you’re using the flexible project layout, you can download them manually by running spatial package get worker_sdk <package_name> <version> <destination zip> (for example: spatial package get worker_sdk csharp 13.6.2 csharp.zip).

The Worker SDK in C# is a combination of two components: a C# assembly called Improbable.WorkerSdkCsharp.dll and a native library called CoreSdkDll. The C# assembly calls into the native library via P/Invoke.

The tables below list all the packages you can retrieve, relevant to the Worker SDK for C#:

Setting up a worker using the SpatialOS build system

To add a C# worker to your project:

1. Create a directory under workers/ of your SpatialOS project (for example, workers/csharp).

2. Create a worker configuration file file (for example, workers/csharp/spatialos.MyCsharpWorker.worker.json) with the following contents:

   {
   "build": {
   "tasks_filename": "spatialos.csharp.build.json",
   "generated_build_scripts_type": "csharp_msbuild"
   },
   "bridge": {
   "worker_attribute_set": {
     "attributes": [
       "new_worker_attribute"
     ]
   },
   "entity_interest": {
     "range_entity_interest": {
       "radius": 2
     }
   },
   "streaming_query": [],
   "component_delivery": {
     "default": "RELIABLE_ORDERED",
     "checkout_all_initially": true
   }
   }
   }
   

   generated_build_scripts_type can be set to either csharp or csharp_msbuild. If csharp_msbuild is used, then msbuild will be used on all platforms to build the C# code. Otherwise, if csharp is used, then xbuild will be used on all platforms instead. See the contents of spatialos.csharp.build.json (after running a build) to understand what commands are invoked during spatial build.

3. The default build setup expects a CsharpWorker.csproj in the same directory alongside which it will automatically generate the following build scripts and files:

   • GeneratedCode.csproj
   • CsharpWorker.sln
   • BuildTargets.targets
   • CsharpWorker.targets
   • spatialos.csharp.build.json
   • spatialos_worker_packages.json

   This CsharpWorker.csproj file is controlled by you, and should provide you with enough flexibility without the need to turn off the automatically generated build scripts. You can choose any name for the assembly - this will then be the name of the worker and the executable.

   We provide a seed csproj file which you should start with.

   The csproj is set to build an executable, so you will need to provide a static int Main(string[] args) somewhere in the source code in order for the build to succeed.

   For example, you can create a src/Test.cs within the worker directory with the following contents:

   using System;
   class Test
   {
       static void Main()
       {
           Console.WriteLine("Hello World!");
       }
   }
   

   The generated_build_scripts_type field in the spatialos.MyCsharpWorker.worker.json file will cause all the files listed above as ‘automatically generated’ to be overwritten every time you run spatial worker build. If you absolutely need to modify these then you should have a look here.

   1. Build your worker using spatial worker build or spatial worker build <worker type>.
   2. Add the worker to your SpatialOS application.

   Assemblies produced by spatial worker build contain an exe file with the assembly name set in your csproj file. For example, the seed csproj produces assemblies containing CsharpWorkerName.exe.

   You should launch them using mono CsharpWorkerName.exe. Configure managed workers to be launched this way in the launch config.

   For more about the build setup, see Building a worker.

   If you see a DllNotFoundException and are using Mono, this may be because you’re running the 32-bit version (on macOS, mono can default to 32-bit).

   To ensure that SpatialOS SDK native libraries are loaded correctly, make sure you’re using the 64-bit version of Mono by:

   • Using the --arch=64 flag by passing it as the first argument, e.g. mono --arch=64 CsharpWorkerName.exe This flag is only valid for macOS versions of Mono.
   • Running mono64 directly.

Search results