Microservices

Beamable offers a rich microservice development workflow using the Beam CLI and Dotnet. Microservices deploy to the Beamable Cloud, and offer a secure way to handle server-side authoritative logic for your games.

Dependencies

Before you can develop a Beamable Standalone Microservice, you need to complete the Getting-Started Guide. That means having Dotnet 8 installed, and getting the Beam CLI.

You can confirm you have everything installed checking the versions of the tools.

dotnet --version
dotnet beam version # beam --version also works.

Quick Start

Standalone Microservices require a .beamable workspace, so you either need to create one with beam init, or use an existing one.

beam init MyProject
cd MyProject

Once you have a .beamble workspace, you can create a new Standalone Microservice using the project new command.

# run this inside your .beamable workspace
dotnet beam project new service HelloWorld

A new file, BeamableServices.sln has been created in /MyProject. Open it in your IDE of choice (Visual Studio Code, Rider, or Visual Studio).

Congratulations, you have a local Beamable Standalone Microservice! To run it, you can use the IDE tooling to start the HelloWorld project, or you can use the project run command. If you're familiar with dotnet, you can also use the normal dotnet run command as well.

However you decide to run the project, you should see a stream of logs similar to the snippet below,

13:25:33.077 [DBUG] Service provider initialized
13:25:33.307 [DBUG] Event provider initialized
13:25:33.308 [INFO] Service ready for traffic.baseVersion=2.0.0-PREVIEW.RC2 executionVersion= portalURL=https://portal.beamable.com/cid/games/DE_1751365810229268/realms/pid/microservices/HelloWorld/docs?refresh_token=redacted&prefix=redacted

The service is running! You can send requests to the service over HTTPS. To verify, you can open the local Open API documentation by using the project open-swagger command.

dotnet beam project open-swagger

Your local web browser should open to the Beamable Portal, showing the local Open API documentation,

Click on the last green button that says, "POST /Add", and then select the "Try It Out" button. In the Request Body, enter some sample JSON,

{
  "a": 2,
  "b": 3
}

And then click the Execute button! In your Standalone Microservice project, you should see some logs appear indicating the service was invoked.

13:30:18.945 [DBUG] Handling Add

The Add function is defined in the HelloWorld.cs file.

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

You can write new functions and tag them with [ClientCallable] to make them accessible on the Open API page. And now you know the basics of working with Beamable Standalone Microservices!

Project Structure

Each file in the Standalone Microservice has a valuable function that is important to understand.

Next Steps

There are many topics to continue learning about Beamable Standalone Microservices,

• Deploy your Microservice to the Beamable Cloud
• Debugging Techniques
• Add a Beamable Database Storage Object
• Microservice Configuration Settings
• Beam CLI Commands for Managing Microservices
• Microservice Routing and Client Usage

Possible Issues and Solutions

Multiple Microservice Classes Detected

Explanation:
Only one Microservice class should exist per microservice project. Multiple classes marked with the [Microservice] attribute will cause conflicts in code generation and runtime behavior.

Example Code Triggering the Error:

[Microservice("MyMicroservice")]
public partial class MyMicroservice : Microservice {}

[Microservice("MyOtherMicroservice")]
public partial class MyOtherMicroservice : Microservice {}

Example Error Message:

Multiple Microservice classes detected. Make sure only a single class implementing Microservice exists in each service project. ClassNames=MyMicroservice, MyOtherMicroservice.

Solutions:

• Ensure only one class is marked as a Microservice in your project.

Example of Solved Code:

[Microservice("MyMicroservice")]
public partial class MyMicroservice : Microservice {}

Non-Partial Microservice Class Detected

Explanation:
Microservice classes must be marked as partial to allow code generation tools to extend them.

Example Code Triggering the Error:

[Microservice("MyMicroservice")]
public class MyMicroservice : Microservice {}

Example Error Message:

Non-Partial Microservice class detected. Make sure your Microservice class is marked as partial.

Solutions:

• Add the partial modifier to the class.

Example of Solved Code:

[Microservice("MyMicroservice")]
public partial class MyMicroservice : Microservice {}

Microservice Class Missing Microservice Id

Explanation:
The Microservice class must include the [Microservice("Id")] attribute to define its identifier.

Example Code Triggering the Error:

public partial class MyMicroservice : Microservice {}

Example Error Message:

Microservice class is missing the microservice id

Solutions:

• Add the [Microservice("Id")] attribute to the class.

Example of Solved Code:

[Microservice("MyMicroservice")]
public partial class MyMicroservice : Microservice {}

Async Void Callable Methods

Explanation:
Methods marked as [Callable], [ClientCallable], [ServerCallable] should not be async void. Using async void makes it impossible to track errors or await completion.

Example Code Triggering the Error:

[Microservice("MyMicroservice")]
public partial class MyMicroservice : Microservice 
{
    [Callable]
    public async void CallMicroservice() {}
}

Example Error Message:

Microservice Callable methods cannot be async voids. Ex: CallMicroservice.

Solutions:

• Change the return type to Task.

Example of Solved Code:

[Microservice("MyMicroservice")]
public partial class MyMicroservice : Microservice 
{
    [Callable]
    public async Task CallMicroservice() {}
}

Invalid Type Usage in Callable Method

Explanation:
Types used in [ClientCallable] methods must be available to both server and client. Declaring types inside the microservice class makes them inaccessible to the Unity client.

Example Code Triggering the Error:

[Microservice("MyMicroservice")]
public partial class MyMicroservice : Microservice 
{
        [ClientCallable]
    public async Task<DTO> CallServiceAsync() => new DTO { x = 1 };

    [ClientCallable]
    public void CallService(DTO data) {}
}

public class DTO
{
    public int x;
}

Example Error Message:

Microservice Callable method CallServiceAsync uses a Type that cannot be inside microservice scope. Type: DTO.

Solutions:

• Move shared types (DTOs, Enums, etc.) to a shared project referenced by both Unity and the server.

Example of Solved Code (Microservice):

[Microservice("MyMicroservice")]
public partial class MyMicroservice : Microservice 
{
    [ClientCallable]
    public async Task<DTO> CallServiceAsync() => new DTO { x = 1 };

    [ClientCallable]
    public void CallService(DTO data) {}
}

Shared Project Code:

public class DTO
{
    public int x;
}

Callable Method Types usage are Nested

Explanation:
Types used in [ClientCallable] methods must be declared in outer scope so the Source Code Generator can handle it properly.

Example Code Triggering the Error:

[Microservice("MyMicroservice")]
public partial class MyMicroservice : Microservice 
{
    public class DTO
    {
        public int x;
    }

    [ClientCallable]
    public void CallService(DTO data) {}
}

Example Error Message:

{nameof(Server.Microservice)} Callable method CallService uses a Type that is Nested, which is not supported by the Source Code Generator. Please move DTO to outer scope.

Solutions:

• Move named types used by Callable methods to a non-nested scope.

Example of Solved Code:

[Microservice("MyMicroservice")]
public partial class MyMicroservice : Microservice 
{
    [ClientCallable]
    public void CallService(DTO data) {}
}

public class DTO
{
    public int x;
}

Beam Generated Schema Class is a Nested Type

Explanation:
Classes that uses the attribute [BeamGenerateSchema] cannot be declared as nested type because the Source Generator Cannot handle it.

Example Code Triggering the Error:

[Microservice("MyMicroservice")]
public partial class MyMicroservice : Microservice 
{
    [BeamGenerateSchema]
    public class DTO
    {
        public int x;
    }
}

Example Error Message:

Type DTO contains [BeamGenerateSchema] attribute and is a Nested type, which is not supported by the Source Code Generator. Please move DTO to outer scope.

Solutions:

• Move classes that contains [BeamGenerateSchema] attribute to a non-nested scope.

Example of Solved Code:

[Microservice("MyMicroservice")]
public partial class MyMicroservice : Microservice { }

[BeamGenerateSchema]
public class DTO
{
    public int x;
}

Invalid Microservice ID

Explanation:
Microservices IDs must match the <BeamID> property on csproj. If there is none <BeamID> property it needs to match the project's name.

Example Code Triggering the Error:

[Microservice("MyMicroservice")]
public partial class MyMicroservice : Microservice {}

Example CSProj Triggering the Error:

<Project Sdk="Microsoft.NET.Sdk">
    ...
    <PropertyGroup Label="Beamable Settings">
        ...
        <BeamId>OtherBeamId</BeamId>
        ...
    </PropertyGroup>
    ...
</Project>

Example Error Message:

Microservice ID: `MyMicroservice` is invalid, it needs to be the same as <BeamId> csharp property (or as csproj name if none exist): `OtherBeamId`

Solutions:

• Switch Microservice attribute parameter to use the same value as <BeamId>
  Example of Solved Code:

  C#

  [Microservice("OtherBeamId")]
  public partial class MyMicroservice : Microservice { }
  
  [BeamGenerateSchema]
  public class DTO
  {
      public int x;
  }
  

• Update <BeamId> property to match the Microservice attribute value
  Example of Solved CSProj:

  XML

  <Project Sdk="Microsoft.NET.Sdk">
      ...
      <PropertyGroup Label="Beamable Settings">
          ...
          <BeamId>MyMicroservice</BeamId>
          ...
      </PropertyGroup>
      ...
  </Project>