跳到主要内容
版本:v3

数据存储、即时通讯 .NET SDK 配置指南

信息

.NET SDK 基于 .NET Standard 2.0 接口标准实现,支持框架如下:

  • Unity 2018.1+
  • .NET Core 2.0+
  • .NET Framework 4.6.1+
  • Mono 5.4+

更多支持框架可参考 .NET Standard 文档。

获取 SDK

通过 GitHub 仓库 Releases 下载最新版本 SDK。

各模块及依赖关系如下:

名称模块描述
LeanCloud-SDK-Storage存储服务。
LeanCloud-SDK-Realtime即时通信、LiveQuery 服务,依赖于存储服务。
LeanCloud-SDK-Engine云引擎服务,依赖于存储,适用于云引擎服务端环境。

如只需使用某种服务,可下载最小依赖包,减小程序体积。

Unity 项目安装

  • 直接导入:请下载 LeanCloud-SDK-XXX-Unity.zip,解压后为 Plugins 文件夹,拖拽至 Unity 即可。

  • UPM:请在项目的 Packages/manifest.json 中添加依赖项

    "dependencies": {
    "com.leancloud.storage": "https://github.com/leancloud/csharp-sdk-upm.git#storage-2.3.0",
    "com.leancloud.realtime": "https://github.com/leancloud/csharp-sdk-upm.git#realtime-2.3.0"
    }

注意:仅支持 Unity 2018+,即 Unity Api Compatibility Level 支持 .NET Standard 2.0 的版本。

非 Unity 项目安装

.NET Core 或其他支持 .NET Standard 2.0 的项目请下载 LeanCloud-SDK-XXX-Standard.zip,解压后设置依赖即可(XXX 指云服务,包括存储 Storage,即时通讯(含 LiveQuery)Realtime,云引擎 Engine)。

初始化

信息

TapSDK 初始化时,会自动执行这一节的初始化方法。

如果已经参考 快速开始 文档完成了 TapSDK 初始化,则不需要参考这里的初始化。

导入模块:

// 导入基础模块
using LeanCloud;
// 导入存储模块
using LeanCloud.Storage;
// 如有需要,导入即时通讯模块
using LeanCloud.Realtime;
// 如有需要,导入 LiveQuery 模块
using LeanCloud.LiveQuery;

在使用服务前,先调用如下代码初始化 SDK:

LCApplication.Initialize("your-client-id", "your-client-token", "https://your_server_url");

应用凭证

开发者中心 > 你的游戏 > 游戏服务 > 应用配置 可以查看应用的基本信息:

  • Client ID:又称 App ID,在 SDK 初始化时用到。
  • Client Token:又称 App Key,客户端对服务端的调用凭证,在 SDK 初始化时用到。
  • 域名配置 > 云服务 API:又称 API 域名或 Server URL,在客户端 SDK 初始化时用到。域名配置参考下一节域名
  • Server Secret:又称 Master Key,用于在自有服务器、云引擎等受信任环境调用管理接口,具备跳过一切权限验证的超级权限。所以一定注意保密,千万不要在客户端代码中使用该凭证

域名

使用 TDS 提供的云服务需要绑定 API 自定义域名,以便和其他厂商的应用隔离入口,避免其他应用受到 DDoS 攻击时相互牵连。

初始化客户端 SDK 时 server_url 处填入的就是 API 域名。

绑定 API 域名

绑定 API 域名的前提是,你拥有一个已经完成备案的域名

点击查看 API 域名绑定步骤

假设你的域名为 example.com,API 域名绑定步骤和状态如下:

domain guide

  • 进入 开发者中心 > 你的游戏 > 游戏服务 > 应用配置 > 域名配置 > API ,点击 「绑定新域名」 按钮。API 域名不支持直接绑定裸域名,需要在主域名的前面添加自定义名称,也就是绑定一个子域名,比如这里你可以绑定 api.example.com
  • 控制台显示 「正在检查备案信息」,请等待一会儿。
  • 如果域名没有完成备案,将会显示 「绑定失败」
  • 域名备案检查通过,域名下方显示 「请配置 DNS」
  • 此时需要到你的域名服务商控制台,进入域名解析设置页面,添加一条记录,记录类型为 A(A 记录可以将域名指向一个 IP 地址),请将前面填到开发者后台的自定义域名和 「推荐 DNS 配置」 下方 A 记录值复制到对应位置。
  • DNS 解析记录和证书申请(如果选择了自动管理 SSL 证书)都需要一定时间,请耐心等待。记录生效后,控制台便会显示 「已绑定」

绑定成功后,初始化 SDK 时请传入绑定的自定义域名 https://api.example.com。这里用的是示例,请换成你自己绑定的 API 域名,注意不要遗漏前面的 https://

配置域名需要一定的时间,TDS 为开发者提供了 共享域名 在游戏测试时使用,但共享域名没有可用性保证,容易受到 DDoS 攻击影响。游戏上线前,一定要确认使用的 API 访问域名是开发者自己绑定的域名,请勿将共享域名用于生产环境。

绑定文件域名

如果使用了数据存储中的文件服务,包括即时通讯的多媒体消息(图像、音频、视频等),需要绑定文件访问域名

可前往 开发者中心 > 你的游戏 > 游戏服务 > 应用配置 > 域名配置 > 文件 绑定文件域名,步骤和 API 自定义域名基本相同。但有两点不一样:

  1. API 域名解析使用 A 记录,文件域名解析使用 CNAME 记录。文件域名同样不支持绑定裸域名,需要绑定子域名。例如你的主域名是 example.com,可以绑定文件域名为 files.example.com
  2. 绑定成功后,还需在 开发与构建 > 数据存储 > 文件 > 设置 > 文件访问地址 点击「修改」按钮进行切换。
信息

每个子域名只能绑定到一个游戏,且 API 域名和文件域名不可使用同样的子域名。如果你已经在 TDS 控制台绑定了某个子域名,重复绑定时控制台会显示「该域名已经被其他应用所绑定」,此时可以更换同一主域名下不同的子域名,来完成后续绑定步骤。

开启调试日志

在应用开发阶段,你可以选择开启 SDK 的调试日志(debug log)来方便追踪问题。调试日志开启后,SDK 会把网络请求、错误消息等信息输出到 IDE 的日志窗口,或是浏览器 Console 或是云引擎日志(如果在云引擎下运行 SDK)。

LCLogger.LogDelegate = (LCLogLevel level, string info) => {
switch (level) {
case LCLogLevel.Debug:
Debug.Log($"[DEBUG] {DateTime.Now} {info}\n");
break;
case LCLogLevel.Warn:
Debug.Log($"[WARNING] {DateTime.Now} {info}\n");
break;
case LCLogLevel.Error:
Debug.Log($"[ERROR] {DateTime.Now} {info}\n");
break;
default:
Debug.Log(info);
break;
}
}
警告

在应用发布之前,请关闭调试日志,以免暴露敏感数据。

验证

首先,确认本地网络环境是可以访问云端服务器的,可以执行以下命令:

curl "https://{{host}}/1.1/date"

{{host}} 为绑定的 API 自定义域名。

如果当前网络正常会返回当前时间:

{ "__type": "Date", "iso": "2020-10-12T06:46:56.000Z" }

然后在项目中编写如下测试代码:

LCObject testObject = new LCObject("TestObject");
testObject["words"] = "Hello world!";
await testObject.Save();

保存后运行程序。

然后打开 开发者中心 > 你的游戏 > 游戏服务 > 云服务 > 数据存储 > 结构化数据 > TestObject,如果看到数据表中出现一行「words」列的值为「Hello world!」的数据,说明 SDK 已经正确地执行了上述代码,配置完毕。

如果控制台没有发现对应的数据,请参考 问题排查

问题排查

SDK 安装指南基于当前最新版本的 SDK 编写,所以排查问题前,请先检查下安装的 SDK 是不是最新版本。

401 Unauthorized

如果 SDK 抛出 401 异常或者查看本地网络访问日志存在:

{
"code": 401,
"error": "Unauthorized."
}

则可认定为 App ID 或者 App Key 输入有误,或者是不匹配,很多开发者同时注册了多个应用,导致拷贝粘贴的时候,用 A 应用的 App ID 匹配 B 应用的 App Key,这样就会出现服务端鉴权失败的错误。

客户端无法访问网络

客户端尤其是手机端,应用在访问网络的时候需要申请一定的权限。