Sites

Menu
These are the docs for 13.8, an old version of SpatialOS. The docs for this version are frozen: we do not correct, update or republish them. 14.2 is the newest →

Setting up the Worker SDK in C#

Requirements

Prerequisites

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.

Note that Mono 5 has deprecated xbuild and distributes msbuild instead as a build toolset. If using generated build scripts, make sure you use the csharp_msbuild generated build scripts type to specify that msbuild is used instead of xbuild. Otherwise, the default csharp generated build scripts type will use xbuild on all three platforms, so will require Mono installed on Windows, in addition to Visual Studio 2015.

Install Mono using the mono-project.com 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.

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

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

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

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums