Standalone Microservices

🚧

Preview Feature

Standalone Microservices are new! This feature is intended for developers who are comfortable with writing DotNet solutions.

Starting with Beamable 1.11.0, it is possible to use a Beamable Microservice outside of Unity. This comes with many advantages.

1. You can control the csproj and Dockerfile of your Microservice.
2. You can use Nuget packages.
3. You can select your version of dotnet.
4. You can run the service locally without docker if you prefer
5. Unity doesn't need to be able to compile the Microservice code.

Getting Started

You must have an existing Beamable organization and login available.
You will need to install the Beamable CLI and the Beamable Dotnet Templates to get started.

dotnet tool install --global beamable.tools
dotnet new --install beamable.templates

Verify your installation by confirming you can execute beam --version and that dotnet new --list --tag beamable yields three results. If you are using dotnet version 7, use dotnet new list --tag beamable

Now you can use the Beamable CLI to create a new Microservice and link it to a Unity project. The following command will create a new .sln file configured with a Beamable Microservice. It will also require you to log into Beamable.

In the final phase of the beam project new command, you will be asked if you want to link a Unity project. If you do, that Unity project will receive autogenerated .cs client files and common .dll files anytime the Standalone Microservice is built. You can link a project later too.

The second command will open the .sln file in your default editor.

beam project new Example
open Example/Example.sln

The Example.cs file contains the Microservice code. The Microservice class is equivalent to the ones from a Unity project. The same rules and conventions apply.

using Beamable.Server;

namespace Beamable.Example
{
	[Microservice("Example")]
	public class Example : Microservice
	{
		[ClientCallable]
		public int Add(int a, int b)
		{
			return a + b;
		}
	}
}

The Microservice can be run locally by running the Example project from your IDE, or by running dotnet run. You can use the IDE to debug, or use dotnet watch -- run to use hot reload.

You can open a swagger page to look at your local service by running

beam project open-swagger Example

To deploy the Microservice, use the following commands.

beam services ps --remote
beam services deploy

See the readme.md file for more details.

Adding a Unity Project

If you haven't already done so through the beam project new flow, you can add associated Unity or Unreal projects to your Standalone Microservice. Run this command from your Standalone Microservice folder. The argument should be the relative path to a local Unity project.

beam project add-unity-project ../../MyProject

Behind the scenes, this will give the Standalone Microservice a relative reference to the Unity project. Anytime the Microservice builds, it will automatically generate the client code in the Unity project.

In the linked Unity project, you can write code that accesses the autogenerated client.

var ctx = await BeamContext.Default.Instance;
var client = ctx.Microservices().Example();
var sum = await client.Add(1,2);

When you run the Unity client, it will send a request to your local running Standalone Microservice if it is running. If your Microservice is not running, then the request will be sent to the remote Microservice.

📘

Why are my Microservice requests are timing out?

If the requests are timing out in Unity, but you know for a fact your local Microservice is running, there may be a few things to check...

1. Make sure you are using Beamable 1.16 or later.
2. Make sure that Unity and your Standalone Microservice are using the same cid/pid.

Microstorage

In order to add a Microstorage object to a Standalone Microservice, run the following command from the recently created /Example folder. You will be prompted for which Microservices should depend upon the new Storage. Use the space key to select services.

beam project new-storage MyStorage

This will create a third project in the existing .sln. It will also modify the Dockerfile and .csproj file of any dependent service.

Microstorage objects will run automatically using Docker when you start a service that depends on the Microstorage object. You can see the running Microstorage object by checking docker ps, or using Docker Desktop.

You can view the local data by running the following command,

beam services run
beam project open-mongo MyStorage

For the microstorage to be deployed you need to run the following command,

beam services ps --remote  
beam services deploy

Note that after deploying the microstorage it will appear in the Beam portal but you will not be able to view it using Mongo Express View until you add at least one collection to it, so in order to get the connection string you need to run the following command,

beam services get-connection-string MyStorage --remote

You can use this MongoDB connection string with Mongo Compass, MongoDB command line tools, or any other program that is capable of connecting to MongoDB. Keep this connection string secret! It allows full read/write access to your Micro Storage.

Using the Common Library

The ExampleCommon project is a place to write code that will be shared with Unity and your Standalone Microservice. By default, this project has no dependencies. However, if you want to use Beamable primitives, such as Promise, you can add a Nuget package reference to Beamable.Common .

When you build the Standalone Microservice, it will automatically build and copy the common built .dll file into all linked Unity or Unreal projects.

Troubleshooting

• Missing .env file: If you are experiencing issues starting up your Microservice locally, it may be because you are missing relevant environment information (customer id, project id). To create one, cd to the specific microservice directory, and run beam login --save-to-file. This will prompt you to login and create a .envfile.