diff --git a/.github/workflows/auto-sync-core.yml b/.github/workflows/auto-sync-core.yml index 93f88bf5c..b0421e12c 100644 --- a/.github/workflows/auto-sync-core.yml +++ b/.github/workflows/auto-sync-core.yml @@ -3,7 +3,7 @@ name: Auto Merge Core on: push: branches: - - 'core/v7.1' + - 'core/v7.0' run-name: "Merge ${{ github.ref_name }} into docs" @@ -16,7 +16,7 @@ jobs: name: Merge ${{ github.ref_name }} into ${{ matrix.branch }} strategy: matrix: - branch: [unreal/v2.3] + branch: [unity/v5.0, unreal/v2.3] outputs: success_branches: ${{ steps.aggregate.outputs.success_branches }} conflicted_branches: ${{ steps.aggregate.outputs.conflicted_branches }} diff --git a/docs/cli/guides/configuration.md b/docs/cli/guides/configuration.md index c47e44ebd..cefcc85eb 100644 --- a/docs/cli/guides/configuration.md +++ b/docs/cli/guides/configuration.md @@ -27,22 +27,22 @@ someOtherFolder | `someOtherFolder` | no config is available | -## Validation +## Validation -From any folder, you can run the [beam config](../commands/cli-command-reference/config/config.md) command to print information about your current Beamable folder. +From any folder, you can run the [beam config](../commands/cli-command-reference/config/config.md) command to print information about your current Beamable folder. -In the example directory structure above, if the `beam config` command was invoked from the `mainFolder`, it would log information about the `mainFolder/.beamable` folder. +In the example directory structure above, if the `beam config` command was invoked from the `mainFolder`, it would log information about the `mainFolder/.beamable` folder. ```sh mainFolder % dotnet beam config - { - "host": "https://api.beamable.com", - "cid": "", - "pid": "", - "configPath": "/Users/examples/mainFolder/.beamable" - } + { + "host": "https://api.beamable.com", + "cid": "", + "pid": "", + "configPath": "/Users/examples/mainFolder/.beamable" + } ``` -However, if the `beam config` command was invoked from the `someOtherFolder` path, you should expect to see an error, because there is no `.beamable` folder within the parent linear. +However, if the `beam config` command was invoked from the `someOtherFolder` path, you should expect to see an error, because there is no `.beamable` folder within the parent lineage. ```sh someOtherFolder % dotnet beam config @@ -51,16 +51,16 @@ someOtherFolder % dotnet beam config NOTE: Consider calling `beam init` first. - + Logs at   /var/folders/ys/949qmfy15r7bl8x36s6wmm000000gn/T/beamCliLog.txt ``` -## Dotnet Tool Folder +## .NET Tool Folder -The Beamable CLI executes as a local dotnet tool installation. That means that there should be a `.config/` folder in your project. There should be a file called `dotnet-tools.json` in the folder, declaring the version of the CLI you are using. +The Beamable CLI executes as a local .NET tool installation. That means that there should be a `.config/` folder in your project. There should be a file called `dotnet-tools.json` in the folder, declaring the version of the CLI you are using. ```json { @@ -79,16 +79,16 @@ The Beamable CLI executes as a local dotnet tool installation. That means that t !!! info "The folder can exist in a higher folder." - Normally the `.config/` folder exists as a sibling of the `.beamable/` folder. However, the `.config/` folder _may_ exist in a parent folder. The closest `.config/` folder will be used. See the [dotnet tool documentation](https://learn.microsoft.com/en-us/dotnet/core/tools/local-tools-how-to-use) for more information. + Normally the `.config/` folder exists as a sibling of the `.beamable/` folder. However, the `.config/` folder _may_ exist in a parent folder. The closest `.config/` folder will be used. See the [.NET tool documentation](https://learn.microsoft.com/en-us/dotnet/core/tools/local-tools-how-to-use) for more information. ## Workspace Overview -A Beamable workspace is defined by the existence of a `.beamable/` folder. +A Beamable workspace is defined by the existence of a `.beamable/` folder. | Path | Note | | ---------------- | ----------------- | -| `config.beam.json` | this file must exist, and contains your project's connection information. | +| `config.beam.json` | this file must exist, and contains your project's connection information. | | `/temp` | this folder should not be included in version control. It contains information about your current session. The contents of this folder may be discarded at any time | | `/shared` | this folder contains information that will be shared with other developers in the project | | `/local` | this folder should not be included in version control. It contains local information specific to your session | diff --git a/docs/cli/guides/getting-started.md b/docs/cli/guides/getting-started.md index 461d8369e..fcf8ba55f 100644 --- a/docs/cli/guides/getting-started.md +++ b/docs/cli/guides/getting-started.md @@ -1,14 +1,14 @@ # Get up and running with the Beamable CLI -The Beamable CLI is a dotnet tool that allows developers to interact with Beamable. It can manage a variety of Beamable technologies, including Microservices, Content, and other services. +The Beamable CLI is a .NET tool that allows developers to interact with Beamable. It can manage a variety of Beamable technologies, including Microservices, Content, and other services. ## Dependencies -You'll need to install [Dotnet 10](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) before you can get started. +You'll need to install [.NET 10](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) before you can get started. Verify it is installed by running `dotnet --version` from a terminal. -!!! info "We support Dotnet 8 as well." +!!! info "We support .NET 8 as well." - If you are using the Beamable CLI before version 7.0, then you should be using [Dotnet 8](https://dotnet.microsoft.com/en-us/download/dotnet/8.0). Starting with CLI 7.0 and beyond, we support both versions of dotnet, but we recommend you use `net10.0`. + If you are using the Beamable CLI before version 7.0, then you should be using [.NET 8](https://dotnet.microsoft.com/en-us/download/dotnet/8.0). Starting with CLI 7.0 and beyond, we support both versions of .NET, but we recommend you use `net10.0`. ## Installing @@ -32,17 +32,17 @@ The following command will install the latest CLI. The "latest" string can be an beam version install latest ``` -!!! info "Check Versions on Nuget" +!!! info "Check Versions on NuGet" - Remember, Beamable.Tools is a dotnet tool available through Nuget. As such, you can find all available versions at [nuget.org](https://www.nuget.org/packages/Beamable.Tools) + Remember, Beamable.Tools is a .NET tool available through NuGet. You can find all available versions at [nuget.org](https://www.nuget.org/packages/Beamable.Tools) There may be updates you are required to do, so please check the [migration guide](upgrading.md). ## Getting Started -Now that Beamable is installed, you can connect to an existing Beamable organization. If you haven't setup an organization yet, [create a Beamable organization](https://portal.beamable.com/signup/registration/) first. +Now that Beamable is installed, you can connect to an existing Beamable organization. If you haven't setup an organization yet, [create a Beamable organization](https://portal.beamable.com/signup/registration/) first. -You can connect the CLI to your Beamable organization with the [beam init](../commands/cli-command-reference/init.md) command. +You can connect the CLI to your Beamable organization with the [beam init](../commands/cli-command-reference/init.md) command. ```shell mkdir MyProject @@ -54,11 +54,11 @@ This command will prompt you for your organization's alias, your credentials, an ```shell dotnet beam config ``` -You should expect to see your CID/PID printed out. +You should expect to see your CID/PID printed out. -As of CLI 3.0.0, anytime you create a Beamable workspace, the CLI will be installed as a local tool next to the workspace's `.beamable` folder. This means that you can run the local tool with `dotnet beam`. If you continue to use `beam` in the workspace, the global installation will automatically forward your command to the local tool. This will be inefficient and lead to poor performance. We recommend you use `dotnet beam` wherever possible. +As of CLI 3.0.0, anytime you create a Beamable workspace, the CLI will be installed as a local tool next to the workspace's `.beamable` folder. This means that you can run the local tool with `dotnet beam`. If you continue to use `beam` in the workspace, the global installation will automatically forward your command to the local tool. This will be inefficient and lead to poor performance. We recommend you use `dotnet beam` wherever possible. -To check that everything is working correctly, you can use the beam me command. Now you have a configured CLI project! +To check that everything is working correctly, you can use the beam me command. Now you have a configured CLI project! !!! info "Finding Help" diff --git a/docs/cli/guides/microservices.md b/docs/cli/guides/microservices.md index ca8f74f6a..24ca6c76d 100644 --- a/docs/cli/guides/microservices.md +++ b/docs/cli/guides/microservices.md @@ -2,11 +2,11 @@ Developing Standalone Microservices with the Beam CLI -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. +Beamable offers a rich microservice development workflow using the Beam CLI and .NET. 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](getting-started.md). That means having [Dotnet 10](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) installed, and getting the [Beam CLI](https://www.nuget.org/packages/Beamable.Tools). +Before you can develop a Beamable Standalone Microservice, you need to complete the [Getting-Started Guide](getting-started.md). That means having [.NET 10](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) installed, and getting the [Beam CLI](https://www.nuget.org/packages/Beamable.Tools). You can confirm you have everything installed checking the versions of the tools. ```sh @@ -24,21 +24,21 @@ dotnet beam init MyProject cd MyProject ``` -Once you have a `.beamable` workspace, you can create a new Standalone Microservice using the [project new](ms-workflow.md#creating-new-projects) command. +Once you have a `.beamable` workspace, you can create a new Standalone Microservice using the [project new](ms-workflow.md#creating-new-projects) command. ```sh # 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). +A new file, `BeamableServices.sln` has been created in `/MyProject`. Open it in your IDE of choice (Visual Studio Code, Rider, or Visual Studio). ![Project Structure](https://files.readme.io/751b491-image.png) -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. +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, +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 @@ -47,17 +47,17 @@ However you decide to run the project, you should see a stream of logs similar t ``` -The service is running! You can send requests to the service over HTTP. To verify, you can open the local Open API documentation by using the project open-swagger command. +The service is running! You can send requests to the service over HTTP. To verify, you can open the local Open API documentation by using the project open-swagger command. ```sh dotnet beam project open-swagger ``` -Your local web browser should open to the Beamable Portal, showing the local Open API documentation, +Your local web browser should open to the Beamable Portal, showing the local Open API documentation, ![local swagger docs](https://files.readme.io/6c000ac-image.png) -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, +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, ```json { @@ -65,17 +65,17 @@ Click on the last green button that says, "`POST` /Add", and then select the "Tr "b": 3 } ``` -And then click the Execute button! In your Standalone Microservice project, you should see some logs appear indicating the service was invoked. +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. +The `Add` function is defined in the `HelloWorld.cs` file. ```csharp using Beamable.Server; - + namespace Beamable.HelloWorld { [Microservice("HelloWorld")] @@ -90,21 +90,21 @@ namespace Beamable.HelloWorld } ``` -You can write new functions and tag them with `[ClientCallable]` to make them accessible on the Open API page. Now you know the basics of working with Beamable Standalone Microservices! +You can write new functions and tag them with `[ClientCallable]` to make them accessible on the Open API page. 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. +Each file in the Standalone Microservice has a valuable function that is important to understand. | file | function | | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `MyProject/services/.gitignore` | a version control file that will ignore build and intermediate folders from your git based source control | | `MyProject/services/Dockerfile` | When the Standalone Microservice is deployed, it will be containerized using Docker. You can modify the Dockerfile to extend the capabilities of the service. See the [Deployment Section](ms-deployment.md#Dockerfiles) for more details | | `MyProject/services/HelloWorld.cs` | This file is the main `.cs` file that has your server functionality | -| `MyProject/services/Programcs` | This file is the entry point of the dotnet application. It bootstraps the server and starts it. You may edit it, but make sure not to remove the section that enables the service. | -| `MyProject/services/HelloWorld.csproj` | This file is the dotnet project file for your service. You can modify the `.csproj` file to customize your service. See the [Microservice Configuration Section](ms-configuration.md) section for more details | -| `MyProject/BeamableServices.sln` | This file is the dotnet solution file, and organizes your services. If you add additional services or storage databases, they will be tracked through the `.sln` file. | +| `MyProject/services/Programcs` | This file is the entry point of the .NET application. It bootstraps the server and starts it. You may edit it, but make sure not to remove the section that enables the service. | +| `MyProject/services/HelloWorld.csproj` | This file is the .NET project file for your service. You can modify the `.csproj` file to customize your service. See the [Microservice Configuration Section](ms-configuration.md) section for more details | +| `MyProject/BeamableServices.sln` | This file is the .NET solution file, and organizes your services. If you add additional services or storage databases, they will be tracked through the `.sln` file. | --- ## Next Steps diff --git a/docs/cli/guides/ms-command-line.md b/docs/cli/guides/ms-command-line.md index b2a699111..3e34b648d 100644 --- a/docs/cli/guides/ms-command-line.md +++ b/docs/cli/guides/ms-command-line.md @@ -4,7 +4,7 @@ Passing output from the CLI to other processes ## Dependencies -Before you can use the Beamable CLI, you need to complete the [Getting-Started Guide](doc:cli-guide-getting-started). That means having [Dotnet 10](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) installed, and getting the [Beam CLI](https://www.nuget.org/packages/Beamable.Tools). +Before you can use the Beamable CLI, you need to complete the [Getting-Started Guide](doc:cli-guide-getting-started). That means having [.NET 10](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) installed, and getting the [Beam CLI](https://www.nuget.org/packages/Beamable.Tools). You can confirm you have everything installed checking the versions of the tools. ```sh @@ -15,9 +15,9 @@ dotnet beam version # dotnet beam --version also works. ## Logging -By default, the Beam CLI uses an informational level of logging. Usually, only the final output of a command will be printed to the console. However, for diagnostic purposes, you can change the log level of the CLI using the `--log` switch. +By default, the Beam CLI uses an informational level of logging. Usually, only the final output of a command will be printed to the console. However, for diagnostic purposes, you can change the log level of the CLI using the `--log` switch. -The log levels are as follows, +The log levels are as follows, | Level | Description | | --------- | ------------------------------------------------------------------------------ | @@ -28,7 +28,7 @@ The log levels are as follows, | `ERROR` | ignores everything unless an error occurs | | `FATAL` | ignores everything unless the process fatally crashes | -In order to set the log level, the full level name may be used (case insensitive), or simply the first letter of the level. For example, to use verbose logs, the following expression may be used. +In order to set the log level, the full level name may be used (case insensitive), or simply the first letter of the level. For example, to use verbose logs, the following expression may be used. ```sh dotnet beam config --logs v @@ -37,21 +37,21 @@ dotnet beam config --logs v ## Raw Output Mode -By default, the Beam CLI prints output in a variety of ways. Some commands will print JSON to the Standard Output Buffer (StdOut), and other commands will print conversational messages. However, all commands can be forced to print in a structured JSON format. +By default, the Beam CLI prints output in a variety of ways. Some commands will print JSON to the Standard Output Buffer (StdOut), and other commands will print conversational messages. However, all commands can be forced to print in a structured JSON format. -The `--raw` flag will always print messages in JSON. The `--raw` message contains additional information than what may be printed for commands that already use JSON. For example, the `beam config` command prints JSON, +The `--raw` flag will always print messages in JSON. The `--raw` message contains additional information than what may be printed for commands that already use JSON. For example, the `beam config` command prints JSON, ```sh dotnet beam config - { - "host": "https://api.beamable.com", - "cid": "123", - "pid": "DE_123", - "configPath": "/Users/Test/MyProject/.beamable" - } + { + "host": "https://api.beamable.com", + "cid": "123", + "pid": "DE_123", + "configPath": "/Users/Test/MyProject/.beamable" + } ``` -However, when the `--raw` flag is given, the output becomes, +However, when the `--raw` flag is given, the output becomes, ```sh dotnet beam config --raw @@ -72,16 +72,16 @@ When a Beam CLI command is piped into another process, the `--raw` flag is force ```sh dotnet beam config > output.txt -cat output.txt +cat output.txt {"ts":1716908709811,"type":"stream","data":{"host":"https://api.beamable.com","cid":"123","pid":"DE_123","configPath":"/Users/Test/MyProject/.beamable"}} ``` A common workflow is to use the [JQ](https://jqlang.github.io/jq/download/) tool to navigate the piped `--raw` output. Below are some common examples. -In order to pipe the `data` to a file, we could write, +In order to pipe the `data` to a file, we could write, ```sh dotnet beam config | jq '.data' > output.txt -cat output.txt +cat output.txt { "host": "https://api.beamable.com", "cid": "123", @@ -96,7 +96,7 @@ dotnet beam config | jq '.data.cid' "123" ``` -Sometimes it is important to get the unescaped JSON, so the `fromjson` component of JQ can be used. For example, if we wanted the `cid` value, but without quotes, +Sometimes you need the unescaped JSON; the `fromjson` component of JQ can be used. For example, if we wanted the `cid` value, but without quotes, ```sh dotnet beam config | jq '.data.cid | fromjson' @@ -109,9 +109,9 @@ dotnet beam config | jq -r .data.cid ## Piping and Logging -When the `--raw` flag is used, or a command is piped to a file, then the Standard Output Buffer will only receive the `--raw` output data. If the `--logs` flag is set, then logs will be sent to the Standard Error Buffer, such that will appear in the console. However, it can be tricky to emit the process logs to a file. +When the `--raw` flag is used, or a command is piped to a file, then the Standard Output Buffer will only receive the `--raw` output data. If the `--logs` flag is set, then logs will be sent to the Standard Error Buffer, such that will appear in the console. However, it can be tricky to emit the process logs to a file. -In order to do so, the Standard Error Buffer must be piped to a file. For example, the following expression will put the process logs into a file. +In order to do so, the Standard Error Buffer must be piped to a file. For example, the following expression will put the process logs into a file. ```sh dotnet beam config --logs v 2> test.txt @@ -120,7 +120,7 @@ dotnet beam config --logs v 2> test.txt The contents of the `test.txt` file contain the process logs, not the `--raw` output. ```sh -cat test.txt +cat test.txt Trying to get option=ConfigDirOption from Env Vars! Value Found= Using standard unix docker uri=[unix:/var/run/docker.sock] GET call: /basic/beamo/manifest/current diff --git a/docs/cli/guides/ms-configuration.md b/docs/cli/guides/ms-configuration.md index 79cd00c33..6362e32aa 100644 --- a/docs/cli/guides/ms-configuration.md +++ b/docs/cli/guides/ms-configuration.md @@ -4,7 +4,7 @@ Configure Standalone Microservices ## Dependencies -Before you can configure Beamable Standalone Microservices, you need to complete the [Getting-Started Guide](getting-started.md). That means having [Dotnet 10](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) installed, and getting the [Beam CLI](https://www.nuget.org/packages/Beamable.Tools). +Before you can configure Beamable Standalone Microservices, you need to complete the [Getting-Started Guide](getting-started.md). That means having [.NET 10](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) installed, and getting the [Beam CLI](https://www.nuget.org/packages/Beamable.Tools). You can confirm you have everything installed checking the versions of the tools. ```sh @@ -19,56 +19,56 @@ cd MyProject dotnet beam project new service HelloWorld ``` -## Project Configuration +## 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. +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. ```xml - - - - service - - - true - - - - $([MSBuild]::GetDirectoryNameOfFileAbove("$(MSBuildProjectDirectory)/..", ".config/dotnet-tools.json")) - $([System.IO.File]::ReadAllText("$(DotNetConfigPath)/.config/dotnet-tools.json")) - - $([System.Text.RegularExpressions.Regex]::Match("$(DotNetConfig)", "beamable.*?\"([0-9]+\.[0-9]+\.[0-9]+.*?)\",", RegexOptions.Singleline | RegexOptions.IgnorePatternWhitespace).Groups[1].Value) - - - - - net8.0 - - + + + + service + + + true + + + + $([MSBuild]::GetDirectoryNameOfFileAbove("$(MSBuildProjectDirectory)/..", ".config/dotnet-tools.json")) + $([System.IO.File]::ReadAllText("$(DotNetConfigPath)/.config/dotnet-tools.json")) + + $([System.Text.RegularExpressions.Regex]::Match("$(DotNetConfig)", "beamable.*?\"([0-9]+\.[0-9]+\.[0-9]+.*?)\",", RegexOptions.Singleline | RegexOptions.IgnorePatternWhitespace).Groups[1].Value) + + + + + net8.0 + + - + ``` ### Code Dependencies -Dotnet projects use a tool called _Nuget_ to manage dependencies on other code libraries. Each `` node within an `` element declares a Nuget dependency. By default, every Standalone Microservice requires the [Beamable Microservice Nuget Package](https://www.nuget.org/packages/Beamable.Microservice.Runtime). However, you can add whatever packages you require as well. +.NET projects use a tool called _NuGet_ to manage dependencies on other code libraries. Each `` node within an `` element declares a NuGet dependency. By default, every Standalone Microservice requires the [Beamable Microservice NuGet Package](https://www.nuget.org/packages/Beamable.Microservice.Runtime). 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 `` elements of the `.csproj` file. +.NET uses a tool called `msbuild` to compile your code into executable files. When the build happens, `msbuild` accesses various XML based properties within the `` elements of the `.csproj` file. #### BeamProjectType -The `` 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 `` property, then it will not be detected by the beam CLI as a valid Microservice or Storage object. +The `` 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 `` property, then it will not be detected by the beam CLI as a valid Microservice or Storage object. | Property Name | Default Value | | ------------------- | --------------------------- | | `` | _there is no default value_ | -Valid values include, +Valid values include, | Value | Description | | --------- | ---------------------------------------------------- | @@ -77,7 +77,7 @@ Valid values include, #### BeamId -The `` controls the name of the Beamable project. +The `` controls the name of the Beamable project. | Property Name | Default Value | | ------------- | ------------------------- | @@ -93,7 +93,7 @@ The `` determines which log provider the microservice will use. #### BeamEnabled -The `` is a boolean property. When `false`, when services are [deployed](ms-deployment.md) , the service will not be enabled, and will not cost Beamable Cloud resources. +The `` is a boolean property. If set to `false`, the service will not be enabled when [deployed](ms-deployment.md), and will not cost Beamable Cloud resources. This option can be set using the project enable or the project disable commands. | Property Name | Default Value | @@ -101,21 +101,21 @@ This option can be set using the project enable or the project disable commands. | `` | true | #### BeamPreventOapiGen -The `` property is a boolean property, only valid on Microservice projects. When false, when the project is built, an open API document will be generated and placed in the `/bin` directory of the project. +The `` property is a boolean property, only valid on Microservice projects. When false, when the project is built, an open API document will be generated and placed in the `/bin` directory of the project. | Property Name | Default Value | | ---------------------- | ------------- | | `` | false | #### BeamCollectorVersion -In version 6.0+, the Microservice uses an open telemetry collector process to send logs from the service to Beamable's log warehouse. The collector is versioned separately from the CLI and Microservice nuget packages. The version of the collector is embedded into the `BeamCollectorVersion` property, but it can be configured by hand. +In version 6.0+, the Microservice uses an open telemetry collector process to send logs from the service to Beamable's log warehouse. The collector is versioned separately from the CLI and Microservice NuGet packages. The version of the collector is embedded into the `BeamCollectorVersion` property, but it can be configured by hand. | Property Name | Default Value | | ------------------------ | ------------------------------------------------------ | | `` | a semver value specific to the CLI version being used. | #### BeamDisableCollectorResolution -In version 6.0+, the Microservice uses an open telemetry collector process to send logs from the service to Beamable's log warehouse. When the Microservice is built, the collector is automatically downloaded. This can be disabled by setting the property to `true`. +In version 6.0+, the Microservice uses an open telemetry collector process to send logs from the service to Beamable's log warehouse. When the Microservice is built, the collector is automatically downloaded. This can be disabled by setting the property to `true`. | Property Name | Default Value | | ---------------------------------- | ------------- | @@ -123,24 +123,24 @@ In version 6.0+, the Microservice uses an open telemetry collector process to se #### BeamPreventBuildCacheInvalidation -The `` property is a boolean, only valid on Microservice projects. In version 6+, anytime you build the service, there is a custom build step that will invalidate the file timestamp on the `.csproj` file, in order to break aggressive IDE cache optimizations. Specifically, the Rider IDE, has a cache that will prevent `msbuild` from running if it thinks your service has not changed. +The `` property is a boolean, only valid on Microservice projects. In version 6+, anytime you build the service, there is a custom build step that will invalidate the file timestamp on the `.csproj` file, to break aggressive IDE cache optimizations. Specifically, the Rider IDE, has a cache that will prevent `msbuild` from running if it thinks your service has not changed. -You can disable the cache invalidation by setting this property to `true`. +You can disable the cache invalidation by setting this property to `true`. | Property Name | Default Value | | ------------------------------------- | ------------- | | `` | false | -#### GenerateClientCode +#### GenerateClientCode -The `` 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. +The `` 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. | Property Name | Default Value | Note | | ---------------------- | ------------- | ------------------------------------- | | `` | false | In CLI 3.0, this was set to `true` . | #### EnableUnrealBlueprintCompatibility -The `` property is a boolean property, only valid on Microservice projects. When it is enabled, the source generator will include validations on Microservice client generation that make Unreal Blueprint compatibility easier to maintain. +The `` property is a boolean property, only valid on Microservice projects. When it is enabled, the source generator will include validations on Microservice client generation that make Unreal Blueprint compatibility easier to maintain. | Property Name | Default Value | | -------------------------------------- | ------------- | @@ -148,14 +148,14 @@ The `` property is a boolean property, only #### BeamValidateCallableTypesExistInSharedLibraries -The `` property is a boolean property, only valid on Microservice projects. -When it is enabled, and the `Beamable.Microservice.SourceGen` nuget package is referenced, the static analyzer will -disallow type references on `[Callable]` methods that are defined _within_ the Microservice assembly. +The `` property is a boolean property, only valid on Microservice projects. +When it is enabled, and the `Beamable.Microservice.SourceGen` NuGet package is referenced, the static analyzer will +disallow type references on `[Callable]` methods that are defined _within_ the Microservice assembly. The goal is to prevent developers from building `[Callable]` methods that rely on data types inaccessible outside -of the Microservice assembly. +of the Microservice assembly. This is disabled by default, because Microservices being developed outside an engine integration likely -do not need to worry about type accessibility. +do not need to worry about type accessibility. | Property Name | Default Value | | --------------------------------------------------- | ------------- | @@ -163,18 +163,18 @@ do not need to worry about type accessibility. #### BeamableTool -The `` 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 `` value. +The `` 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 `` 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 `` property as `dotnet beam`. +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 `` property as `dotnet beam`. -This property is accessible to the dotnet build targets, including any custom targets you create. +This property is accessible to the dotnet build targets, including any custom targets you create. | Property Name | Default Value | | ---------------- | -------------------------------------------- | | `` | the value of env var, `BEAM_PATH`, or `beam` | #### BeamServiceGroup -The `` property is a comma or semi-colon separated list of tags that logically group services together. +The `` 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. ```xml @@ -189,21 +189,21 @@ If you need to specify multiple values, use a `,` or a `;` to separate values. Y ### Telemetry Properties -In CLI 6.0, the CLI will try to collect usage data and send it to Beamable. You can opt out of this by changing the `BeamCliAllowTelemetry` property to false in the `.beamable/otel-config.json` file. +In CLI 6.0, the CLI will try to collect usage data and send it to Beamable. You can opt out of this by changing the `BeamCliAllowTelemetry` property to false in the `.beamable/otel-config.json` file. -Additionally, you can completely opt out of usage reporting by setting the `BEAM_NO_TELEMETRY` environment variable. +Additionally, you can completely opt out of usage reporting by setting the `BEAM_NO_TELEMETRY` environment variable. -### Dotnet Properties +### .NET Properties -Common Dotnet properties may be explored through [Dotnet's Documentation](https://learn.microsoft.com/en-us/visualstudio/msbuild/common-msbuild-project-properties?view=vs-2022) . However, there are a few properties that are set automatically through the usage of the [Beamable Microservice Nuget Package](https://www.nuget.org/packages/Beamable.Microservice.Runtime). To view these default settings, you should view the package source code's `.props` file, located here, +Common .NET properties may be explored through [.NET documentation](https://learn.microsoft.com/en-us/visualstudio/msbuild/common-msbuild-project-properties?view=vs-2022) . However, there are a few properties that are set automatically through the usage of the [Beamable Microservice NuGet Package](https://www.nuget.org/packages/Beamable.Microservice.Runtime). To view these default settings, you should view the package source code's `.props` file, located here, [https://github.com/beamable/BeamableProduct/blob/cli-6.0.0/microservice/microservice/Targets/Beamable.Microservice.Runtime.props](https://github.com/beamable/BeamableProduct/blob/cli-2.0.0/microservice/microservice/Targets/Beamable.Microservice.Runtime.props) !!! info "Make sure to reference the right version!" - The link above points to the cli-6.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`. + The link above points to the cli-6.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` . +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`. diff --git a/docs/cli/guides/ms-debugging.md b/docs/cli/guides/ms-debugging.md index 2a5591aa0..b18f0737c 100644 --- a/docs/cli/guides/ms-debugging.md +++ b/docs/cli/guides/ms-debugging.md @@ -4,7 +4,7 @@ Debug Standalone Microservices locally ## Dependencies -Before you can debug Beamable Standalone Microservices, you need to complete the [Getting-Started Guide](getting-started.md). That means having [Dotnet 10](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) installed, and getting the [Beam CLI](https://www.nuget.org/packages/Beamable.Tools). +Before you can debug Beamable Standalone Microservices, you need to complete the [Getting-Started Guide](getting-started.md). That means having [.NET 10](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) installed, and getting the [Beam CLI](https://www.nuget.org/packages/Beamable.Tools). You can confirm you have everything installed checking the versions of the tools. ```sh @@ -19,26 +19,26 @@ cd MyProject dotnet beam project new service HelloWorld ``` -## Debugging +## Debugging -Beamable Standalone Microservices run as vanilla dotnet processes on your machine. That means you can use your favorite IDE to debug the service. You can attach breakpoints and then start the service with Debugging, or attach to existing process using your IDE. +Beamable Standalone Microservices run as vanilla .NET processes on your machine. That means you can use your favorite IDE to debug the service. You can attach breakpoints and then start the service with Debugging, or attach to existing process using your IDE. ![A breakpoint in a microservice](https://files.readme.io/88da124-image.png) ## Hot Reload -If you run your service with hot reload enabled, then your code will be recompiled automatically as you make changes to your code, and your running service won't need to restart. +If you run your service with hot reload enabled, then your code will be recompiled automatically as you make changes to your code, and your running service won't need to restart. -Unfortunately, JetBrains Rider has limited hot reload support out of the box. With that in mind, this guide will assume that if you want to use hot reload, you'll be using the CLI. +Unfortunately, JetBrains Rider has limited hot reload support out of the box. With that in mind, this guide will assume that if you want to use hot reload, you'll be using the CLI. -Not all types of source code changes will work with hot reload. Only changes to the `.cs` files will be acceptable. No changes to the `.csproj` or other build-time configuration options will be reloaded. +Not all types of source code changes will work with hot reload. Only changes to the `.cs` files will be acceptable. No changes to the `.csproj` or other build-time configuration options will be reloaded. -### Dotnet CLI +### .NET CLI -You can run your service with hot reload by using the vanilla dotnet CLI. +You can run your service with hot reload by using the vanilla .NET CLI. ```sh - MyProject % dotnet watch --project ./services/HelloWorld + MyProject % dotnet watch --project ./services/HelloWorld dotnet watch 🔥 Hot reload enabled. For a list of supported edits, see https://aka.ms/dotnet/hot-reload. 💡 Press "Ctrl + R" to restart. dotnet watch 🔧 Building... @@ -49,7 +49,7 @@ dotnet watch 🔧 Building... Generating client files... dotnet watch 🚀 Started ``` -Once you make an edit to your source code, you should see some logs that indicate the change. +Once you make an edit to your source code, you should see some logs that indicate the change. ``` dotnet watch ⌚ File changed: ./services/HelloWorld/HelloWorld.cs. diff --git a/docs/cli/guides/ms-deployment.md b/docs/cli/guides/ms-deployment.md index 11440247d..48694ff0f 100644 --- a/docs/cli/guides/ms-deployment.md +++ b/docs/cli/guides/ms-deployment.md @@ -4,13 +4,13 @@ Deploy Standalone Microservices to the Beamable Cloud ## Dependencies -Before you can deploy Beamable Standalone Microservices, you need to complete the [Getting-Started Guide](getting-started.md). That means having [Dotnet 10](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) installed, and getting the [Beam CLI](https://www.nuget.org/packages/Beamable.Tools). +Before you can deploy Beamable Standalone Microservices, you need to complete the [Getting-Started Guide](getting-started.md). That means having [.NET 10](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) installed, and getting the [Beam CLI](https://www.nuget.org/packages/Beamable.Tools). You can confirm you have everything installed checking the versions of the tools. ```sh dotnet --version beam version -# "beam --version" also works +# "beam --version" also works # "dotnet beam version" when using the CLI with an engine integration ``` @@ -28,7 +28,7 @@ dotnet beam project new service HelloWorld ## Deployment -Beamable Standalone Microservices use Dotnet as the core technology to run locally on your development machine. However, when it is time to release your Microservice to production, the service will be built into an OCI compliant image using [Docker](https://www.docker.com/products/docker-desktop/), and uploaded to the Beamable Cloud. Beamable's internal orchestration platform (sometimes called _BeamO_ ) will deploy containerized instances of the service. +Beamable Standalone Microservices use .NET as the core technology to run locally on your development machine. However, when it is time to release your Microservice to production, the service will be built into an OCI compliant image using [Docker](https://www.docker.com/products/docker-desktop/), and uploaded to the Beamable Cloud. Beamable's internal orchestration platform (sometimes called _BeamO_ ) will deploy containerized instances of the service. Deploying services is a two-step process. First, you must build the images and generate a **plan file**. Then, you use the CLI to deploy a plan. @@ -103,7 +103,7 @@ When planning to release microservices, its important to think about how to hand **Merge**: Creates a release plan that merges your current local environment to the existing remote services. In other words, existing deployed services that are not present locally will remain unaffected. -By default, we use the **replace** plan as it keeps "whatever is in your repository" as the source of truth. That being said, there are cases where **merge** can be useful. +By default, we use the **replace** plan as it keeps "whatever is in your repository" as the source of truth. That being said, there are cases where **merge** can be useful. For example, in cases where you want to remove the source code of a service from the repo, but still have the service be available for a while; this can happen if you have multiple *supported* client versions in existence, one dependent on a removed service and the other not. @@ -114,7 +114,7 @@ Calling `deploy release` makes the plan a reality. It'll upload the images the B Now that your service is running on the Beamable Cloud, you can send HTTPS traffic to your service. To help test, you can open the dot-dot-dot (`...`) menu on the right side of the `HelloWorld` card, and select "Docs" to open an Open API page. #### Redeploying Existing Services -Another important, albeit not common, usage of the `deploy release` command is to re-deploy your currently deployed services. This may be necessary to deal with bugs in your microservice code (or Beamable itself) that cause instability until you push a fix to them. +Another important, albeit not common, usage of the `deploy release` command is to re-deploy your currently deployed services. This may be necessary to deal with bugs in your microservice code (or Beamable itself) that cause instability until you push a fix to them. Here's how you'd do that: ```shell @@ -132,7 +132,7 @@ dotnet beam deploy release --from-manifest-id "id from the other command" ``` ## Enabling/Disabling Services -After a Standalone Microservice has been deployed, it will continue to be available on the Beamable Cloud until it is disabled. A service can be temporarily disabled through Portal, but they will be re-activated after a fresh `deploy release` command occurs. +After a Standalone Microservice has been deployed, it will continue to be available on the Beamable Cloud until it is disabled. A service can be temporarily disabled through the Portal, but they will be re-activated after a fresh `deploy release` command occurs. To disable a service, you need to modify the configuration of the Microservice source code itself. In the `.csproj` file of your service, set the `` property to `false`. Then, re-run the `deploy plan` command. You will see that the service would become disabled if you were to `deploy release` that plan. @@ -145,7 +145,7 @@ dotnet beam project disable --ids HelloWorld dotnet beam project enable --ids HelloWorld ``` -See the [Microservice Configuration Section](ms-configuration.md) for more details about project configuration. +See the [Microservice Configuration Section](ms-configuration.md) for more details about project configuration. !!! info "Services Cost Money!" @@ -156,69 +156,69 @@ A quick-note: we highly recommend you ***delete services from your repository*** For game-makers, these are often advanced use-cases. An example could be: > A Microservice containing DevTools that should NEVER be available in your production realm but SHOULD be available in non-production realms. This type of service cannot simply be removed. Instead, you need to control which realms have it deployed or not. -> +> > So, you can hide these services from your production realm by always having it disabled before publishing to Prod; but never having it disabled when publishing to other realms. ## Dockerfiles -Standalone Microservices build custom Docker images that are run on the Beamable Cloud. Each service has a `Dockerfile` that defines how the Docker image is constructed. +Standalone Microservices build custom Docker images that are run on the Beamable Cloud. Each service has a `Dockerfile` that defines how the Docker image is constructed. You may modify this file to extend the capabilities of your resulting docker image. However, there are a few restrictions about how you may modify the file. Do not edit or remove anything between the `` tags. This is a special tag that should allow us to programmatically add things to the `Dockerfile` should the need arise. -Beamable has validated that dotnet 8 is stable for all supported platforms. You may change the dotnet framework version at your own peril. +Beamable has validated that .NET 8 is stable for all supported platforms. You may change the .NET framework version at your own peril. !!! info "Docker CPU Architecture" Beamable Cloud requires that all services are built to x64 CPU architectures. Unfortunately, this means that developers with non x86 based computers will need to _cross compile_ services, which causes the `deploy` process to take longer. - + This is transparent to you and handled by your own machine's installed .NET toolchain. -Finally, the port `6565` **MUST** be exposed. The port is used as a health check mechanism within the Beamable Cloud. If you delete that line, your services will fail to pass health checks and cannot be uploaded. +Finally, the port `6565` **MUST** be exposed. The port is used as a health check mechanism within the Beamable Cloud. If you delete that line, your services will fail to pass health checks and cannot be uploaded. Here is a sample `Dockerfile` from a service created with Beam CLI 3.0.0. ```Dockerfile -ARG BEAM_DOTNET_VERSION="8.0-alpine" -FROM mcr.microsoft.com/dotnet/runtime:${BEAM_DOTNET_VERSION} - -# These args are provided by the Beam CLI - -# Declares the relative path from the beamable workspace to the pre-build support binaries for BeamService -# Normally, this will be /services/BeamService/bin/beamApp/support -ARG BEAM_SUPPORT_SRC_PATH - -# Declares the relative path from the beamable workspace to the pre-built binaries for BeamService -# Normally, this will be /services/BeamService/bin/beamApp/app -ARG BEAM_APP_SRC_PATH - -# Declares where the built application will exist inside the Docker image. -# This value is usually /beamApp/BeamService -ARG BEAM_APP_DEST - -# Beamable may inject custom settings into this Dockerfile. Please do not remove these lines. # - -# /beamApp is the directory that will hold the application -WORKDIR /beamApp - -# expose the health port -EXPOSE 6565 -# copy general supporting files -COPY $BEAM_SUPPORT_SRC_PATH . - -# copy specific application code -COPY $BEAM_APP_SRC_PATH . - -# ensure that the application is runnable -RUN chmod +x $BEAM_APP_DEST -ENV BEAM_APP=$BEAM_APP_DEST - -# when starting the container, run dotnet with the built dll -ENTRYPOINT "dotnet" $BEAM_APP - -# Swap entrypoints if the container is exploding and you want to keep it alive indefinitely so you can go look into it. +ARG BEAM_DOTNET_VERSION="8.0-alpine" +FROM mcr.microsoft.com/dotnet/runtime:${BEAM_DOTNET_VERSION} + +# These args are provided by the Beam CLI + +# Declares the relative path from the beamable workspace to the pre-build support binaries for BeamService +# Normally, this will be /services/BeamService/bin/beamApp/support +ARG BEAM_SUPPORT_SRC_PATH + +# Declares the relative path from the beamable workspace to the pre-built binaries for BeamService +# Normally, this will be /services/BeamService/bin/beamApp/app +ARG BEAM_APP_SRC_PATH + +# Declares where the built application will exist inside the Docker image. +# This value is usually /beamApp/BeamService +ARG BEAM_APP_DEST + +# Beamable may inject custom settings into this Dockerfile. Please do not remove these lines. # + +# /beamApp is the directory that will hold the application +WORKDIR /beamApp + +# expose the health port +EXPOSE 6565 +# copy general supporting files +COPY $BEAM_SUPPORT_SRC_PATH . + +# copy specific application code +COPY $BEAM_APP_SRC_PATH . + +# ensure that the application is runnable +RUN chmod +x $BEAM_APP_DEST +ENV BEAM_APP=$BEAM_APP_DEST + +# when starting the container, run dotnet with the built dll +ENTRYPOINT "dotnet" $BEAM_APP + +# Swap entrypoints if the container is exploding and you want to keep it alive indefinitely so you can go look into it. #ENTRYPOINT ["tail", "-f", "/dev/null"] ``` ### Local Docker Testing & Debugging -The recommended developer workflow is to run your micro services using Dotnet. However, because deployments are running within a container, it may be beneficial to validate that your services work in Docker before deploying them (especially if you've made changes to the default `Dockerfile`). +The recommended developer workflow is to run your micro services using Dotnet. However, because deployments are running within a container, it may be beneficial to validate that your services work in Docker before deploying them (especially if you've made changes to the default `Dockerfile`). To validate your Docker services, use the `--docker-compose-dir` option for the `beam deploy plan` command. The `plan` command will generate a [docker compose](https://docs.docker.com/compose/) project directory at the given path. The project will have all of your enabled services and storages. @@ -231,26 +231,26 @@ docker compose up You can validate that your services are running in docker using project ps or by using Docker directly. ```sh -dotnet beam project ps +dotnet beam project ps docker ps ``` -After you are done testing, you can use Docker directly to stop all the containers, or your can use `docker compose down`. +After you are done testing, you can use Docker directly to stop all the containers, or your can use `docker compose down`. ```sh docker compose down ``` -Please note that when validating docker containers this way, the resulting docker compose project is built to mirror the deployed environment, so your services will start up 10 connections to Beamable. +Please note that when validating docker containers this way, the resulting docker compose project is built to mirror the deployed environment, so your services will start up 10 connections to Beamable. -You have full control over the docker-compose file, so if you want to set up persistent storage objects via docker volumes, or set up mongo-express, please reference the Mongo [documentation](https://hub.docker.com/_/mongo). +You have full control over the docker-compose file, so if you want to set up persistent storage objects via docker volumes, or set up mongo-express, please reference the Mongo [documentation](https://hub.docker.com/_/mongo). #### Useful Debugging Practices -**Running the Docker Container Manually**: If you have a customized Dockerfile or encounter some problems when building/running the image/container, it can be sometimes useful to run the container via docker's CLI directly. +**Running the Docker Container Manually**: If you have a customized Dockerfile or encounter some problems when building/running the image/container, it can be sometimes useful to run the container via docker's CLI directly. You can do that by running: `dotnet beam deploy plan --logs v` which prints out all docker commands its using under the hood. You can then use the printed commands as a starting point for your investigation into whatever problem you're solving. -**Debugging Container Structure**: In some cases of customized `Dockerfiles`, the image may fail to build or the container fail to run due to aspects of the container's file structure. Docker will not allow you to easily inspect a container's file structure unless its running; and we cleanup the container once its `ENTRYPOINT` process is killed. +**Debugging Container Structure**: In some cases of customized `Dockerfiles`, the image may fail to build or the container fail to run due to aspects of the container's file structure. Docker will not allow you to easily inspect a container's file structure unless its running; and we cleanup the container once its `ENTRYPOINT` process is killed. This means that if SAMS code depends on local file structure (DLLs not existing where they should being the most common thing) and it fails because of a malformation of that structure you'll have a hard time debugging it. @@ -260,12 +260,12 @@ In some cases, it may be useful to not start the actual process and instead use ENTRYPOINT ["tail", "-f", "/dev/null"] ``` -When you do that, the service will not start --- but the container will look exactly like it does just before the service runs, except it won't be cleaned up by the health-check failing. This means you can easily inspect its file structure via Docker for Windows/Mac's UI or other tools. +When you do that, the service will not start — but the container will look exactly like it does just before the service runs, except it won't be cleaned up by the health-check failing. This means you can easily inspect its file structure via Docker for Windows/Mac's UI or other tools. !!! info "Troubleshoot" If you are on a Mac with the apple silicon processors (M1, M2, etc) the following error might occur when deploying C# Microservices. In that case, make sure that the `Use Rosetta for emulation on Apple Silicon` is disabled in your Docker settings. - + ``` assertion failed [block != nullptr]: BasicBlock requested for unrecognized address (BuilderBase.h:550 block_for_offset) diff --git a/docs/cli/guides/ms-federation.md b/docs/cli/guides/ms-federation.md index 57b93c548..7eecdfe23 100644 --- a/docs/cli/guides/ms-federation.md +++ b/docs/cli/guides/ms-federation.md @@ -4,7 +4,7 @@ Federate Standalone Microservices with external services ## Dependencies -Before you can federate using Beamable Standalone Microservices, you need to complete the [Getting-Started Guide](getting-started.md). That means having [Dotnet 10](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) installed, and getting the [Beam CLI](https://www.nuget.org/packages/Beamable.Tools). +Before you can federate using Beamable Standalone Microservices, you need to complete the [Getting-Started Guide](getting-started.md). That means having [.NET 10](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) installed, and getting the [Beam CLI](https://www.nuget.org/packages/Beamable.Tools). You can confirm you have everything installed checking the versions of the tools. ```sh @@ -22,10 +22,10 @@ dotnet beam project new service HelloWorld ## Federation -Microservice _Federation_ is the ability to inject custom server logic in the middle of existing Beamable server functionality. Federation can be used to add custom behaviour to your game like supporting external identity auth providers, using a block chain as the backing data provider for player inventory, managing how match making works, and more. +Microservice _Federation_ is the ability to inject custom server logic in the middle of existing Beamable server functionality. Federation can be used to add custom behaviour to your game like supporting external identity auth providers, using a block chain as the backing data provider for player inventory, managing how match making works, and more. -There are 4 types of federation. All of these federations have C# interfaces -that define the types of functions that they require. +There are 4 types of federation. All of these federations have C# interfaces +that define the types of functions that they require. 1. `IFederatedLogin` 2. `IFederatedInventory` 3. `IFederatedGameServer` @@ -37,7 +37,7 @@ A Microservice supports these federations when The `Microservice` class includes A service that federates login functionality may have a class signature like the following. ```csharp -public partial class ExampleService : IFederatedLogin +public partial class ExampleService : IFederatedLogin { // implementation } @@ -53,25 +53,25 @@ public class MySample : IFederationId { } ## CLI Commands -The CLI offers a few commands to enable and disable federations for a service. The `beam fed` command suite allows you to read and write federation data. None of the commands will modify your C# source files. +The CLI offers a few commands to enable and disable federations for a service. The `beam fed` command suite allows you to read and write federation data. None of the commands will modify your C# source files. -The `beam fed list` command will show all federations for all services. +The `beam fed list` command will show all federations for all services. ```sh dotnet beam fed list - { - "cid": "1338004997867618", - "pid": "DE_1754280032981028", - "services": [ - { - "beamoName": "ExampleService", - "routingKey": "chriss-macbook-pro-2_59e8e38ad189aefe093dfa7d74e18841", - "federations": { - "myId": [ - { - "interface": "IFederatedLogin" - } - ] - + { + "cid": "1338004997867618", + "pid": "DE_1754280032981028", + "services": [ + { + "beamoName": "ExampleService", + "routingKey": "chriss-macbook-pro-2_59e8e38ad189aefe093dfa7d74e18841", + "federations": { + "myId": [ + { + "interface": "IFederatedLogin" + } + ] + ``` --- diff --git a/docs/cli/guides/ms-logging.md b/docs/cli/guides/ms-logging.md index e28f826a3..c6f74bdf5 100644 --- a/docs/cli/guides/ms-logging.md +++ b/docs/cli/guides/ms-logging.md @@ -3,9 +3,9 @@ Logging from a Microservice ## Dependencies -This guide assumes you have an existing Microservice. You need to complete the +This guide assumes you have an existing Microservice. You need to complete the [Getting-Started Guide] -(getting-started.md). That means having [Dotnet 10](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) installed, and getting the [Beam CLI](https://www.nuget.org/packages/Beamable.Tools). +(getting-started.md). That means having [.NET 10](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) installed, and getting the [Beam CLI](https://www.nuget.org/packages/Beamable.Tools). You can confirm you have everything installed checking the versions of the tools. ```sh @@ -22,33 +22,33 @@ dotnet beam project new service HelloWorld ## Logs -In CLI 6.0+, Microservices use the standard [Microservice Logging Tools](https://learn.microsoft.com/en-us/dotnet/core/extensions/logging?tabs=command-line) for logging. To log something, use the following example: +In CLI 6.0+, Microservices use the standard [Microservice Logging Tools](https://learn.microsoft.com/en-us/dotnet/core/extensions/logging?tabs=command-line) for logging. To log something, use the following example: ```csharp -[ClientCallable] -public void SampleLog() -{ - Log.Information("Hello"); +[ClientCallable] +public void SampleLog() +{ + Log.Information("Hello"); } ``` -The static functions on the `Log` type will reference a default `ILogger`. If you want to use custom logging functions, access the `ILogger` via `Log.Default`. Beamable Microservices use _ZLogger_ under the hood, so you can access those methods directly if you want to. +The static functions on the `Log` type will reference a default `ILogger`. If you want to use custom logging functions, access the `ILogger` via `Log.Default`. Beamable Microservices use _ZLogger_ under the hood, so you can access those methods directly if you want to. ```csharp -[ClientCallable] -public void SampleLog() -{ - Log.Default.ZLogInformation($"Hello"); +[ClientCallable] +public void SampleLog() +{ + Log.Default.ZLogInformation($"Hello"); } ``` !!! info - Local microservice logs will not appear in Portal unless the `BEAM_LOCAL_OTEL` environment variable is set. + Local microservice logs will not appear in the Portal unless the `BEAM_LOCAL_OTEL` environment variable is set. ### Log Level -Each log has a _level_, or an _importance_ rating. Logs are one of the following, +Each log has a _level_, or an _importance_ rating. Logs are one of the following, - _Critical_ - _Error_ - _Warning_ @@ -56,7 +56,7 @@ Each log has a _level_, or an _importance_ rating. Logs are one of the following - _Debug_ - _Verbose_ -When you run a Microservice locally, you will see log messages at the _Debug_ level and above. However, in a deployed Microservice, you will only see **Information** and above. This is called the _Log Level_. It is considered best practice to avoid logging _Debug_ and _Verbose_ logs in production, because they negatively impact performance. +When you run a Microservice locally, you will see log messages at the _Debug_ level and above. However, in a deployed Microservice, you will only see **Information** and above. This is called the _Log Level_. Best practice is to avoid logging _Debug_ and _Verbose_ logs in production, as they negatively impact performance. The `Log` type has methods for each type of log level. @@ -66,21 +66,21 @@ The `Log` type has methods for each type of log level. #### Request Dynamic Log Levels -In version 6.0+, you can override the log level per request based on the player calling your Microservice, or the path being invoked on the service. By default, the log level for the entire service is _Information_, but if there was an error-prone route, or a specific user was experiencing issues, you could set the log level to _Debug_ for that use case, without affecting the log level for anything else. +In version 6.0+, you can override the log level per request based on the player calling your Microservice, or the path being invoked on the service. By default, the log level for the entire service is _Information_, but if there was an error-prone route, or a specific user was experiencing issues, you could set the log level to _Debug_ for that use case, without affecting the log level for anything else. -To set a dynamic log level, go to the Portal's microservice page, and create a new _Log Config Rule_. Once you create a rule, the Microservice will automatically update to emit logs at the new level. It may take a few seconds for the log level to change. +To set a dynamic log level, go to the Portal's microservice page, and create a new _Log Config Rule_. Once you create a rule, the Microservice will automatically update to emit logs at the new level. It may take a few seconds for the log level to change. ### Attributes -In version 6.0+, Microservice logs include attributes that can be explored in Portal. +In version 6.0+, Microservice logs include attributes that can be explored in the Portal. #### Single Custom Attributes -You can add custom attributes per log message by using the standard string formatting approach: +You can add custom attributes per log message by using the standard string formatting approach: ```csharp -[ClientCallable] -public void CustomAttribute(int a) -{ - Log.Information("attribute {a}", a); +[ClientCallable] +public void CustomAttribute(int a) +{ + Log.Information("attribute {a}", a); } ``` @@ -89,11 +89,11 @@ If the method was invoked with `a` equal to `42`, then the rendered log message attribute 42 ``` -However, the attribute, `a`, is available for querying in Portal. Use a custom search expression for `a:42` to find any log messages with the `a` attribute value of `42`. +However, the attribute, `a`, is available for querying in the Portal. Use a custom search expression for `a:42` to find any log messages with the `a` attribute value of `42`. #### Scoped Custom Attributes -It is possible to automatically add attributes to an entire sequence of logs. For example, imagine you wanted to tag a series of log lines as being part of an algorithm. +You can automatically add attributes to an entire sequence of logs. For example, imagine you wanted to tag a series of log lines as being part of an algorithm. ```csharp [ClientCallable] @@ -110,7 +110,7 @@ public bool CheckIfNumberIsOdd(int number) ["operation"] = nameof(CheckIfNumberIsOdd), ["number"] = number }); - + Log.Debug("Checking number"); var isOdd = number % 2 == 1; @@ -135,11 +135,11 @@ number is even! 42 is odd=False ``` -However, the _attributes_ available on the log lines will include the `operation` and `number`, while the attributes on the last log will not. +However, the _attributes_ available on the log lines will include the `operation` and `number`, while the attributes on the last log will not. #### Defined Custom Attributes -In the previous section, the custom log attributes are localized to specific log events. The attributes are searchable in Portal, but they will not appear as _known_ attributes, because they are not declared at any top level location. In order to define known attributes, you need to use a custom `ITelemetryAttributeProvider`. +In the previous section, the custom log attributes are localized to specific log events. The attributes are searchable in the Portal, but they will not appear as _known_ attributes, because they are not declared at any top level location. In order to define known attributes, you need to use a custom `ITelemetryAttributeProvider`. ```csharp public class CustomAttributes : ITelemetryAttributeProvider @@ -166,31 +166,31 @@ public class CustomAttributes : ITelemetryAttributeProvider } ``` -And register the `CustomAttributes` in the dependency scope of your service. +And register the `CustomAttributes` in the dependency scope of your service. ```csharp -public static async Task Main() -{ - await BeamServer - .Create() - .IncludeRoutes(routePrefix: "") - .ConfigureServices(builder => - { - builder.AddSingleton(); - }) .RunForever(); +public static async Task Main() +{ + await BeamServer + .Create() + .IncludeRoutes(routePrefix: "") + .ConfigureServices(builder => + { + builder.AddSingleton(); + }) .RunForever(); } ``` -The various _CreateAttribute_ functions should add attributes to the current context of a request. +The various _CreateAttribute_ functions should add attributes to the current context of a request. - `DefaultAttributes` allow you to add an attribute to _every_ log line. -- `ConnectionAttributes` allow you to add an attribute to every log line that is part of a specific _connection_ to Beamable. When a Microservice runs locally, there is only a single connection, but in a deployed environment, there are _10_ connections. -- `RequestAttributes` allow you add attributes to every log line per _request_. +- `ConnectionAttributes` allow you to add an attribute to every log line that is part of a specific _connection_ to Beamable. When a Microservice runs locally, there is only a single connection, but in a deployed environment, there are _10_ connections. +- `RequestAttributes` allow you add attributes to every log line per _request_. -The `GetDescriptors()` function must return a description for all attributes you want to be defined. When an attribute is described from the return value, the title and description will appear in Portal. +The `GetDescriptors()` function must return a description for all attributes you want to be defined. When an attribute is described from the return value, the title and description will appear in the Portal. ### Standard Log Attributes -There are several standard log attributes that will be included automatically. Some of these are from the Open Telemetry (OTEL) standard, and others are from Beamable's logging middleware. +There are several standard log attributes that will be included automatically. Some of these are from the Open Telemetry (OTEL) standard, and others are from Beamable's logging middleware. | Name | Description | Conditions | Standard Set | LEVEL | | --------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------ | ------- | @@ -214,46 +214,46 @@ There are several standard log attributes that will be included automatically. S ### Third Party Log Hosting -Starting with version 6.0, it is possible to send Microservice logs to a third parties. In this example, we will use BetterStack. +Starting with version 6.0, you can send Microservice logs to third-party log hosting services. In this example, we will use BetterStack. -This section will assume you have set up a BetterStack account, and created a _Source_ such that you have a _source token_ and an _ingesting host_. +This section will assume you have set up a BetterStack account, and created a _Source_ such that you have a _source token_ and an _ingesting host_. To start, we will configure locally running Microservices to send data to BetterStack. To start, create this file called `config.yaml` next to your `BeamableServices.sln` file. ```yml -receivers: - otlp: - protocols: - grpc: - endpoint: 0.0.0.0:4317 - http: - endpoint: 0.0.0.0:4318 - -processors: - batch: - -exporters: - otlphttp/betterstack: - endpoint: "${env:BETTERSTACK_ENDPOINT}" - headers: - Authorization: "${env:BETTERSTACK_AUTH}" - -service: - pipelines: - metrics/betterstack: - receivers: [otlp] - processors: [batch] - exporters: [otlphttp/betterstack] - logs/betterstack: - receivers: [otlp] - processors: [batch] +receivers: + otlp: + protocols: + grpc: + endpoint: 0.0.0.0:4317 + http: + endpoint: 0.0.0.0:4318 + +processors: + batch: + +exporters: + otlphttp/betterstack: + endpoint: "${env:BETTERSTACK_ENDPOINT}" + headers: + Authorization: "${env:BETTERSTACK_AUTH}" + +service: + pipelines: + metrics/betterstack: + receivers: [otlp] + processors: [batch] + exporters: [otlphttp/betterstack] + logs/betterstack: + receivers: [otlp] + processors: [batch] exporters: [otlphttp/betterstack] ``` > [!TIP] -> Learn more about this file by reading the [documentation](https://opentelemetry.io/docs/collector/configuration/) +> Learn more about this file by reading the [documentation](https://opentelemetry.io/docs/collector/configuration/) -Prepare the following environment variables. +Prepare the following environment variables. ```sh # Send local log data to Portal for debug purposes export BEAM_LOCAL_OTEL=true @@ -261,24 +261,24 @@ export BEAM_LOCAL_OTEL=true # Use the tokenSource from better stack instead of 123 export BETTERSTACK_AUTH="Bearer 123" -# Use the ingestingHost +# Use the ingestingHost export BETTERSTACK_ENDPOINT="https://123.eu-nbg-2.betterstackdata.com" ``` -Run the standard Open Telemetry collector in Docker, +Run the standard Open Telemetry collector in Docker, ```sh -docker run -p 4317:4317 -p 4318:4318 \ - -v $(pwd)/config.yaml:/etc/otelcol-contrib/config.yaml \ - -e BETTERSTACK_ENDPOINT=$BETTERSTACK_ENDPOINT \ - -e BETTERSTACK_AUTH=$BETTERSTACK_AUTH \ +docker run -p 4317:4317 -p 4318:4318 \ + -v $(pwd)/config.yaml:/etc/otelcol-contrib/config.yaml \ + -e BETTERSTACK_ENDPOINT=$BETTERSTACK_ENDPOINT \ + -e BETTERSTACK_AUTH=$BETTERSTACK_AUTH \ ghcr.io/open-telemetry/opentelemetry-collector-releases/opentelemetry-collector-contrib:0.125.0 ``` -Now you have a locally running telemetry collector. We need to configure your local Microservice to _use_ the collector. Prepare the following environment variables, +Now you have a locally running telemetry collector. We need to configure your local Microservice to _use_ the collector. Prepare the following environment variables, ```sh -export BEAM_DISABLE_STANDARD_OTEL=1 -export BEAM_OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318 +export BEAM_DISABLE_STANDARD_OTEL=1 +export BEAM_OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318 export BEAM_OTEL_EXPORTER_OTLP_PROTOCOL=HttpProtobuf ``` @@ -305,15 +305,15 @@ RUN curl -fL -o /tmp/otelcol.tar.gz \ https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.125.0/otelcol-contrib_0.125.0_linux_amd64.tar.gz && \ mkdir -p /otel-contrib && \ tar -xzf /tmp/otelcol.tar.gz -C /otel-contrib && \ - rm /tmp/otelcol.tar.gz + rm /tmp/otelcol.tar.gz # Copy the local config yaml file into the image COPY config.yaml /otel-contrib/config.yaml ``` -Copy the `config.yaml` file from before and paste it next to the `Dockerfile`. +Copy the `config.yaml` file from before and paste it next to the `Dockerfile`. -Add the following functions to your `Program.cs` +Add the following functions to your `Program.cs` > [!WARNING] > This sample hard-codes the BetterStack auth for simplicity. We are working on better solutions for secret management. Please check in soon. @@ -332,7 +332,7 @@ public static void SetupCollector() var isDocker = Environment.GetEnvironmentVariable("DOTNET_RUNNING_IN_CONTAINER") == "true"; if (!isDocker) return; - + Environment.SetEnvironmentVariable("BETTERSTACK_AUTH", "Bearer REDACTED"); Environment.SetEnvironmentVariable("BETTERSTACK_ENDPOINT", "https://REDACTED.eu-nbg-2.betterstackdata.com"); @@ -346,14 +346,14 @@ public static void SetupCollector() p.Exited += (sender, args) => { - // panic! If the collector has stopped, then logs aren't getting sent anywhere. + // panic! If the collector has stopped, then logs aren't getting sent anywhere. // and all we can do is explode so that AWS will re-place the task. Environment.Exit(1); }; if (!p.Start()) { - // panic! If the collector did not start, then logs aren't getting sent anywhere. + // panic! If the collector did not start, then logs aren't getting sent anywhere. // and all we can do is explode so that AWS will re-place the task. Environment.Exit(1); @@ -366,23 +366,23 @@ public static void SetupCollector() And invoke those methods before starting the service. ```csharp -/// -/// The entry point for the service. -/// -public static async Task Main() -{ - SetupTelemetry(); - SetupCollector(); - await BeamServer - .Create() - .IncludeRoutes(routePrefix: "") - .RunForever(); +/// +/// The entry point for the service. +/// +public static async Task Main() +{ + SetupTelemetry(); + SetupCollector(); + await BeamServer + .Create() + .IncludeRoutes(routePrefix: "") + .RunForever(); } ``` Deploy the service ```sh -dotnet beam deploy release +dotnet beam deploy release ``` > [!tip] @@ -390,7 +390,7 @@ dotnet beam deploy release As you interact with the service, you should see logs appear in BetterStack. -This section dealt with exporting logs to BetterStack, but the situation is similar for other log providers, like DataDog. The part that needs to change is how the collector is configured. +This section dealt with exporting logs to BetterStack, but the situation is similar for other log providers, like DataDog. The part that needs to change is how the collector is configured. > [!WARNING] > When you do this, you will not see logs in Beamable. This demonstration _replaces_ the Beamable logs for BetterStack. diff --git a/docs/cli/guides/ms-routing.md b/docs/cli/guides/ms-routing.md index b8ff01070..93ae25351 100644 --- a/docs/cli/guides/ms-routing.md +++ b/docs/cli/guides/ms-routing.md @@ -4,7 +4,7 @@ Configure Standalone Microservice routing and client generation ## Dependencies -Before you can configure Beamable Standalone Microservices, you need to complete the [Getting-Started Guide](getting-started.md). That means having [Dotnet 10](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) installed, and getting the [Beam CLI](https://www.nuget.org/packages/Beamable.Tools). +Before you can configure Beamable Standalone Microservices, you need to complete the [Getting-Started Guide](getting-started.md). That means having [.NET 10](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) installed, and getting the [Beam CLI](https://www.nuget.org/packages/Beamable.Tools). You can confirm you have everything installed checking the versions of the tools. ```sh @@ -22,12 +22,12 @@ dotnet beam project new service HelloWorld ## Microservice Routing -Beamable Microservices use a privileged web socket to communicate with Beamable's existing APIs and services. There is a custom Beamable application level protocol, _Thorium_, that allows a Microservice to receive HTTPS traffic sent to `https://api.beamable.com`. However, for the Microservice to receive the traffic, the HTTP request needs to meet the following requirements, +Beamable Microservices use a privileged web socket to communicate with Beamable's existing APIs and services. There is a custom Beamable application level protocol, _Thorium_, that allows a Microservice to receive HTTPS traffic sent to `https://api.beamable.com`. However, for the Microservice to receive the traffic, the HTTP request needs to meet the following requirements, -1. The `uri` of the HTTP request must have a `path` that maps to the desired Microservice. -2. The HTTP request must have an `X-DE-SCOPE` header, and +1. The `uri` of the HTTP request must have a `path` that maps to the desired Microservice. +2. The HTTP request must have an `X-DE-SCOPE` header, and 3. _Optionally_, the HTTP request should have a `X-BEAM-SERVICE-ROUTING-KEY` header that carries a map of service routing keys, and -4. _Optionally_, the HTTP request should have an `Authorization` header that carries a Bearer Token. +4. _Optionally_, the HTTP request should have an `Authorization` header that carries a Bearer Token. #### Path Routing @@ -48,17 +48,17 @@ The variables are described in the following table. | `serviceName` | yes | `HelloWorld` | The name of your service. This maps to the Beam Id of your service. | | `method` | yes | `Add` | The name of the Method you want to invoke. | -When the `host` (`api.beamable.com`) receives an HTTP request with the following `uri` format, the request will be deconstructed into the variable components, and the contents of the HTTP request will be forwarded to your Microservice via the _Thorium_ web socket protocol. The Microservice receives the request, and uses the `method` component of the original request to invoke the right `[Callable]` method. +When the `host` (`api.beamable.com`) receives an HTTP request with the following `uri` format, the request will be deconstructed into the variable components, and the contents of the HTTP request will be forwarded to your Microservice via the _Thorium_ web socket protocol. The Microservice receives the request, and uses the `method` component of the original request to invoke the right `[Callable]` method. #### X-BEAM-SERVICE-ROUTING-KEY Header -When a Microservice is started locally, it may share the same name with a Microservice running in the Beamable cloud. When this happens, and your local development machine is generating traffic for the named service, the _routing key_ defines _which_ Microservice instance (the local or remote) receives the traffic. +When a Microservice is started locally, it may share the same name with a Microservice running in the Beamable cloud. When this happens, and your local development machine is generating traffic for the named service, the _routing key_ defines _which_ Microservice instance (the local or remote) receives the traffic. -A Microservice instance may optionally register a routing key, and if they do, then they will only receive traffic that includes the routing key in a custom `X-BEAM-SERVICE-ROUTING-KEY` header. +A Microservice instance may optionally register a routing key, and if they do, then they will only receive traffic that includes the routing key in a custom `X-BEAM-SERVICE-ROUTING-KEY` header. -All microservice instances running on the Beamable cloud _do not_ register any routing keys, so they receive traffic that does not include any `X-BEAM-SERVICE-ROUTING-KEY` value. +All microservice instances running on the Beamable cloud _do not_ register any routing keys, so they receive traffic that does not include any `X-BEAM-SERVICE-ROUTING-KEY` value. -The format of the `X-BEAM-SERVICE-ROUTING-KEY` value should be a series of `:` pairs, separated by commas. Here is an example of a routing key header value that routes two services, +The format of the `X-BEAM-SERVICE-ROUTING-KEY` value should be a series of `:` pairs, separated by commas. Here is an example of a routing key header value that routes two services, ``` serviceA:routingKeyA,serviceB:routingKeyB @@ -66,23 +66,23 @@ serviceA:routingKeyA,serviceB:routingKeyB #### X-DE-SCOPE Header -In addition to specifying the `cid` and `pid` in the `uri` of the HTTP request, those values must also be sent in a special HTTP header, `X-DE-SCOPE`. The value for this header should take the format, +In addition to specifying the `cid` and `pid` in the `uri` of the HTTP request, those values must also be sent in a special HTTP header, `X-DE-SCOPE`. The value for this header should take the format, ```javascript var scope = cid + '.' + pid; ``` -#### Authorization +#### Authorization -Finally, while not required, it is important to send an HTTP authorization header in the form of a Bearer token. The bearer token should be a valid access token for a Beamable Player. These tokens can be fetched from the Portal, or you can use the following command to view the token information from a local beamable CLI project. +Finally, while not required, we recommend sending an HTTP authorization header in the form of a Bearer token. The bearer token should be a valid access token for a Beamable Player. These tokens can be fetched from the Portal, or you can use the following command to view the token information from a local beamable CLI project. ```sh cat .beamable/temp/auth.beam.json ``` -Beamable does not require that any access token be provided via an authorization header. However, if an authorization header is provided, then Beamable will decorate the request with account information before the request is forwarded to the Microservice. The Microservice itself may enforce the account details to have minimal access permissions. These constraints vary based on the type of `[Callable]` attribute you use. +Beamable does not require that any access token be provided via an authorization header. However, if an authorization header is provided, then Beamable will decorate the request with account information before the request is forwarded to the Microservice. The Microservice itself may enforce the account details to have minimal access permissions. These constraints vary based on the type of `[Callable]` attribute you use. -The account information is accessible via the `Context.UserId` property when executing the `[Callable]` method. +The account information is accessible via the `Context.UserId` property when executing the `[Callable]` method. | Attribute | Authorization Requirements | | --------------------- | ------------------------------------------------------------------------------------------------------------ | @@ -97,33 +97,33 @@ The account information is accessible via the `Context.UserId` property when exe You should be using the Beamable SDK in your Unity projects that use Standalone Microservices. Otherwise, there will be many compile errors as the Beamable SDK is not available. -Microservices can automatically generate client code for the Unity game engine. First, a Unity project needs to be linked to the `.beamable` workspace. To do this, use the project add-unity-project command. +Microservices can automatically generate client code for the Unity game engine. First, a Unity project needs to be linked to the `.beamable` workspace. To do this, use the project add-unity-project command. ```sh dotnet beam project add-unity-project ``` -The given path should be the relative path to the Unity project. If it isn't right, the CLI will offer an explorative search flow to identify a valid Unity project. +The given path should be the relative path to the Unity project. If it isn't right, the CLI will offer an explorative search flow to identify a valid Unity project. After the command has run, there will be a `.beamable/linked-projects.json` file. You can review it to double check your project has been added correctly. ```sh -MyProject % cat .beamable/linked-projects.json +MyProject % cat .beamable/linked-projects.json { "unityProjectsPaths": [ "../UnityProject" ], "unrealProjectsPaths": [] -}% +}% ``` -When there is a linked project, anytime a Microservice _builds_, it will automatically generate client code for the Unity project to use. This can be accessed via the `BeamContext`. +When there is a linked project, anytime a Microservice _builds_, it will automatically generate client code for the Unity project to use. This can be accessed via the `BeamContext`. ```csharp public async Promise TalkToMicroservice(){ - var ctx = await BeamContext.Default.Instance; - var client = ctx.Microservices().HelloWorld(); + var ctx = await BeamContext.Default.Instance; + var client = ctx.Microservices().HelloWorld(); var sum = await client.Add(1, 2); } ``` @@ -132,20 +132,20 @@ The automatic client code generation can be disabled when a project builds by mo ### Open API -It is possible to use the project oapi command to generate an Open API document and then use open source tools to transpile the document into a client in some other programming language. +You can use the project oapi command to generate an Open API document and then use open source tools to transpile the document into a client in some other programming language. ```sh dotnet beam project oapi --output example.json --ids MyService ``` -In fact, that command can baked into the Microservice's `.csproj` file with a custom build target. This requires that the `` property is set, which only happens when you run the project from the IDE. See the generate-props command to extend the `` property outside of IDE use cases. +In fact, that command can baked into the Microservice's `.csproj` file with a custom build target. This requires that the `` property is set, which only happens when you run the project from the IDE. See the generate-props command to extend the `` property outside of IDE use cases. ```xml - - + + ``` -Then, you can use the open source [Open API Generator](https://openapi-generator.tech/docs/generators/javascript/) to build a local javascript client. This snippet uses docker to interact with the generator tool, but you can also use `npm`. +Then, you can use the open source [Open API Generator](https://openapi-generator.tech/docs/generators/javascript/) to build a local javascript client. This snippet uses docker to interact with the generator tool, but you can also use `npm`. ```sh docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \ @@ -159,7 +159,7 @@ docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \ In this example, we need to use `browserify` to convert the generated client code into a valid browser script. ```sh npm install -g browserify -browserify ./dist/index.js --standalone helloWorld > ../../app/bundle.js +browserify ./dist/index.js --standalone helloWorld > ../../app/bundle.js ``` Then, a sample web page might use a similar script to interact with the Microservice. @@ -179,7 +179,7 @@ Then, a sample web page might use a similar script to interact with the Microser var client = new helloWorld.ApiClient(host); client.authentications['scope'].apiKey = cid + '.' + pid; client.authentications['user'].accessToken = refreshToken - + var api = new helloWorld.UncategorizedApi(client); var args = new helloWorld.AddRequestArgs(); args.a = 2; diff --git a/docs/cli/guides/ms-storage.md b/docs/cli/guides/ms-storage.md index 7a961f257..49edea73b 100644 --- a/docs/cli/guides/ms-storage.md +++ b/docs/cli/guides/ms-storage.md @@ -4,7 +4,7 @@ Add database storage to Beamable Standalone Microservices ## Dependencies -Before you can use Beamable Storage Objects, you need to complete the [Getting-Started Guide](getting-started.md). That means having [Dotnet 10](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) installed, and getting the [Beam CLI](https://www.nuget.org/packages/Beamable.Tools). +Before you can use Beamable Storage Objects, you need to complete the [Getting-Started Guide](getting-started.md). That means having [.NET 10](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) installed, and getting the [Beam CLI](https://www.nuget.org/packages/Beamable.Tools). You can confirm you have everything installed checking the versions of the tools. ```sh @@ -21,16 +21,16 @@ dotnet beam project new service HelloWorld ## Storage Objects -A Storage Object is a MongoDB database. Beamable will host and manage a database on your behalf when you deploy your project. Locally, the Beam CLI creates a local mongo database inside a Docker container. Beamable never installs mongo directly on your host machine. +A Storage Object is a MongoDB database. Beamable will host and manage a database on your behalf when you deploy your project. Locally, the Beam CLI creates a local mongo database inside a Docker container. Beamable never installs mongo directly on your host machine. -To create a Storage Object, use the [project new storage](ms-workflow.md#creating-new-projects) command. +To create a Storage Object, use the [project new storage](ms-workflow.md#creating-new-projects) command. ```sh dotnet beam project new storage ``` -This creates a new `.csproj` in your existing `.sln`. You will also be prompted to assign a reference between the Storage Object and some Microservices. A Storage Object cannot exist independently of a Microservice. When you specify a dependency between a Storage Object and a Microservice, Beamable knows to pass the connection credentials to the Microservice. +This creates a new `.csproj` in your existing `.sln`. You will also be prompted to assign a reference between the Storage Object and some Microservices. A Storage Object cannot exist independently of a Microservice. When you specify a dependency between a Storage Object and a Microservice, Beamable knows to pass the connection credentials to the Microservice. -When developing locally, anytime a Microservice that depends on a Storage Object starts, it will make sure the Docker container for the Storage Object is running. If there is no running container, it will start a container. This can take several seconds and it may appear the service is failing to start. +When developing locally, anytime a Microservice that depends on a Storage Object starts, it will make sure the Docker container for the Storage Object is running. If there is no running container, it will start a container. This can take several seconds and it may appear the service is failing to start. The code documentation explains how to interact with a Storage Object. diff --git a/docs/cli/guides/ms-upm.md b/docs/cli/guides/ms-upm.md index 2252d39ca..ed5e2b5d0 100644 --- a/docs/cli/guides/ms-upm.md +++ b/docs/cli/guides/ms-upm.md @@ -4,8 +4,8 @@ Sharing a Microservice with Unity via UPM ## Dependencies -Before you can use Distribute a Microservice with UPM, you need to complete the -[Getting-Started Guide](getting-started.md). That means having [Dotnet 10](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) installed, and getting the [Beam CLI](https://www.nuget.org/packages/Beamable.Tools). +Before you can use Distribute a Microservice with UPM, you need to complete the +[Getting-Started Guide](getting-started.md). That means having [.NET 10](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) installed, and getting the [Beam CLI](https://www.nuget.org/packages/Beamable.Tools). You can confirm you have everything installed checking the versions of the tools. ```sh @@ -13,7 +13,7 @@ dotnet --version dotnet beam version # beam --version also works. ``` -You also need to have a local `.beamable` workspace with a Beamable +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. ```sh beam init Project @@ -23,20 +23,20 @@ dotnet beam project new service Service ## Steps -Standalone Microservice projects can be distributed as Unity Package Manager -(UPM) packages, which allows downstream Unity projects to re-use an existing -Microservice. +Standalone Microservice projects can be distributed as Unity Package Manager +(UPM) packages, which allows downstream Unity projects to re-use an existing +Microservice. -However, there are several configuration steps required in the Standalone -Microservice project. +However, there are several configuration steps required in the Standalone +Microservice project. ### Preparing the Microservice -Follow these steps to convert an existing Standalone Microservice into a UPM -compatible Microservice. +Follow these steps to convert an existing Standalone Microservice into a UPM +compatible Microservice. 1. Rename "services" folder to "services~" -2. Modify the `.sln` file to mirror the folder name change. +2. Modify the `.sln` file to mirror the folder name change. 3. Create a local `Assets` folder next to the `.beamable` folder 4. Create a `Runtime` folder and a `Runtime/Client` folder next to the `.beamable` folder 5. Create a file in the `.beamable` folder called `linked-projects.json`, @@ -47,8 +47,8 @@ compatible Microservice. ] } ``` - - So far, your folder structure should at least have these files. + + So far, your folder structure should at least have these files. ``` /Project /.beamable @@ -82,14 +82,14 @@ asmdef` (replace `"Service"` with your service name), and paste the following, ``` Make sure to replace `"Service"` in the `"name"` field with your service name. -7. Now you are ready to generate the client code. To do this, run the - following command **AFTER** building your Microservice. This command - should be run from the `/services~/Service` folder. +7. Now you are ready to generate the client code. To do this, run the + following command **AFTER** building your Microservice. This command + should be run from the `/services~/Service` folder. ```sh dotnet beam project generate-client ./bin/Debug/net8.0/Service.dll --output-links --output-path-hints "Service=Runtime/Client/ServiceClient.cs" --logs v ``` -8. You need to create a `package.json` file. Place it next to the `/Assets` - folder in the Microservice project. +8. You need to create a `package.json` file. Place it next to the `/Assets` + folder in the Microservice project. ```json { "name": "com.service", @@ -97,8 +97,8 @@ asmdef` (replace `"Service"` with your service name), and paste the following, "displayName": "Demo" } ``` - -Finally, your project structure should look similar to this, + +Finally, your project structure should look similar to this, So far, your folder structure should at least have these files. ``` @@ -121,16 +121,16 @@ So far, your folder structure should at least have these files. ### Preparing the Unity Project -Now that the Microservice is ready, in order to import it into a Unity -project as a UPM package, follow these steps. +Now that the Microservice is ready, to import it into a Unity +project as a UPM package, follow these steps. -1. Ensure that the Unity project is referencing Beamable's packages. - At least Beamable version `com.beamable` and `com.beamable.server` 2.1.3 is - required. -2. In Unity Package Manager, add a package from disk, and select the path to - your created `package.json` from the previous steps. -3. Modify the `.beamable/additional-project-paths.json` file in the Unity - project and add the path to the UPM project folder. +1. Ensure that the Unity project is referencing Beamable's packages. + At least Beamable version `com.beamable` and `com.beamable.server` 2.1.3 is + required. +2. In Unity Package Manager, add a package from disk, and select the path to + your created `package.json` from the previous steps. +3. Modify the `.beamable/additional-project-paths.json` file in the Unity + project and add the path to the UPM project folder. ```json ["/path/to/Project"] ``` diff --git a/docs/cli/guides/ms-workflow.md b/docs/cli/guides/ms-workflow.md index cf38b4a4a..81783eb1e 100644 --- a/docs/cli/guides/ms-workflow.md +++ b/docs/cli/guides/ms-workflow.md @@ -4,7 +4,7 @@ Managing Microservices from the CLI ## Dependencies -Before you can manage Beamable Standalone Microservices, you need to complete the [Getting-Started Guide](getting-started.md). That means having [Dotnet 10](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) installed, and getting the [Beam CLI](https://www.nuget.org/packages/Beamable.Tools). +Before you can manage Beamable Standalone Microservices, you need to complete the [Getting-Started Guide](getting-started.md). That means having [.NET 10](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) installed, and getting the [Beam CLI](https://www.nuget.org/packages/Beamable.Tools). You can confirm you have everything installed checking the versions of the tools. ```sh @@ -14,9 +14,9 @@ dotnet beam version # dotnet beam --version also works. ## Creating New Projects {#creating-new-projects} -New Microservices, Storages, and Common projects can be created within an existing `.beamable` folder workspace. +New Microservices, Storages, and Common projects can be created within an existing `.beamable` folder workspace. -Use the `beam project new` commands to create new projects. +Use the `beam project new` commands to create new projects. ```sh dotnet beam project new service # create a new Microservice @@ -26,7 +26,7 @@ dotnet beam project new common-lib # create a new Common Library All of these commands will create a new `.csproj` project and configure it to work with Beamable. The new `.csproj` will be referenced in the `.sln` file. If there is already a `.sln` file, then the first `.sln` file detected in the `.beamable` workspace will be modified to include the `.csproj` reference. If there is no `.sln`, then a file called `BeamableServices.sln` will be created. However, the `--sln` option may be given to override this behavior and specify a .`sln` file to use. -Projects will be created in the `BeamableServices/services/` directory by default. +Projects will be created in the `BeamableServices/services/` directory by default. ## Finding Microservices @@ -34,24 +34,24 @@ Once there is a Microservice in your `.beamable` workspace, you can check for it ```sh MyProject % dotnet beam project list - { - "localServices": [ - { - "name": "HelloWorld", - "projectPath": "services/HelloWorld" - } - ], - "localStorages": [ - ] - } + { + "localServices": [ + { + "name": "HelloWorld", + "projectPath": "services/HelloWorld" + } + ], + "localStorages": [ + ] + } ``` ## Running Microservices -Microservices can be run in several ways, +Microservices can be run in several ways, 1. using the IDE, 2. using `dotnet` commands directly, or -3. using `beam` commands. +3. using `beam` commands. The project run command will turn on a service. @@ -70,20 +70,20 @@ MyProject % dotnet beam project ps HelloWorld is available prefix=[Chriss-MacBook-Pro-2] docker=[False] ``` -The `prefix` in the log declares that the service is running locally, and the `docker` log declares that the service is running through dotnet, and not inside a docker container. +The `prefix` in the log declares that the service is running locally, and the `docker` log declares that the service is running through dotnet, and not inside a docker container. -Optionally, you can pass the `-w` flag to watch for changes to running services. +Optionally, you can pass the `-w` flag to watch for changes to running services. ## Stopping Services -If a service is running, then the project stop command may be used to stop the program. If the service is not running, then the command will have no output. However, if the service is running, it will log a stop message. +If a service is running, then the project stop command may be used to stop the program. If the service is not running, then the command will have no output. However, if the service is running, it will log a stop message. ```sh MyProject % dotnet beam project stop --ids HelloWorld stopped HelloWorld. ``` -When a service is stopped this way, you should expect to see a log in the Microservice itself, +When a service is stopped this way, you should expect to see a log in the Microservice itself, ``` [Info] Stopping service through debug-server due to reason=[cli-request] @@ -91,7 +91,7 @@ When a service is stopped this way, you should expect to see a log in the Micros ## Observing Logs -When a service is run, the process that starts the service should receive the log outputs. For example, if the service is run through the IDE, then the IDE should receive the logs from the service. However, it is possible to attach to the logs of a running service from a separate process. +When a service is run, the process that starts the service should receive the log outputs. For example, if the service is run through the IDE, then the IDE should receive the logs from the service. However, you can attach to the logs of a running service from a separate process. For example, imagine that a service is run through `dotnet` directly, diff --git a/docs/cli/guides/upgrading.md b/docs/cli/guides/upgrading.md index c8c98e79f..587a796e9 100644 --- a/docs/cli/guides/upgrading.md +++ b/docs/cli/guides/upgrading.md @@ -4,30 +4,30 @@ Update the Beamable CLI and workspaces ## Update the CLI -To install the latest version of the CLI, use the following command. +To install the latest version of the CLI, use the following command. ```sh dotnet beam version install latest ``` -You can also search for available versions with the `beam version ls` command. The `beam version install` command accepts any valid version instead of the "latest" string in the example above. +You can also search for available versions with the `beam version ls` command. The `beam version install` command accepts any valid version instead of the "latest" string in the example above. !!! info ".config/dotnet-tools.json" - As of CLI 3.0.0, Standalone Microservice Projects use dotnet local tool installations for Beamable. The version number is stored in a special dotnet file, `.config/dotnet-tools.json`. This file should be committed to version control. Please do not edit this file directly, and prefer instead to use the `beam version` command suite. + As of CLI 3.0.0, Standalone Microservice Projects use dotnet local tool installations for Beamable. The version number is stored in a special dotnet file, `.config/dotnet-tools.json`. This file should be committed to version control. Please do not edit this file directly, and prefer instead to use the `beam version` command suite. ## Migration Guide -The Beamable CLI may include changes between versions that require developer intervention. If there are known steps that a developer must perform manually, they are documented below. The following sections describe the required updates from one version to another. +The Beamable CLI may include changes between versions that require developer intervention. If there are known steps that a developer must perform manually, they are documented below. The following sections describe the required updates from one version to another. These are ordered with the latest versions towards the top, and the older versions toward the bottom of the document. **When jumping multiple versions (A.A.A -> C.C.C), apply the migrations without skipping steps (A.A.A -> B.B.B -> C.C.C).** ### From 6.2.x to 7.0.0 -There is one large change between CLI 6 and CLI 7, but there is an automatic upgrade path. +There is one large change between CLI 6 and CLI 7, but there is an automatic upgrade path. #### Configuration Refactor -The 7.0 release restructures the `.beamable` folder in your project. Previously, there were several single-use files in the folder. Now, those files have been merged into a single `config.beam.json`. +The 7.0 release restructures the `.beamable` folder in your project. Previously, there were several single-use files in the folder. Now, those files have been merged into a single `config.beam.json`. The first time you run any command with CLI 7.0, your config files will be automatically merged into the new format. @@ -40,22 +40,22 @@ There are no compile time breaking changes between 5.x and 6.0. However, there a #### Microservice Logging Changes The 6.0 release completely changes the way that Microservices send and store log information. Previously, Microservices sent logs in a proprietary format to Amazon Cloud Watch. In the new release, logs are formatted as standard [open telemetry](https://opentelemetry.io/docs/specs/otel/logs/) data, and sent to a log warehouse via an [otel collector](https://opentelemetry.io/docs/collector/). The change is transparent to the Microservice layer, and you do not need to make any changes to enable the new logs. -When you upgrade your service to 6.0, you will begin to see a new log workflow in the Portal. **Your old logs will not be available**. Only the new logs are available. Beamable only retains log data for 2 weeks anyway, but if you _must_ have access to your existing 2 weeks of log information, you will need Pro Support, and you must reach out directly to Beamable Support. +When you upgrade your service to 6.0, you will begin to see a new log workflow in the Portal. **Your old logs will not be available**. Only the new logs are available. Beamable only retains log data for 2 weeks anyway, but if you _must_ have access to your existing 2 weeks of log information, you will need Pro Support, and you must reach out directly to Beamable Support. #### Telemetry Warning -The 6.0 CLI will collect usage data and send it back to Beamable. By default, the CLI will ask you to opt into sending the usage information. The result of your selection is stored in the `.beamable/otel-config.json` file. You can change the `BeamCliAllowTelemetry` property to opt in or out of the usage collection. +The 6.0 CLI will collect usage data and send it back to Beamable. By default, the CLI will ask you to opt into sending the usage information. The result of your selection is stored in the `.beamable/otel-config.json` file. You can change the `BeamCliAllowTelemetry` property to opt in or out of the usage collection. Additionally, you can completely opt out of usage reporting by setting the `BEAM_NO_TELEMETRY` environment variable. #### `services` command removed The `beam services` command suite has been removed in CLI 6.0. The `service` command group were about managing various _Docker_ related tasks, but most of the commands had fallen into disuse. There were two common use cases for the `service` commands, -1. running Microservice projects locally, -2. building Microservice _Docker_ images and testing the containers. +1. running Microservice projects locally, +2. building Microservice _Docker_ images and testing the containers. -To run a Microservice, please use the `dotnet beam project run` command, or simply run the service from your IDE, or with `dotnet run`. +To run a Microservice, please use the `dotnet beam project run` command, or simply run the service from your IDE, or with `dotnet run`. -To build and validate _Docker_ images locally, there is a new option on the `beam deploy plan` command that will generate a [docker compose](https://docs.docker.com/compose/) project out of the _Docker_ images. Use the `--docker-compose-dir` option to create a docker compose workspace, and then use docker compose directly to turn on and off the docker containers. +To build and validate _Docker_ images locally, there is a new option on the `beam deploy plan` command that will generate a [docker compose](https://docs.docker.com/compose/) project out of the _Docker_ images. Use the `--docker-compose-dir` option to create a docker compose workspace, and then use docker compose directly to turn on and off the docker containers. ```sh dotnet beam deploy plan --docker-compose-dir Example @@ -65,8 +65,8 @@ docker compose up ### From 4.3.x to 5.0.0 -The upgrade from 4.x to 5 has a few breaking changes. Once your project is using -CLI 5+, run the following command to automatically fix known compiler errors, +The upgrade from 4.x to 5 has a few breaking changes. Once your project is using +CLI 5+, run the following command to automatically fix known compiler errors, ```sh beam checks scan --fix all ``` @@ -74,7 +74,7 @@ beam checks scan --fix all #### `MongoDb.Driver` Upgrade to 3.0 This fix will be automatically handled by running `beam checks scan --fix all` -The `MongoDb.Diver` package must be updated from the `2.19.2` version to `3.3.0`. +The `MongoDb.Diver` package must be updated from the `2.19.2` version to `3.3.0`. If your project does not include any storage objects, you can ignore this step. However, if you do have storage objects, then those projects likely include this reference in the `.csproj` files, @@ -91,24 +91,24 @@ package. You can also change the version number to exactly `3.3.0`. #### Replaced `Serilog` with `ZLogger` This fix will be automatically handled by running `beam checks scan --fix all` -`Serilog` is a popular logging framework in the dotnet ecosystem, and Beamable used -it extensively in earlier versions. However, with CLI 5+, Beamable migrated to -use `ZLogger`, which is a higher performance logging tool. +`Serilog` is a popular logging framework in the dotnet ecosystem, and Beamable used +it extensively in earlier versions. However, with CLI 5+, Beamable migrated to +use `ZLogger`, which is a higher performance logging tool. If your code uses the following types of log statements, then you will need to make a small -change, +change, ```csharp Log.Info("hello world"); ``` -The `Log` type used to come from `Serilog`'s namespace, but since `Serilog` is no -longer included in the package, the `Log` type will fail to compile. You should -see a `using` statement at the top of your file, +The `Log` type used to come from `Serilog`'s namespace, but since `Serilog` is no +longer included in the package, the `Log` type will fail to compile. You should +see a `using` statement at the top of your file, ```csharp using Serilog; ``` -This can be replaced with the following line, and the new `Log` type will be referenced. +This can be replaced with the following line, and the new `Log` type will be referenced. ```csharp using Beamable.Server; ``` @@ -116,17 +116,17 @@ using Beamable.Server; #### Game Server Federation uses new `Lobby` type This fix will be automatically handled by running `beam checks scan --fix all` -The `IFederatedGameServer` interface used to use the `Beamable.Experimental.Api.Lobbies.Lobby` -type, but in version 5+, it uses `Beamable.Api.Autogenerated.Models.Lobby`. +The `IFederatedGameServer` interface used to use the `Beamable.Experimental.Api.Lobbies.Lobby` +type, but in version 5+, it uses `Beamable.Api.Autogenerated.Models.Lobby`. The newer type is autogenerated, so as the Beamable Lobby API evolves over time, the -federation will receive the latest fields and data. +federation will receive the latest fields and data. The simple upgrade path is to change your `using` statement to reference the new type. -However, the access patterns into the two `Lobby` types are different enough that -much of your method will likely need to change as well. +However, the access patterns into the two `Lobby` types are different enough that +much of your method will likely need to change as well. A better approach is to explicitly list the `IFederatedGameServer.CreateGameServer()`'s -parameter with the new namespace, and then use a conversion tool to get back the old type. +parameter with the new namespace, and then use a conversion tool to get back the old type. #### Client Generation In the old CLI and Microservice packages, Unity and Unreal Engine client could we be automatically @@ -134,7 +134,7 @@ generated when the Microservices were built. However, in CLI 5+, the engine inte are responsible for generating the client code, and the default behaviour is that a standalone Microservice project will _no longer generate client code automatically_. -It is possible to generate a unity client by hand using the following command, +You can generate a Unity client by hand using the following command, ```sh dotnet beam project generate-client-oapi --output-dir ./Path/To/Your/Unity/Folder/To/Put/Clients/In ``` @@ -144,7 +144,7 @@ into your services' `.csproj` files. You can find the target here, [CLI 4.3.0 .Targets File](https://github.com/beamable/BeamableProduct/blob/cli-4.3.0/microservice/microservice/Targets/Beamable.Microservice.Runtime.targets#L15) ```csharp -public Promise CreateGameServer(Beamable.Api.Autogenerated.Models.Lobby autoGeneratedlobby) +public Promise CreateGameServer(Beamable.Api.Autogenerated.Models.Lobby autoGeneratedlobby) { var lobby = autoGeneratedlobby.ConvertLobbyType(); // rest of method @@ -153,21 +153,19 @@ public Promise CreateGameServer(Beamable.Api.Autogenerated.Models.Lo #### Content CLI Commands The old version of the CLI had a set of content commands, and they have been -dramatically refactored and redesigned in CLI 5. If you had been using content -commands from the CLI, please reach out to Beamable for guidance. +dramatically refactored and redesigned in CLI 5. If you had been using content +commands from the CLI, please reach out to Beamable for guidance. ### From 3.0.1 to 4.0.0 -The upgrade from 3.0.x to 4.0.0 is relatively simple compared to other major -releases. +The upgrade from 3.0.x to 4.0.0 is relatively simple compared to other major +releases. #### Removed `net6.0` and `net7.0` support Unfortunately, `net6.0` and `net7.0` have reached their [End-Of-Life phases](https://devblogs.microsoft.com/dotnet/dotnet-6-end-of-support/). -The CLI 4.0 release officially drops Beamable support for these EOL dotnet -versions. As such, when you update your projects, you must update your -`.csproj` files to use `net8.0`. +The CLI 4.0 release officially drops Beamable support for these EOL .NET versions; when you update your projects, you must update your `.csproj` files to use `net8.0`. -In all your `.csproj` files, find the line with the `` -declaration, +In all your `.csproj` files, find the line with the `` +declaration, ```xml net6.0 @@ -180,33 +178,33 @@ And update it to > 📘 Update Dotnet SDK > -> As of CLI 4.0.0, you must have dotnet8 SDK installed on your development -> machines, instead of the dotnet6 SDK. +> As of CLI 4.0.0, you must have dotnet8 SDK installed on your development +> machines, instead of the dotnet6 SDK. -#### `MongoDb.Driver` package vulnerability +#### `MongoDb.Driver` package vulnerability Previous versions of Beamable relied on version 2.15.1 of the `MongoDb. -Driver` nuget package. If your project does not include any storage objects, -you can ignore this step. However, if you do have storage objects, then -those projects likely include this reference in the `.csproj` files, +Driver` NuGet package. If your project does not include any storage objects, +you can ignore this step. However, if you do have storage objects, then +those projects likely include this reference in the `.csproj` files, ```xml ``` If your storage object does not include direct references to the `MongoDB. -Driver`, you can simply delete this line, and the correct version will be -included automatically by referencing the `Beamable.Microservice.Runtime` -package. You can also change the version number to exactly `2.19.2`. +Driver`, you can simply delete this line, and the correct version will be +included automatically by referencing the `Beamable.Microservice.Runtime` +package. You can also change the version number to exactly `2.19.2`. #### Modify the `.dockerignore` file if you have one -In your service projects, if you have a `dockerignore` file, add the -following line to the end of the file. +In your service projects, if you have a `dockerignore` file, add the +following line to the end of the file. ``` !**/beamApp ``` ### From 2.0.2 to 3.0.1 -The upgrade from 2.0.x to 3.0.1 brings a few critical updates to the `csproj` file, how the Beam CLI tool is managed, and the version of `dotnet`. +The upgrade from 2.0.x to 3.0.1 brings a few critical updates to the `csproj` file, how the Beam CLI tool is managed, and the version of `dotnet`. **To start this process, let's open a terminal and navigate to the directory containing your `.beamable` folder. All commands are written as though invoked from this directory.** @@ -223,10 +221,10 @@ cd SomeDrive/ProjectRoot #### CLI File Structure Starting with CLI 3.0.1, you should start by updating the CLI's file structure. The steps required are defined below: -1. Install [dotnet 8 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/8.0) in your machine (it is the new recommended version). The old `net6.0` framework's end-of-life arrived on November 12, 2024. +1. Install [dotnet 8 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/8.0) in your machine (it is the new recommended version). The old `net6.0` framework's end-of-life arrived on November 12, 2024. 2. Delete the `.beamable/local-services-manifest.json` file. (It is no longer necessary) -Previous to 3.0.0, the CLI was always installed globally and all Beamable CLI projects on your computer had to share the same CLI version. You could un-install & re-install specific versions when switching projects, but that is a bad workflow --- so... we changed it. +Previous to 3.0.0, the CLI was always installed globally and all Beamable CLI projects on your computer had to share the same CLI version. You could un-install & re-install specific versions when switching projects, but that is a bad workflow — so... we changed it. In 3.0.0, the CLI should be installed as a _local dotnet tool_. @@ -234,7 +232,7 @@ The steps to change your project from using the global CLI tool to a *local dotn Start by verifying you are in the correct location by running the following command. ```sh -cat .beamable/connection-configuration.json +cat .beamable/connection-configuration.json { "host": "https://api.beamable.com", "cid": "857238240682", @@ -244,39 +242,39 @@ cat .beamable/connection-configuration.json Next, run `dotnet tool install --create-manifest-if-needed beamable.tools --version 3.0.1`. This should create a file in a top level `.config/dotnet-tools.json` with the following contents. ```json -{ - "version": 1, - "isRoot": true, - "tools": { - "beamable.tools": { - "version": "3.0.1", - "commands": [ - "beam" - ], - "rollForward": false - } +{ + "version": 1, + "isRoot": true, + "tools": { + "beamable.tools": { + "version": "3.0.1", + "commands": [ + "beam" + ], + "rollForward": false + } }} ``` -Finally, to verify that the tool is installed locally, run the following, +Finally, to verify that the tool is installed locally, run the following, ```sh dotnet beam version - { - "version": "3.0.1", - "location": "/usr/local/share/dotnet/dotnet", - "type": "LocalTool", + { + "version": "3.0.1", + "location": "/usr/local/share/dotnet/dotnet", + "type": "LocalTool", "templates": "3.0.1" - } + } ``` -From here on out, if you want to use the project specific CLI run `dotnet beam` instead of `beam`. +From here on out, if you want to use the project specific CLI run `dotnet beam` instead of `beam`. However, if you run `beam` in the context of a local project _and_ the global version of your CLI is different than the local project version, the command will be automatically forwarded to the local version. This does add some latency so prefer `dotnet beam` whenever you can. You will see a warning message similar to this when invoking `beam` directly: ``` -You tried using a Beamable CLI version=[3.0.1] which is different than the one configured in this project=[3.0.0-PREVIEW.RC2]. We are forwarding the command (beam +You tried using a Beamable CLI version=[3.0.1] which is different than the one configured in this project=[3.0.0-PREVIEW.RC2]. We are forwarding the command (beam --pretty version) to the version the project is using via dotnet=[dotnet]. Instead of relying on this forwarding, please 'dotnet beam' from inside the project directory. ``` @@ -293,46 +291,46 @@ In every `csproj` file for **Microservices**, **MicroStorages**, and **Common Li First, add a `PropertyGroup` with a `Label` called `Beamable Version` that looks like this: ```xml - - - - $([MSBuild]::GetDirectoryNameOfFileAbove("$(MSBuildProjectDirectory)/..", ".config/dotnet-tools.json")) - $([System.IO.File]::ReadAllText("$(DotNetConfigPath)/.config/dotnet-tools.json")) - - $([System.Text.RegularExpressions.Regex]::Match("$(DotNetConfig)", "beamable.*?\"([0-9]+\.[0-9]+\.[0-9]+.*?)\",", RegexOptions.Singleline | RegexOptions.IgnorePatternWhitespace).Groups[1].Value) - + + + + $([MSBuild]::GetDirectoryNameOfFileAbove("$(MSBuildProjectDirectory)/..", ".config/dotnet-tools.json")) + $([System.IO.File]::ReadAllText("$(DotNetConfigPath)/.config/dotnet-tools.json")) + + $([System.Text.RegularExpressions.Regex]::Match("$(DotNetConfig)", "beamable.*?\"([0-9]+\.[0-9]+\.[0-9]+.*?)\",", RegexOptions.Singleline | RegexOptions.IgnorePatternWhitespace).Groups[1].Value) + ``` -If the project is targeting `net6.0` or `net7.0`, then, we recommend you +If the project is targeting `net6.0` or `net7.0`, then, we recommend you upgrade the `TargetFramework` to `.net8.0`. ```xml - - - net8.0 + + + net8.0 ``` > 📘 Don't update `netstandard2.1` to `net8.0` > > Be careful not to update common projects from `netstandard2.1` to `net8.0`. -> The `netstandard2.1` target produces `.dll` files that can be copied -> directly into a wide variety of engines, such as Unity. However, `net8.0` -> binaries are not compatible with Unity. +> The `netstandard2.1` target produces `.dll` files that can be copied +> directly into a wide variety of engines, such as Unity. However, `net8.0` +> binaries are not compatible with Unity. ##### Microservices For every Microservice project replace all `PackageReference` elements that reference a `Beamable.` with the following two references: ```xml - - + + ``` Then, also add the following to the `Beamable Settings` `Property Group`: ```xml - - - service + + + service ``` ##### MicroStorages @@ -343,9 +341,9 @@ For every MicroStorage project, replace all `PackageReference` elements that ref Then, add the following to the `Beamable Settings` `Property Group`. Please replace `MyStorage` with your `csproj`'s file name. ```xml -storage - -beamable_storage_MyStorage_data +storage + +beamable_storage_MyStorage_data beamable_storage_MyStorage_files ``` @@ -355,14 +353,14 @@ For every Common Library project, replace all `PackageReference` elements that r ``` -#### Microservice Code Changes - `partial` and `FederationId` +#### Microservice Code Changes - `partial` and `FederationId` -With the introduction of the `Beamable.Microservice.SourceGen` library, all Microservice classes must be marked with the `partial` keyword. This will allow the source-generator to add custom implementations to Microservices in future releases. +With the introduction of the `Beamable.Microservice.SourceGen` library, all Microservice classes must be marked with the `partial` keyword. This will allow the source-generator to add custom implementations to Microservices in future releases. If you use any Federated endpoints as part of your Microservices, there a few code-changes you'll have to make: - Replace all `IThirdPartyCloudIdentity` with `IFederationId`. -- Add a `FederationId` attribute to the class `IFederationId` --- the `UniqueName` is the property. +- Add a `FederationId` attribute to the class `IFederationId` — the `UniqueName` is the property. - If you were ever accessing the `UniqueName` property as part of your code, you'll need to replace those calls with `GetUniqueName()`. Once these are in, try to compile your services. The newly referenced Roslyn Static Analyzer should tell you if you made any mistakes. @@ -384,44 +382,44 @@ This is very simple: simply replace the contents of each Dockerfile with the fol Make sure that the version in this line `ARG BEAM_DOTNET_VERSION="8.0-alpine"` matches the `.net` version in the `.csproj` file. ```Dockerfile -ARG BEAM_DOTNET_VERSION="8.0-alpine" -FROM mcr.microsoft.com/dotnet/runtime:${BEAM_DOTNET_VERSION} - -# These args are provided by the Beam CLI - -# Declares the relative path from the beamable workspace to the pre-build support binaries for BeamService -# Normally, this will be /services/BeamService/bin/beamApp/support -ARG BEAM_SUPPORT_SRC_PATH - -# Declares the relative path from the beamable workspace to the pre-built binaries for BeamService -# Normally, this will be /services/BeamService/bin/beamApp/app -ARG BEAM_APP_SRC_PATH - -# Declares where the built application will exist inside the Docker image. -# This value is usually /beamApp/BeamService -ARG BEAM_APP_DEST - -# Beamable may inject custom settings into this Dockerfile. Please do not remove these lines. # - -# /beamApp is the directory that will hold the application -WORKDIR /beamApp - -# expose the health port -EXPOSE 6565 -# copy general supporting files -COPY $BEAM_SUPPORT_SRC_PATH . - -# copy specific application code -COPY $BEAM_APP_SRC_PATH . - -# ensure that the application is runnable -RUN chmod +x $BEAM_APP_DEST -ENV BEAM_APP=$BEAM_APP_DEST - -# when starting the container, run dotnet with the built dll -ENTRYPOINT "dotnet" $BEAM_APP - -# Swap entrypoints if the container is exploding and you want to keep it alive indefinitely so you can go look into it. +ARG BEAM_DOTNET_VERSION="8.0-alpine" +FROM mcr.microsoft.com/dotnet/runtime:${BEAM_DOTNET_VERSION} + +# These args are provided by the Beam CLI + +# Declares the relative path from the beamable workspace to the pre-build support binaries for BeamService +# Normally, this will be /services/BeamService/bin/beamApp/support +ARG BEAM_SUPPORT_SRC_PATH + +# Declares the relative path from the beamable workspace to the pre-built binaries for BeamService +# Normally, this will be /services/BeamService/bin/beamApp/app +ARG BEAM_APP_SRC_PATH + +# Declares where the built application will exist inside the Docker image. +# This value is usually /beamApp/BeamService +ARG BEAM_APP_DEST + +# Beamable may inject custom settings into this Dockerfile. Please do not remove these lines. # + +# /beamApp is the directory that will hold the application +WORKDIR /beamApp + +# expose the health port +EXPOSE 6565 +# copy general supporting files +COPY $BEAM_SUPPORT_SRC_PATH . + +# copy specific application code +COPY $BEAM_APP_SRC_PATH . + +# ensure that the application is runnable +RUN chmod +x $BEAM_APP_DEST +ENV BEAM_APP=$BEAM_APP_DEST + +# when starting the container, run dotnet with the built dll +ENTRYPOINT "dotnet" $BEAM_APP + +# Swap entrypoints if the container is exploding and you want to keep it alive indefinitely so you can go look into it. #ENTRYPOINT ["tail", "-f", "/dev/null"] ``` @@ -430,7 +428,7 @@ ENTRYPOINT "dotnet" $BEAM_APP #### CLI File Structure -The `.beamable` folder structure changes between the major versions 1, and 2. +The `.beamable` folder structure changes between the major versions 1, and 2. After you upgrade your global CLI to 2.0.1, run the following command in your project. This command should automatically perform some of the required upgrade steps. ```sh @@ -439,12 +437,12 @@ beam config If you forgot to the run the command, or would like to verify that the upgrade happened correctly, follow the bullets below. -- The `.beamable/beamoLocalManifest.json` file should no longer exist. +- The `.beamable/beamoLocalManifest.json` file should no longer exist. - The `.beamable/beamoLocalRuntime.json` file should no longer exist. - The `.beamable/config-defaults.json` file should no longer exist. -- The `.beamable/user-token.json` file should no longer exist. +- The `.beamable/user-token.json` file should no longer exist. -Instead, you should expect to see (at least), +Instead, you should expect to see (at least), - `.beamable/connection-configuration.json` _(this replaces the old `config-defaults` file. )_ - `.beamable/temp/connection-auth.json` _(this replaces the old `user-token` file)_ @@ -452,10 +450,10 @@ Instead, you should expect to see (at least), ##### SDK Version -Unfortunately, the upgrade flow between major version 1 and 2 does not automatically upgrade the nuget dependency on Beamable. All of the `.csproj` files you may have will need to be manually upgraded to Beamable 2.0.1. Remember, every service, common library, and storage have their own `.csproj` files. +Unfortunately, the upgrade flow between major version 1 and 2 does not automatically upgrade the NuGet dependency on Beamable. All of the `.csproj` files you may have will need to be manually upgraded to Beamable 2.0.1. Remember, every service, common library, and storage have their own `.csproj` files. -Open each `csproj` file, and find the `` for Beamable. -For a service, it will likely look like this, +Open each `csproj` file, and find the `` for Beamable. +For a service, it will likely look like this, ```xml ``` @@ -465,12 +463,12 @@ For a storage, it may (unfortunately) look like this ``` -And for a common library, +And for a common library, ```xml ``` -In all these cases, please update the `Version` to `2.0.1`. +In all these cases, please update the `Version` to `2.0.1`. ##### Structure @@ -478,167 +476,167 @@ In addition, different project types have the following upgrade requirements... ###### Services -For services, the `csproj` file has been simplified between major versions 1 and 2. You can remove all of the tasks and extraneous nuget references. +For services, the `csproj` file has been simplified between major versions 1 and 2. You can remove all the tasks and extraneous NuGet references. This snippet can (and should) be removed from a 1.19.22 service's `csproj` file. ```xml - - - - - - - - - - - - - + + + + + + + + + + + + + ``` -Also, all of these targets can be removed, +Also, all of these targets can be removed, ```xml - - - - - - - - - - - - - - - - - @(BeamablePackage->'%(Version)') - - - - - - - - - @(BeamablePackage->'%(Version)') - - - + + + + + + + + + + + + + + + + + @(BeamablePackage->'%(Version)') + + + + + + + + + @(BeamablePackage->'%(Version)') + + + ``` -The following property group section can be dramatically simplified. The only required properties from the following snippet are, -1. `GenerateClientCode`, and +The following property group section can be dramatically simplified. The only required properties from the following snippet are, +1. `GenerateClientCode`, and 2. `TargetFramework` ```xml - - - - beam - - - false - - - true - - - - $(DefineConstants);BEAMABLE_GENERATE_ENV - - - - - Exe - - - net6.0 - - disable - disable - Linux - - - 1591 - - - true + + + + beam + + + false + + + true + + + + $(DefineConstants);BEAMABLE_GENERATE_ENV + + + + + Exe + + + net6.0 + + disable + disable + Linux + + + 1591 + + + true ``` -However, there is one *new* property that is **REQUIRED**. You must add the following property, +However, there is one *new* property that is **REQUIRED**. You must add the following property, ```xml service ``` After all the edits, you should have a `csproj` file that looks similar to the following. This is the `csproj` file that is generated for a new service using CLI 2.0.1. ```xml - - - - service - - - true - - - - net6.0 - - - - + + + + service + + + true + + + + net6.0 + + + + ``` ###### Common Libraries -Similar to services, the `csproj` file for common libraries has been simplified between major versions 1 and 2. +Similar to services, the `csproj` file for common libraries has been simplified between major versions 1 and 2. -You should remove this target, +You should remove this target, ```xml - - - - + + + + ``` -And from the following properties the only two that you need are, +And from the following properties the only two that you need are, 1. `CopyToLinkedProjects`, and 2. `TargetFramework` ```xml - - - - netstandard2.1 - true - - - - - - beam - - - true - - - - - true - true - true + + + + netstandard2.1 + true + + + + + + beam + + + true + + + + + true + true + true ``` @@ -660,7 +658,7 @@ When you are done with these edits, your `csproj` file should appear similar to - + ``` @@ -668,75 +666,75 @@ When you are done with these edits, your `csproj` file should appear similar to #### Dockerfiles -Any service you created in 1.19.22 will have a `Dockerfile`. These files need some manual edits to make them compatible with 2.0.1. +Any service you created in 1.19.22 will have a `Dockerfile`. These files need some manual edits to make them compatible with 2.0.1. Select all the lines _between_ the first `FROM` command, and the `RUN dotnet publish` command, and _replace_ them with the following. -```Dockerfile -# this line signals the start of environment variables copies into the built container. Do not remove it. This will be overwritten every time a variable changes in the execution of the CLI. - -# this line signals the end of environment variables copies into the built container. Do not remove it. - -# this line signals the start of Beamable Project Src copies into the built container. Do not remove it. The content between here and the closing tag will change anytime the Beam CLI modifies dependencies. - -# this line signals the end of Beamable Project Src copies. Do not remove it. - -# build the dotnet program +```Dockerfile +# this line signals the start of environment variables copies into the built container. Do not remove it. This will be overwritten every time a variable changes in the execution of the CLI. + +# this line signals the end of environment variables copies into the built container. Do not remove it. + +# this line signals the start of Beamable Project Src copies into the built container. Do not remove it. The content between here and the closing tag will change anytime the Beam CLI modifies dependencies. + +# this line signals the end of Beamable Project Src copies. Do not remove it. + +# build the dotnet program WORKDIR / ``` -Next, select the lines starting with (and _including_) `RUN dotnet publish` until the line (but not including) `ENTRYPOINT` , and _replace_ them with the following, +Next, select the lines starting with (and _including_) `RUN dotnet publish` until the line (but not including) `ENTRYPOINT` , and _replace_ them with the following, ```Dockerfile -RUN dotnet publish ${BEAM_CSPROJ_PATH} -c release -o /beamApp - -# use the dotnet runtime as the final stage -FROM mcr.microsoft.com/dotnet/runtime:6.0-alpine -WORKDIR /beamApp - -# expose the health port -EXPOSE 6565 -# copy the built program +RUN dotnet publish ${BEAM_CSPROJ_PATH} -c release -o /beamApp + +# use the dotnet runtime as the final stage +FROM mcr.microsoft.com/dotnet/runtime:6.0-alpine +WORKDIR /beamApp + +# expose the health port +EXPOSE 6565 +# copy the built program COPY --from=build-env /beamApp . ``` Finally, on the last line (the `ENTRYPOINT`), replace the `/subapp` with `/beamApp` -Here is a Dockerfile that was adapted from 2.0.1. There are two important things to note, +Here is a Dockerfile that was adapted from 2.0.1. There are two important things to note, 1. this file is for a service called `Example3`, which justifies the `ENTRYPOINT`, and -2. when you run `beam services run`, the CLI will _inject_ content into the file between on the `BEAM-CLI-` tags. After the command runs, you should see `ENV`, `RUN`, and `COPY` statements between the beamable tags. This is how the `${BEAM_CSPROJ_PATH}` reference will be resolved. +2. when you run `beam services run`, the CLI will _inject_ content into the file between on the `BEAM-CLI-` tags. After the command runs, you should see `ENV`, `RUN`, and `COPY` statements between the beamable tags. This is how the `${BEAM_CSPROJ_PATH}` reference will be resolved. ```Dockerfile -# use the dotnet sdk as a build stage -FROM mcr.microsoft.com/dotnet/sdk:6.0-alpine as build-env - -# this line signals the start of environment variables copies into the built container. Do not remove it. This will be overwritten every time a variable changes in the execution of the CLI. - -# this line signals the end of environment variables copies into the built container. Do not remove it. - -# this line signals the start of Beamable Project Src copies into the built container. Do not remove it. The content between here and the closing tag will change anytime the Beam CLI modifies dependencies. - -# this line signals the end of Beamable Project Src copies. Do not remove it. - -# build the dotnet program -WORKDIR / - -RUN dotnet publish ${BEAM_CSPROJ_PATH} -c release -o /beamApp - -# use the dotnet runtime as the final stage -FROM mcr.microsoft.com/dotnet/runtime:6.0-alpine -WORKDIR /beamApp - -# expose the health port -EXPOSE 6565 -# copy the built program -COPY --from=build-env /beamApp . - -# when starting the container, run dotnet with the built dll -ENTRYPOINT ["dotnet", "/beamApp/Example3.dll"] +# use the dotnet sdk as a build stage +FROM mcr.microsoft.com/dotnet/sdk:6.0-alpine as build-env + +# this line signals the start of environment variables copies into the built container. Do not remove it. This will be overwritten every time a variable changes in the execution of the CLI. + +# this line signals the end of environment variables copies into the built container. Do not remove it. + +# this line signals the start of Beamable Project Src copies into the built container. Do not remove it. The content between here and the closing tag will change anytime the Beam CLI modifies dependencies. + +# this line signals the end of Beamable Project Src copies. Do not remove it. + +# build the dotnet program +WORKDIR / + +RUN dotnet publish ${BEAM_CSPROJ_PATH} -c release -o /beamApp + +# use the dotnet runtime as the final stage +FROM mcr.microsoft.com/dotnet/runtime:6.0-alpine +WORKDIR /beamApp + +# expose the health port +EXPOSE 6565 +# copy the built program +COPY --from=build-env /beamApp . + +# when starting the container, run dotnet with the built dll +ENTRYPOINT ["dotnet", "/beamApp/Example3.dll"] ``` #### Microservice .config folders -Finally, the `.config` folder under each Microservice folder should be deleted. This file is cruft, and is no longer needed. +Finally, the `.config` folder under each Microservice folder should be deleted. This file is cruft, and is no longer needed. Also, remember that if your Microservice is referencing a Storage object, you must have Docker running; otherwise the Microservice will not start correctly. diff --git a/docs/portal/campaigns.md b/docs/portal/campaigns.md index 06c62593c..7a7ba73f8 100644 --- a/docs/portal/campaigns.md +++ b/docs/portal/campaigns.md @@ -16,7 +16,7 @@ Beamable Portal, under **Communicate > Campaigns > + Create Campaign.** After that, you can create campaigns setting some information through a few steps: -- Meta information: This is going to be all the main information about your Campaign. You're going to select which Type the campaign will be, as well as it's name and date. +- Meta information: This is going to be all the main information about your Campaign. You're going to select which Type the campaign will be, as well as its name and date. ![Campaign Meta Information](../media/imgs/campaigns-meta-information.png)