Microservice Configuration

Dependencies

Before you can configure Beamable Standalone Microservices, 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
beam version # beam --version also works.

In order to configure a Microservice, you also need to have a local .beamable workspace with a Beamable Standalone Microservice. As a reminder, you can create one quickly using the commands below.

beam init MyProject
cd MyProject
dotnet beam project new service HelloWorld

Project Configuration

Each Standalone Microservice is a dotnet project, and can be configured through the dotnet .csproj. In most IDEs, the .csproj file will be hidden automatically, but you can open it by right-clicking on the project in the IDE and opening the .csproj file. As of Beam CLI 3.0.0, the starting .csproj has the following structure.

<Project Sdk="Microsoft.NET.Sdk">  
    <PropertyGroup Label="Beamable Settings">  
        <!-- All Microservices must have the value, "service" -->  
        <BeamProjectType>service</BeamProjectType>  
  
        <!-- When "true", this will auto-generate client code to any linked unity projects -->  
        <GenerateClientCode>true</GenerateClientCode>  
    </PropertyGroup>  
    <!-- These are special Beamable parameters that we use to keep the beamable packages in-sync to the CLI version your project is using. -->  
    <!-- This makes it so your microservices are auto-updated whenever you update the CLI installed in your project. -->    <PropertyGroup Label="Beamable Version" Condition="$(DOTNET_RUNNING_IN_CONTAINER)!=true">  
        <DotNetConfigPath Condition="'$(DotNetConfigPath)' == ''">$([MSBuild]::GetDirectoryNameOfFileAbove("$(MSBuildProjectDirectory)/..", ".config/dotnet-tools.json"))</DotNetConfigPath>  
        <DotNetConfig Condition="'$(DotNetConfig)' == ''">$([System.IO.File]::ReadAllText("$(DotNetConfigPath)/.config/dotnet-tools.json"))</DotNetConfig>  
        <!-- Extracts the version number from the first tool defined in 'dotnet-tools.json' that starts with "beamable". -->  
        <BeamableVersion Condition="'$(BeamableVersion)' == ''">$([System.Text.RegularExpressions.Regex]::Match("$(DotNetConfig)", "beamable.*?\"([0-9]+\.[0-9]+\.[0-9]+.*?)\",", RegexOptions.Singleline | RegexOptions.IgnorePatternWhitespace).Groups[1].Value)</BeamableVersion>  
        <!-- When running from inside docker, this gets injected via the Dockerfile at build-time. -->  
    </PropertyGroup>  
    <PropertyGroup Label="Dotnet Settings">  
        <!-- net8.0 is the LTS version until 2026. To update your net version, update the <TargetFramework> when Beamable announces support. -->  
        <TargetFramework>net8.0</TargetFramework>  
    </PropertyGroup>  
    <ItemGroup Label="Nuget References">  
        <PackageReference Include="Beamable.Microservice.Runtime" Version="$(BeamableVersion)" />
        <PackageReference Include="Beamable.Microservice.SourceGen" Version="$(BeamableVersion)" OutputItemType="Analyzer" />
    </ItemGroup>  
</Project>

Code Dependencies

Dotnet projects use a tool called Nuget to manage dependencies on other code libraries. Each <PackageReference> node within an <ItemGroup> element declares a Nuget dependency. By default, every Standalone Microservice requires the Beamable Microservice Nuget Package. However, you can add whatever packages you require as well.

Beamable Properties

Dotnet uses a tool called msbuild to compile your code into executable files. When the build happens, msbuild accesses various XML based properties within the <PropertyGroup> elements of the .csproj file.

BeamProjectType

The <BeamProjectType> is an enum string that declares the containing .csproj to be either a Microservice, or a Storage object. If a .csproj does not declare the <BeamProjectType> property, then it will not be detected by the beam CLI as a valid Microservice or Storage object.

Valid values include,

BeamId

The <BeamId> controls the name of the Beamable project.

BeamEnabled

The <BeamEnabled> is a boolean property. When false, when services are deployed , the service will not be enabled, and will not cost Beamable Cloud resources.
This option can be set using the project enable or the project disable commands.

GenerateClientCode

The <GenerateClientCode> property is boolean property, only valid on Standalone Microservice projects. When the project is built, if there are any linked Unity or Unreal projects, client code may be generated for the engine client and placed in the linked project folders. In order to link a project, use the add-unity-project command, or the add-unreal-project command.

BeamableTool

The <BeamableTool> property is the path to the Beam CLI program that the Standalone Microservice will use to do various tasking. For most cases, this is configured to be the globally installed beam tool. However, if any dotnet build tasks run with a BEAM_PATH environment variable, then the BEAM_PATH environment variable will set the <BeamableTool> value.

Generally, it is not advised to overwrite this setting. However, it you install the beam CLI as a local dotnet tool in the project, it would be valid to overwrite the <BeamableTool> property as dotnet beam.

This property is accessible to the dotnet build targets, including any custom targets you create.

BeamServiceGroup

The <BeamServiceGroup> property is a comma or semi-colon separated list of tags that logically group services together.
If you need to specify multiple values, use a , or a ; to separate values. You can also redefine the property in terms of itself.

<BeamServiceGroup>firstTag</BeamServiceGroup>
<BeamServiceGroup>$(BeamServiceGroup);secondTag</BeamServiceGroup>

Dotnet Properties

Common Dotnet properties may be explored through Dotnet's Documentation . However, there are a few properties that are set automatically through the usage of the Beamable Microservice Nuget Package. To view these default settings, you should view the package source code's .props file, located here,

https://github.com/beamable/BeamableProduct/blob/cli-2.0.0/microservice/microservice/Targets/Beamable.Microservice.Runtime.props

📘

Make sure to reference the right version!

The link above points to the cli-2.0.0 release tag version of the source code. Make sure that you are looking the same version as your Beamable.Microservice.Runtime nuget version is using in the .csproj.

Other than the default properties set in the .props file, a major requirement of Beamable Standalone Microservices the TargetFramework property. If you are using CLI 3.0.0 and above, you may target net8.0 .

If you are using CLI 2.0.1 or below, you must target net6.0.