跳到主要内容
版本：v2

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

我们于 2020 年 12 月推出了基于 .NET Standard 2.0 接口标准实现的新版 .NET SDK。旧版 .NET SDK（类名以 AV 开头的） 已不再更新，欢迎旧版 SDK 的用户尽快切换到新版 .NET SDK，具体迁移方法详见 .NET SDK 迁移指南。

新版 .NET SDK 基于 .NET Standard 2.0 接口标准实现，支持框架如下：

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

更多支持框架可参考：https://docs.microsoft.com/en-us/dotnet/standard/net-standard

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

安装​

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-0.7.5",
    "com.leancloud.realtime": "https://github.com/leancloud/csharp-sdk-upm.git#realtime-0.7.5"
    }

注意：仅支持 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）

模块及依赖关系​

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

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

快速开始​

绑定域名​

你需要绑定 API 自定义域名，以便和其他厂商的应用隔离入口，避免其他应用受到 DDoS 攻击时相互牵连。 如果使用了文件服务，也需要绑定文件自定义域名。

进入 开发者中心 > 你的游戏 > 游戏服务 > 技术服务 > 数据存储 > 服务设置 > 自定义域名 点击「绑定新域名」按钮，根据控制台提示完成绑定步骤。 注意，DNS 解析记录和证书申请（如果选择了自动管理 SSL 证书）都需要一定时间，请耐心等待。

绑定成功后，初始化 SDK 时，请传入绑定的自定义域名（https://please-replace-with-your-customized.domain.com）。

如果你使用了文件服务（包括即时通讯的多媒体消息（图像、音频、视频等）），同样需要前往 开发者中心 > 你的游戏 > 游戏服务 > 技术服务 > 数据存储 > 文件 > 设置 > 文件访问域名 绑定域名，步骤和 API 自定义域名基本相同，但有两点不一样：

  1. API 域名解析使用 A 记录，文件域名解析使用 CNAME 记录，也因此文件域名不支持绑定裸域名（例如 example.com），需要绑定子域名（例如 files.example.com）。
  2. 绑定成功后，还需在 文件 > 设置 > 文件访问地址 点击「修改」按钮进行切换。

应用凭证​

在 开发者中心 > 你的游戏 > 游戏服务 > 基本信息 可以查看应用凭证：

  • Client ID，又称 App ID，在 SDK 初始化时用到。联系技术支持时，提供 Client ID 可以方便我们更快定位到你的应用。
  • Client Token，又称 App Key，在 SDK 初始化时用到。
  • Server Secret，又称 Master Key，用于在自有服务器、云引擎等受信任环境调用管理接口，具备跳过一切权限验证的超级权限。所以一定注意保密，千万不要在客户端代码中使用该凭证。

导入模块​

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

初始化 SDK​

在使用服务前，先调用如下代码：

LCApplication.Initialize("your-client-id", "your-client-token", "https://please-replace-with-your-customized.domain.com");

开启调试日志​

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

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

Unity 平台可重定向到 Debug.

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

验证​

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

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，这样就会出现服务端鉴权失败的错误。

客户端无法访问网络​

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