Microservices - DLLs

Create and deploy server-authoritative C# [CLCP-Microservices-06]

The purpose of this guide is for game makers to create and deploy server-authoritative C# functionality within their games with Beamable Microservices.

This guide includes everything needed to use the Microservices feature in the "Beamable SDK for Unity".


Related Feature

β€’ More details are covered in related feature page(s). See Microservices for more info.

Game Maker User Experience

There are 3 major parts to the process. During development, the game maker's user experience is as follows:


Follow these steps to get started:

Step 1. Setup Microservice

1. Setup Docker
2. Create Microservice
3. Call Microservice
β€’ See Adding Microservices for more info

Note: Here the implementation of the Microservice itself may be lean/empty. The goal is to demonstrate a Microservice call and response with no errors

Step 2. Import DLLs

The Beamable Microservices Feature works with DLL which is .Net-compatible (version "net45"). This includes a vast subset of .NET-compatible DLLs.

For the purposes of this demonstration, Amazon's DynamoDB will be used.


Amazon DynamoDB is a key-value and document database that delivers single-digit millisecond performance at any scale. It's a fully managed, multi-region, multi-active, durable database with built-in security, backup and restore, and in-memory caching for internet-scale applications. DynamoDB can handle more than 10 trillion requests per day and can support peaks of more than 20 million requests per second.

The process of integrating non-Amazon DLL's is similar. Use the steps below as a reference.

1. Locate & Download the primary DLL(s)β€’ Download from the developers (e.g. Amazon's DynamoDB Resources)

Note: This may download more or less than the set of DLL(s) for the project's needs.
2. Locate & Download any dependency DLL(s)There are 2 solution paths here. Choose the one path that works best for the needs of the project...

2.1 - Use Nuget In the Web Browser

β€’ Search the DLL at Nuget.org Resources)
β€’ Expand the 'Dependencies'
β€’ Download each dependency (and dependency of each dependency, etc...)
β€’ Rename the *.nupkg file to *.zip and unzip
β€’ Drag the *.dll file from the file system to any folder within the Unity Project Window.

Note: Some unzipped packages will include multiple copies of the DLL file. When in doubt, choose the 'net45' version.

2.2 - Or Use the NugetForUnity Package

β€’ See Github.com/GlitchEnzo/NuGetForUnity for more info
β€’ Search and import the DLLs needed

3. Add the DLL(s) to the Assembly Definition

β€’ Ensure Override References checkbox is ticked
β€’ Add each DLL to the appropriate Asmdef file

Note: Beamable creates an instance of a Unity's Assembly Definition (Asmdef) file for each Microservice

Step 3. Use DLLs

Work within the Microservice created in Step 1 above.

1. Add appropriate 'using' statementscsharp using Amazon.DynamoDBv2;

Note: Some code editors will auto-complete this step for you
2. Complete the implementationcsharp AmazonDynamoDBConfig config = new AmazonDynamoDBConfig();

Note: The details of this step will vary for each use case
3. "Build" the Microserviceβ€’ See Microservices Manager for more info
4. "Start" the Microserviceβ€’ See Microservices Manager for more info
5. Run the Unity sceneβ€’ Enjoy!

With each newly created Microservice, there is auto-generated code. This serves as a working template for the game maker, who will write the actual implementation.



Beamable SDK Examples

β€’ The following example code is available for download at GitHub.com/Beamable_Microservices_Examples

Project Window

The MyADBMicroserviceExample folder contains the DLL files, Scene, and Scripts for the complete example.



In this MyADBMicroserviceExample.cs example, the MyADBMicroservice.cs allows read/write access to the database.

using UnityEngine;
using Beamable.Server.Clients;

namespace Beamable.Examples.Features.Microservices.MyADBMicroserviceExample
    /// <summary>
    /// Demonstrates <see cref="Microservices"/>.
    /// </summary>
    public class MyADBMicroserviceExample : MonoBehaviour
        //  Properties  -----------------------------------
        //  Fields  ---------------------------------------
        private MyADBMicroserviceClient  _myAdbMicroserviceClient;
        //  Unity Methods  --------------------------------

        protected void Start()
            Debug.Log("Start() Instructions...\n" + 
            "* Complete docker setup per https://docs.beamable.com/docs/microservices-feature\n" +
            "* Start the server per https://docs.beamable.com/docs/microservices-feature\n" +
            "* Play This Scene\n" + 
            "* Enjoy!\n\n\n");
        //  Methods  --------------------------------------
        private async void SetupBeamable()
            var beamContext = BeamContext.Default;
            await beamContext.OnReady;

            Debug.Log($"beamContext.PlayerId = {beamContext.PlayerId}");
            _myAdbMicroserviceClient = new MyADBMicroserviceClient();
            // #1 - Call Microservice
            bool isSuccess = await _myAdbMicroserviceClient.ConnectToDatabase();
            // #2 - IsSuccess = true
            Debug.Log ($"ConnectToDatabase() IsSuccess = {isSuccess}");
using System;
using System.Threading.Tasks;
using Amazon;
using Amazon.DynamoDBv2;
using Amazon.Runtime;
using UnityEngine;

namespace Beamable.Server.MyADBMicroservice.MyADBMicroserviceExample
   public class MyADBMicroservice : Microservice
      public async Task<bool> ConnectToDatabase()
         // TODO: Create an account with https://aws.amazon.com/dynamodb/ 
         // TODO: And add your keys here
         string accessKey = "replace-with-your-access-key";
         string secretKey = "replace-with-your-secret-key";
            // Credentials
            var credentials = new BasicAWSCredentials(accessKey, secretKey);
            // Configuration
            var config = new AmazonDynamoDBConfig()
               RegionEndpoint = RegionEndpoint.USWest2
            // Client
            AmazonDynamoDBClient client = 
               new AmazonDynamoDBClient(credentials, config);
            Debug.Log($"CallADB() Success!");
         catch (Exception e)
            Debug.Log($"CallADB() Failure! Message = {e.Message}");
            return false;

         return true;



Here are hints to help explain some of the trickier concepts:

β€’ The MyADBMicroserviceExample.cs will compile and run as shown above. However,
β€’ The game maker must create an account with https://aws.amazon.com/dynamodb/ and update the C# code to use those credentials to properly connect with Amazon DynamoDB


Newtonsoft.JSON is a popular tool for handling JSON in dotnet. The internals of the Beamable Microservice already use Newtonsoft, but the type information is not available in Unity by default. However, as of 1.3.1, a custom Newtonsoft.Json dll file may be referenced and used within the Microservice code. When a custom Newtonsoft.Json is provided, it will override the existing source Beamable uses.

An easy to obtain a custom version of Newtonsoft.JSON is to reference Unity's standard UPM newtonsoft Package. Add this line to your manifest.json dependencies section.

"com.unity.nuget.newtonsoft-json": "3.2.1",

Then, in your Microservice's assembly definition file, add a reference to the now available dll.

Now you can take advantage of Newtonsoft in your Microservice.


Unity style serialization is still used for wire protocols!

Even if you have configured Newtonsoft in your Microservice, the inputs and outputs of [ClientCallable] methods will still use Unity style serialization. Therefor, you cannot use newtonsoft serialization techniques for inputs and outputs.