Documentation

Support

Cloud Code

Use modules

Use scripts

Use Triggers

Open Unity Dashboard

Cloud Code

Data transfer objects (DTOs)

Define data transfer objects to transfer data between client and server.
Read time 3 minutesLast updated 18 hours ago
You can define data transfer objects in your modules. You can use DTOs to transfer data between the client and the server. For example, you can use DTOs to serialize your module data to JSON, and deserialize it into the same structure on the client side.

Prerequisites

Before you get started with DTOs, create a Cloud Code module.

Manage DTOs

You can define DTOs to capture data types for your module endpoint functions.

Create and configure your DTO project

To get started, create a C# project to store your DTOs in, and add a reference to it from your main project. Refer to the Microsoft documentation on how to Manage references in a project. For more information on modules, refer to module structure. Next, you have to configure your DTO C# project to use a supported runtime .NET version in Unity Editor, which is 
netstandard
. Open the 
<project_name>.csproj
file, and change the 
TargetFramework
. If you use Unity 2021.2.0, this is 
netstandard.2.1
. For more information, refer to the Unity manual supported .NET versions. You also need to disable implicit usings. Refer to the example C# project configuration below: 
<Project Sdk="Microsoft.NET.Sdk">    <PropertyGroup>        <TargetFramework>netstandard2.1</TargetFramework>        <ImplicitUsings>disable</ImplicitUsings>        <RootNamespace>DTOSample</RootNamespace>    </PropertyGroup></Project>

Add the DTOs to your module

To add DTOs to your module, you need to define a new class in your project to store your DTOs. This can be similar to the following example: 
namespace DTOSample{    public class DiceRollDto    {        public DiceRollDto(int roll, int sides)        {            Roll = roll;            Sides = sides;        }        public int Roll { get; set; }        public int Sides { get; set; }    }}

Use DTOs in your module logic

In your main project with module functions, define your game logic, and use the defined DTO as the function return type. The following is an example of a simple module endpoint: 
using DTOSample;using Unity.Services.CloudCode.Core;namespace Sample;public class HelloWorld{    [CloudCodeFunction("RollDice")]    public async Task<DiceRollDTO> RollDice(int diceSides)    {        var random = new Random();        var roll = random.Next(1, diceSides);        return new DiceRollDTO(roll, diceSides);    }}

Extract the DLLs

To use the DTOs in your Unity project to match the response type, you need to extract the DLLs from the module C# project. You should deploy your module for this step to be able to call the module function later. For manual packaging, refer to package code for more information on how to generate the assemblies. If you generate the assemblies when you deploy your module, by default, you can find the DLLs in the 
bin/Debug/Release/net6.0/linux-x64/publish
folder of your module project. Your assemblies be similar to the following example: 
├─ Main.csproj└─ bin    └─ Debug        └─ Release            └─ net6.0                └─ linux-x64                    └─ publish                        └─ Main.dll                        └─ Main.pdb                        └─ DTOs.dll                        └─ DTOs.pdb                        ...
Copy the 
DTOs.dll
file.

Import the DLLs to Unity project

To use an external DLL in your game, place the DLL inside your Unity project in the 
Assets
directory. The next time the Unity Editor synchronizes the project, the Editor adds the necessary references to the DLLs. For more information, refer to Managed plug-ins in the Unity manual.

Reuse the DTOs in a Unity MonoBehaviour script

You can call out to Cloud Code SDK and use the same DTOs to deserialize the response: 
using DTOSample;using UnityEngine;using Unity.Services.Authentication;using Unity.Services.CloudCode;using Unity.Services.Core;public class Test : MonoBehaviour{    // Call this method to roll the dice (use a button)    public async void Awake()    {        await UnityServices.InitializeAsync();        // Sign in anonymously to the Authentication service        if (!AuthenticationService.Instance.IsSignedIn) await AuthenticationService.Instance.SignInAnonymouslyAsync();        // Call out to the Roll Dice script in Cloud Code        var response = await CloudCodeService.Instance.CallModuleEndpointAsync<DiceRollDto>("Main", "RollDice", new Dictionary<string, object>()        {            {"diceSides", 6}        });        // Log the response of the script in console        Debug.Log($"You rolled {response.Roll} / {response.Sides}");    }}
Use the following example of a successful response for reference: 
"You rolled 5 / 6"
For more information, refer to running modules from Unity Runtime.