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:
- Create a directory under
workers/
of your SpatialOS project (for example,workers/csharp
). 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 eithercsharp
orcsharp_msbuild
. Ifcsharp_msbuild
is used, thenmsbuild
will be used on all platforms to build the C# code. Otherwise, ifcsharp
is used, thenxbuild
will be used on all platforms instead. See the contents ofspatialos.csharp.build.json
(after running a build) to understand what commands are invoked duringspatial build
.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 astatic 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!"); } }
- Build your worker using
spatial worker build
orspatial worker build <worker type>
. - Add the worker to your SpatialOS application.
Assemblies produced by
spatial worker build
contain anexe
file with the assembly name set in yourcsproj
file. For example, the seed csproj produces assemblies containingCsharpWorkerName.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.