开始使用

本节介绍在项目中创建 C# 模块所需的所有步骤。

部署 Hello World#

通过创建一个简单的 Hello World C# 模块开始使用 Cloud Code。

典型工作流程#

要开始使用 Cloud Code 模块，必须按照以下步骤操作：

1. 创建 .NET 项目：Cloud Code 模块是简单的 .NET 项目，其中公开了游戏客户端可以调用的终端。
2. 导入 Cloud Code Authoring 包：安装 Cloud Code Authoring 包来创建可调用的终端。
3. 在项目中创建模块终端：定义可从游戏客户端调用的游戏逻辑。
4. 打包代码：为项目生成程序集，并将它们打包到存档中。
5. 部署项目：将存档部署到 Cloud Code 服务。
6. 调用模块终端：从游戏客户端调用模块终端。

创建 .NET 项目#

Cloud Code 模块是简单的 .NET 项目，其中公开了游戏客户端可以调用的终端。首先，请在所选的集成开发环境 (IDE) 中创建新的 .NET 项目。要详细了解 Cloud Code 模块的结构，请参阅模块结构。

以下几节将介绍如何在 JetBrains Rider 和 Microsoft Visual Studio 集成开发环境中创建项目。

JetBrains Rider#

按照以下步骤在 JetBrains Rider 中创建新项目。

1. 选择 File（文件）> New（新建）。
2. 选择类库，即 .NET Core 或 .NET Framework。
3. 为模块命名。
4. 选择 Create（创建）。

Microsoft Visual Studio#

按照以下步骤在 Microsoft Visual Studio 中创建新项目。

1. 选择 File（文件）> New Solution（新建解决方案）。
2. 选择一个 .Net 类库。
3. 选择 Next（下一步）。
4. 为模块命名。
5. 选择 Create（创建）。

导入 Cloud Code Authoring 包#

由于 Cloud Code 模块是 .NET 项目，因此它们使用 NuGet Package Manager 来管理依赖项。Cloud Code 模块需要 Cloud Code Authoring 包才能创建可调用的终端。这是一个可以安装到项目中的 NuGet 包。

以下几节将演示如何在以下集成开发环境中导入包。

JetBrains Rider#

使用 JetBrains Rider 安装 Cloud Code Authoring 包。

1. 选择 Tools（工具）> NuGet > Show NuGet Packages（显示 NuGet 包）。
2. 搜索 Com.Unity.Services.CloudCode.Core。
3. 将最新版本安装到您的项目中。

Microsoft Visual Studio#

使用 Microsoft Visual Studio 安装 Cloud Code Authoring 包。

1. 右键单击项目 > Manage NuGet Packages（管理 NuGet 包）。
2. 搜索 Com.Unity.Services.CloudCode.Core。
3. 选择 Add Package（添加包）。

创建模块终端#

要在 C# 模块中创建终端，您需要创建一个可在外部调用的函数，并使用 CloudCodeFunction 属性对其进行属性设置，然后为其指定公开使用的名称。您可以选择不同的函数名称，这样可以在稍后重构代码时不破坏游戏客户端已调用的函数。

模块函数的一个简单示例如下所示：

using Unity.Services.CloudCode.Core;

namespace ExampleModule;

public class MyModule
{
    [CloudCodeFunction("SayHello")]
    public string Hello(string name)
    {
        return $"Hello, {name}!";
    }
}

此示例创建一个名为 SayHello 的模块终端。这个终端接受名为 name 的字符串参数并返回一个字符串。

打包代码#

在部署模块之前，必须将代码打包到存档中。此存档必须包含 Cloud Code 服务运行模块时所需的程序集。

您可以通过发布项目来生成这些程序集。必须为 linux-x64 目标运行时构建程序集。您可以启用 ReadyToRun 编译来提高性能。

如需更多有关如何生成程序集的信息，请参阅打包代码。

如需更多有关如何自动执行此过程的信息，请查看自动执行本地部署。

按照以下步骤配置集成开发环境以生成程序集。

JetBrains Rider#

要使用 JetBrains Rider 集成开发环境生成程序集，请按照以下步骤操作：

1. 选择 Run（运行）> Edit Configurations（编辑配置）。
2. 选择 +。
3. 选择 Publish to folder（发布到文件夹）。
4. 为配置命名。
5. 将 **Target location（目标位置）**设置为要存储构建输出的位置。
6. 选择 **Release | Any CPU（发布 | 任何 CPU）**配置。
7. 选择 linux-x64 目标运行时。
8. （可选）启用 Enable ReadyToRun compilation（启用 ReadyToRun 编译）。
9. 选择 Apply（应用）。

Microsoft Visual Studio#

要使用 Microsoft Visual Studio 集成开发环境生成程序集，请按照以下步骤操作：

1. 右键单击解决方案，然后选择 Publish（发布）。
2. 按照屏幕上的步骤将文件存储在本地。
3. 选择 Show All Settings（显示所有设置）。
4. 将目标运行时设置为 linux-x64。
5. 选择 Save（保存）。
6. 选择 Publish（发布）。

压缩程序集

默认情况下，发布过程会按照根项目目录下的 bin/Release/net6.0/linux-x64/publish 路径生成一个文件夹。您必须将此文件夹的内容压缩到存档中。如果您希望使用 UGS CLI 来部署模块，我们建议您将存档文件扩展名更改为 .ccm。

在 Unix 系统上，可以运行以下命令：

zip ExampleModule.ccm *

在 Windows 系统上，可以运行以下命令：

zip -r ExampleModule.ccm path/to/your/project/bin/Release/net6.0/linux-x64/publish/*

部署模块项目#

要使游戏客户端能够访问您的模块终端，您必须将存档部署到 Cloud Code 服务。

请参阅编写模块以了解有关模块部署的更多信息。

要使用 UGS CLI 进行部署，必须将存档文件扩展名更改为 .ccm。

配置 UGS CLI#

按照以下步骤操作以开始使用 UGS CLI：

1. 安装 UGS CLI。

2. 按如下方式配置 Project ID 和环境：
   ugs config set project-id <your-project-id>
ugs config set environment-name <your-environment-name>

3. 为服务帐户配置 Cloud Code 和环境管理所需的角色。请参阅接受身份验证。

部署该模块

运行以下命令：

ugs deploy <path-to-ccm-file>

成功的部署将返回以下输出：

Deployed:
    ExampleModule.ccm

从游戏调用模块函数#

部署模块后，可以从游戏客户端调用模块函数。

先决条件

要在 Unity 编辑器中使用 Cloud Code，必须先安装 Cloud Code SDK，并将 Unity Gaming Services（Unity 游戏服务）项目关联到 Unity 编辑器。

关联项目

将 Unity Gaming Services（Unity 游戏服务）项目与 Unity 编辑器关联。您可以在 Unity Dashboard（Unity 后台）中找到您的 UGS Project ID。

1. 在 Unity 编辑器中，选择 Edit（编辑）> Project Settings（项目设置）> Services（服务）。

2. 关联您的项目。
   如果项目没有 Unity Project ID：

   1. 选择 Create a Unity Project ID（创建 Unity Project ID）> Organizations（组织），然后从下拉选单中选择一个组织。
   2. 选择 Create project ID（创建 Project ID）。

   
   如果已有 Unity Project ID：

   1. 选择 Use an existing Unity project ID（使用现有 Unity Project ID）。
   2. 从下拉选单中选择组织和项目。
   3. 选择 Link project ID（关联 Project ID）。

此时将显示您的 Unity Project ID，并且该项目现在已关联到 Unity 服务。此外，还可以使用 UnityEditor.CloudProjectSettings.projectId 在 Unity 编辑器脚本中访问您的 Project ID。

SDK 安装#

要安装适用于 Unity 编辑器的最新 Cloud Code 包，请执行以下操作：

1. 在 Unity 编辑器中，打开 Window（窗口）> Package Manager（包管理器）。
2. 在 Package Manager（包管理器）中，选择 **Unity Registry（Unity 注册表）**列表视图。
3. 搜索 com.unity.services.cloudcode 或在列表中找到 Cloud Code 包。
4. 选择该包，然后单击 Install（安装）。

SDK 设置#

开始使用 Cloud Code SDK：

1. 确保通过 Cloud Code 服务后台页面启用该服务。
2. 确保 Cloud Code SDK 和 Authentication SDK 均已安装。
3. 在 Unity 编辑器中选择 Edit（编辑）> Project Settings（项目设置）> **Services（服务）**登录到您的云项目。
4. 在 Unity 编辑器中创建新的 C# Monobehaviour 脚本。请参阅 Unity 手册中的创建和使用脚本。
5. 在脚本中，使用 await UnityServices.InitializeAsync() 初始化 Core SDK。
6. 在脚本中，初始化 Authentication SDK。

C#

await AuthenticationService.Instance.SignInAnonymouslyAsync();

调用模块函数

要从游戏客户端调用模块函数，必须对调用进行身份验证，在调用任何服务的功能之前初始化 Services Core SDK，然后调用模块函数。

如需更多有关如何使用游戏客户端来调用模块的信息，请参阅从 Unity Runtime 运行模块。

按照以下步骤调用模块函数：

1. 初始化 Services Core SDK。在调用 Cloud Code 之前，通过导入 Services Core 命名空间 (Unity.Services.Core) 在游戏代码中初始化 Unity Services，然后调用 InitializeAsync 方法。
2. 对调用进行身份验证。每次调用 Cloud Code 都必须经过身份验证，并且玩家必须拥有有效的玩家 ID 和访问令牌才能访问 Cloud Code 服务。请参阅身份验证。建议通过调用 SignInAnonymouslyAsync 方法开始进行匿名身份验证。
3. 调用模块函数。使用 Cloud Code SDK 通过 CallEndpointModuleAsync 方法调用模块函数。

集成示例

以下示例说明了如何从游戏客户端中的模块 ExampleModule 调用模块函数 SayHello。

C#

using System.Collections.Generic;
using Unity.Services.Authentication;
using Unity.Services.CloudCode;
using Unity.Services.Core;
using UnityEngine;

public class TestModule : MonoBehaviour
{
    private async void Start()
    {
        // Initialize the Unity Services Core SDK
        await UnityServices.InitializeAsync();

        // Authenticate by logging into an anonymous account
        await AuthenticationService.Instance.SignInAnonymouslyAsync();

        try
        {
            // Call the function within the module and provide the parameters we defined in there
            string result = await CloudCodeService.Instance.CallModuleEndpointAsync("ExampleModule", "SayHello", new Dictionary<string, object> {{"name", "World"}});

            Debug.Log(result);
        }
        catch (CloudCodeException exception)
        {
            Debug.LogException(exception);
        }
    }
}

后续步骤#

了解部署第一个模块后的后续步骤。