Setup and installation

Setup and installation: Worker SDK in C# bindings



Supported runtimes

  • The Worker SDK C# bindings are built to target .NET Framework 4.5. In practice, this means that they should be compatible with most runtimes including .NET Framework 4.5+ on Windows, Mono 4.0+ and .NET Core 2.0 (via compatibility mode).
  • The C# assembly also depends on the C SDK library improbable_worker at runtime and calls into it via P/Invoke.
  • The C SDK library is 64-bit, 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 new MSBuild format designed for .NET Core or Visual Studio 2017, and they require a .NET Core runtime to run. To use the older MSBuild format with Visual Studio 2015, or to use a different .NET runtime, you'll need to create your own project file and either disable generated build scripts or use the flexible project layout.


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 the msbuild toolset. The SpatialOS deployment clusters have version or newer installed, which is the environment that server-worker instances run in.

Install Mono using the installation guides (Windows/macOS/Linux).

Note that the macOS version of Mono is distributed as a universal binary, which requires --arch=64 to be passed to the command line when launching your worker instance.

Unity with IL2CPP

For more information about IL2CPP bytecode stripping in Unity and how to customise the engine's link.xml file, refer to the Unity documentation.

The Worker SDK C# bindings are known to work well with Unity's IL2CPP runtime. However, if you implemented your own custom codegen, you might run into an issue where Unity automatically strips out unreachable CLR bytecode when creating the final executable. This can cause the Connection to not work correctly, as reflection during initialization can no longer find the classes generated from your schema.

To work around this problem, you can provide a file called link.xml to control the behaviour of IL2CPP's bytecode stripping:

  1. In Unity, add a file called link.xml into the Assets folder, if not already present.
  2. Add the name of the assembly containing your generated code to link.xml to tell
    Unity to preserve the bytecode of the generated code. For example, if the assembly is called GeneratedCode.dll, the link.xml should contain:
    <assembly fullname="GeneratedCode" preserve="all"></assembly>


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 SpatialOS 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_cinterop 14.3.0

The Worker SDK C# bindings are a combination of two components: a C# assembly called Improbable.Worker.CInterop.dll, plus the corresponding dynamic C SDK package for your platform.

The table below lists all the packages you can retrieve, relevant to the Worker SDK C# bindings:

Package name Arch Build type More information
csharp_cinterop x86_64 C# assembly Targeting .NET Framework 3.5 (compatible with .NET Standard 2.0 via compatibility mode)

Setting up a worker type using the SpatialOS build system

If you're using the flexible project layout, you don't need to do this.

To add a C# worker type 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": "",
"generated_build_scripts_type": "csharp_bindings"
"bridge": {
"worker_attribute_set": {
  "attributes": [
"entity_interest": {
  "range_entity_interest": {
    "radius": 2
"streaming_query": [],
"component_delivery": {
  "default": "RELIABLE_ORDERED",
  "checkout_all_initially": true

See the contents of (after running a build) to understand what commands are invoked during spatial build.

  1. The default build setup expects a CsharpWorker.csproj in the same directory. Alongside this, it automatically generates the following build scripts and files:
    • CsharpWorker.sln
    • BuildTargets.targets
    • CsharpWorker.targets
    • spatialos_worker_packages.json
      You control this CsharpWorker.csproj file, and it should give you enough flexibility without the need to turn off the automatically generated build scripts. You can choose any name for the assembly - this will become the name of the worker type and the executable.

Below is a seed csproj file that you should start with.

<?xml version="1.0" encoding="utf-8"?>
<Project Sdk="Microsoft.NET.Sdk">

  <Import Project="BuildTargets.targets" />
  <Import Project="CsharpWorker.targets" />


The csproj is set to build an executable, so you need to provide a static int Main(string[] args) (see the Microsoft documentation) 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 causes 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, see Using custom build scripts.

Build your worker using spatial worker build or spatial worker build <worker type>.

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

Launch your worker using dotnet CsharpWorkerName.dll. Configure server-worker instances to be launched this way in the launch configuration field of the worker configuration file.

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.

2019-11-25 Page added with limited editorial review.

Updated about a year ago

Setup and installation

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.