Setup and installation

Setup and installation: Worker SDK in C#

Requirements

Prerequisites

Supported runtimes

The Worker SDK in C# is built to target .NET Framework 4.5. In practice, this means that it 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 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 generated build scripts type to specify that msbuild is used instead of xbuild. Otherwise, the csharp_xbuild 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.

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 for C# is known to work well with Unity's IL2CPP runtime. However, Unity automatically strips out unreachable CLR bytecode when creating the final executable. This can cause the Connection and Dispatcher 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:
<linker>
    <assembly fullname="GeneratedCode" preserve="all"></assembly>
</linker>

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.Worker.dll, plus the relevant dynamic C SDK package for your platform.

The table below shows the package you can retrieve, relevant to the Worker SDK for C#:

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

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"
},
"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_xbuild. If csharp is used, then msbuild will be used on all platforms to build the C# code.
Otherwise, if csharp_xbuild 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.

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

    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.

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

<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="12.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <!-- Note that order of imports of targets is important and should be preserved.
       In particular, BuildTargets.targets should be imported before Microsoft.Csharp.targets.
   -->
  <Import Project="BuildTargets.targets" />

  <PropertyGroup>
    <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
    <Platform Condition=" '$(Platform)' == '' ">AnyCPU</Platform>
    <ProjectGuid>{5F743C5A-5961-4406-83A9-3D97CB5FE4ED}</ProjectGuid>
    <OutputType>Exe</OutputType>
    <AssemblyName>CsharpWorkerName</AssemblyName>
    <TargetFrameworkVersion>v4.5.2</TargetFrameworkVersion>
    <FileAlignment>512</FileAlignment>
    <TargetFrameworkProfile />
  </PropertyGroup>

  <ItemGroup>
    <Reference Include="System" />
    <Reference Include="System.Core" />
    <Reference Include="System.Xml" />
    <Compile Include="src\**\*.cs" />
  </ItemGroup>

  <Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />
  <Import Project="CsharpWorker.targets" />
</Project>

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.

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.