C# 和 Unity SDK
使用 dotnet add package DeviceChain.Sdk 安装 .NET 包。它面向
.NET 8 和 .NET Standard 2.1。你需要提供平台源地址;没有默认主机。
Unity 包在同一套 API 上增加了传输实现和主线程订阅处理机制。
客户端与身份验证
using System;
using DeviceChain.Sdk;
await using var client = new DeviceChainClient(new Uri("https://devicechain.example.com"));
await client.LoginAsync("me@example.com", "your-password");
await client.SelectTenantAsync("acme");
LoginAsync(email, password, cancellationToken) 返回 IdentityAuth,其中包含
IdentityToken、ExpiresAt、Superuser 和 Memberships。对于启用了
第二因素的账户,它会抛出 DeviceChain.Sdk.Auth.MfaRequiredException:在选择租户之前,
将异常的 Challenge 和用户的验证码传给 VerifyMfaAsync(challenge, code, cancellationToken)。
参见双因素登录。
SelectTenantAsync(tenant, cancellationToken) 返回包含
AccessToken、RefreshToken 和 ExpiresAt 的 AuthToken。这些调用中的所有取消令牌
都是可选的。client.Auth 公开会话的 Memberships、Superuser 和当前的
AccessToken。使用 GetAccessTokenAsync(cancellationToken) 获取令牌,它会在令牌
即将过期时刷新;也可以使用 RefreshAsync(cancellationToken) 显式轮换令牌。
客户端将 GetAccessTokenAsync 接入 HTTP 和订阅身份验证。
查询与订阅
client.Gql.SendAsync(area, query, variables, variablesInfo, dataInfo, options, cancellationToken)
返回反序列化后的 GraphQL 数据对象,而不是响应封装。variablesInfo
和 dataInfo 是由应用程序通过源生成器生成的 System.Text.Json 上下文
提供的 JsonTypeInfo<T>。options 和 cancellationToken 是可选的;使用
new RequestOptions { Anonymous = true } 可跳过持有者令牌。
例如,在使用 System.Text.Json 源生成器的 .NET 项目中:
using System;
using System.Text.Json;
using System.Text.Json.Serialization;
using DeviceChain.Sdk;
using DeviceChain.Sdk.Json;
await using var client = new DeviceChainClient(new Uri("https://devicechain.example.com"));
await client.LoginAsync("me@example.com", "your-password");
await client.SelectTenantAsync("acme");
JsonElement data = await client.Gql.SendAsync(
Area.DeviceManagement,
"query{devices(criteria:{pageNumber:1,pageSize:10}){results{token name}}}",
EmptyVariables.Value, AppJson.Default.EmptyVariables, AppJson.Default.JsonElement);
Console.WriteLine(data.GetProperty("devices"));
[JsonSerializable(typeof(EmptyVariables))]
[JsonSerializable(typeof(JsonElement))]
internal partial class AppJson : JsonSerializerContext { }
将 JsonElement 替换为你的 DTO 及其生成的元数据,即可获得强类型结果。
EmptyVariables 位于 DeviceChain.Sdk.Json 中;SDK 自身的 SdkJson 上下文是内部类型。
client.Subscriptions(area).SubscribeAsync(query, variables, variablesInfo, dataInfo, cancellationToken)
返回 IAsyncEnumerable<TData>。每个区域共享一个套接字,并使用与 HTTP 相同的
序列化元数据。使用可选令牌取消枚举,并在结束时释放客户端。
套接字断开或过期后,使用方需要重新订阅;新连接会获取新的令牌。
重新连接后,请查询遗漏的历史记录。
client.WebSocketUri(area) 返回订阅端点;Areas.Path(area) 返回
其 HTTP 路径。请使用 Area 枚举,而不是字符串形式的区域名称。
GraphQlRequestException 公开 Status、Errors 和可选的 RetryAfter。
每个 GraphQlError 公开 Message 和 Code;请检查这些字段,而不是匹配消息文本。
发布遥测数据
client.DevicePublisher(ingressOrigin, instanceId, tenant) 创建 HTTP 发布器。
设备入口的源地址与平台 GraphQL 的源地址相互独立。
EmitMeasurementsAsync(deviceToken, credentialId, metrics, occurredTime, cancellationToken)
接受 IReadOnlyDictionary<string, double>。
EmitLocationAsync(deviceToken, credentialId, fix, occurredTime, cancellationToken) 接受
new LocationFix(latitude, longitude),并可指定 Elevation、Accuracy、Speed 和
Heading。这两个方法都返回 Task;发生时间和取消令牌都是可选的。
坐标以 WGS84 度数表示,高程为相对于椭球面的米数,精度以米为单位,
速度以米每秒为单位,航向为从真北顺时针计算的度数。使用
LocationFix.CanonicalHeading(degrees) 规范化方位角;未知字段保留为 null。
对于 MQTT,构造 new DeviceEventPublisher(new MqttDeviceEventCarrier(session, deviceToken))。
会话必须已经启动,且令牌必须与会话的设备匹配。发送方法
仍接受 credentialId,但 MQTT 载体会将其从消息体中省略,因为 CONNECT
已经完成了设备身份验证。自定义 IDeviceEventCarrier 必须实现
CarriesBodyCredential 和 SendAsync(deviceToken, jsonEvent, cancellationToken)。
MQTT 设备会话
相关类型位于 DeviceChain.Sdk.Mqtt 和 DeviceChain.Sdk.Transport 中。
var options = new MqttSessionOptions(brokerUri, instanceId, tenant, deviceToken, credentialId);
await using var session = new MqttDeviceSession(options);
await session.StartAsync(async (command, ct) =>
{
// Apply the command to your device before returning its outcome.
await ApplyCommandAsync(command, ct); // your application function
return CommandOutcome.Succeeded();
}, cancellationToken);
在此片段中,宿主提供 URI、实例、租户、设备凭据、取消令牌,以及
ApplyCommandAsync(DeviceCommand, CancellationToken) 函数。
CommandHandler 返回 Task<CommandOutcome>;失败时使用 CommandOutcome.Failed(error),
成功时使用 CommandOutcome.Succeeded(payload),其中 payload 为可选的 JSON 文本。
DeviceCommand 携带 Token、Name、可选的 JsonElement 类型的 Payload 和到达顺序 Sequence。
StartAsync 同时要求处理程序和取消令牌,并等待订阅确认。
通过观察 State 和 StateChanged(Starting、Ready、Reconnecting、Blind、Stopped)、
RunningCommands、QueuedCommands 和 MalformedFrames 来了解运行状况。
常用的 MqttSessionOptions 设置包括 Trust(默认使用系统根证书)、
ClientCertificate、ClientIdDiscriminator、KeepAlive(60 秒)、
OperationTimeout(30 秒)、CommandHistorySize(256),以及重连延迟
ReconnectInitialDelay / ReconnectMaxDelay(1 / 30 秒)。
MaxConcurrentCommands 默认为 1。大于 1 时,使用 CommandLane 保持
相关命令的顺序;CommandShutdownTimeout 限制释放资源时等待处理程序的时长
(默认为 5 秒,上限为 MaxCommandShutdownTimeout,即 24 天)。
有关并发执行和重复投递的行为,参见
SDK README;
有关 TLS 身份和信任,参见证书身份验证。
通过 HTTP 拉取命令
DeviceChain.Sdk.Commands.HttpCommandPuller 独立于外观类构造:
new HttpCommandPuller(transport, ingressOrigin, instanceId, tenant, deviceToken, accessToken)。
使用设备的访问令牌和一个 IHttpTransport,例如封装宿主所拥有的
HttpClient 的 HttpClientTransport。设备类型必须启用 HTTP_PULL。
PullAsync(waitSeconds, cancellationToken)返回IReadOnlyList<PulledCommand>; 等待时间默认为DefaultWaitSeconds(25),范围为 0 到MaxWaitSeconds(30)。 空列表表示没有命令到达。- 在执行操作之前调用
AcknowledgeAsync(command.Token, cancellationToken)。Attempt标识可能的重复投递,因此设备操作应保持幂等。 - 如果
DeliveryMode为"ONEWAY",确认即完成投递;不要响应。 否则,在执行操作后调用RespondAsync(command.Token, success, payload, error, cancellationToken)。payload为可选的JsonElement,error为可选字符串。
PulledCommand 还公开 Name、可选的 Payload 和可选的 ExpiresAt。
这些拉取器方法中的取消令牌都是可选的。失败通过
GraphQlRequestException 报告;服务器限制轮询频率时,请遵循 RetryAfter。
Unity
使用 sdks/unity/stage-sdk.sh 准备 SDK,然后在 Unity 的 Package Manager 中
从磁盘添加 sdks/unity/io.devicechain.sdk/package.json。
该包要求 Unity 2021.3 或更高版本以及 .NET Standard 2.1 API 配置。
DeviceChain.Sdk.Unity.DeviceChainRuntime.CreateClient(origin) 接受 Uri 或
字符串,并返回与上文相同的可释放的 DeviceChainClient。它在所有平台上使用
UnityWebRequestHttpTransport,在原生平台上使用 ClientWebSocketFactory,
在 WebGL 播放器中使用 WebGlWebSocketFactory。WebGL 订阅由
DeviceChainPump 在主线程上自动推进。WebGL 播放器中的运行路径
仍未经验证;MQTT 需要原生构建。
在主线程上构造 Unity 客户端,以便其 HTTP 传输捕获 Unity 的 同步上下文。HTTP 请求和取消中止操作会自动调度回 该上下文。在主线程上开始订阅枚举以保留该上下文;将原生 MQTT 处理程序中的 场景更改调度回该上下文。在导入 Unity 之前,先将查询 DTO 和源生成的 JSON 上下文编译到 .NET 程序集中。客户端的所有者结束生命周期时,请释放客户端。
提供自身传输实现的宿主使用
new DeviceChainClient(origin, httpTransport, webSocketFactory, readLoopDriver);
客户端不拥有这两个注入的传输实现。在支持线程的宿主上,readLoopDriver 是可选的。
对于自定义 WebGL 循环,传入 ManualPumpDriver 并在每帧调用 Pump(),
或使用 DeviceChainPump.Attach(driver) 和 Detach(driver) 管理 Unity 中的推进处理。
普通的 .NET 构造函数可以复用调用方拥有的 HttpClient;否则,它会拥有
并释放自己创建的 HttpClient。