概述

CloudBase C# SDK 让您可以在 .NET 应用（包括 Unity、.NET Core、控制台及服务端应用）中使用云开发的能力，包括身份认证、文档型数据库、数据模型、MySQL 数据库、云函数、云托管、APIs、云存储等功能。

SDK 已在 GitHub 开源，欢迎查看源码、示例并反馈问题：TencentCloudBase/cloudbase-csharp-sdk。

提示

CloudBase C# SDK 已与 HTTP API 全面对齐。所有异步方法均以 Async 结尾并返回 Task<T>。

SDK 按照功能用途分为以下类别：

安装：NuGet、Unity（UPM）及源码引用等安装方式。
示例项目：仓库 examples 目录下的快速上手、终端测试工具与 Unity 游戏示例。
依赖注入：在 ASP.NET Core 等场景通过 AddCloudBase 注册 SDK。
认证登录：用户注册和登录相关的 API 方法，支持多种登录方式。
会话管理：管理用户会话状态和令牌的 API 方法。
用户管理：获取、更新和管理用户信息的 API 方法。
身份源管理：管理第三方身份源绑定和解绑的 API 方法。
密码管理：密码重置和修改相关的 API 方法。
验证管理：验证码发送、验证和重发、图形验证码创建、验证和管理相关的 API 方法。
文档型数据库：文档型（NoSQL）数据库的集合、文档、查询、聚合、事务等链式操作。
数据模型：数据模型 CRUD 操作。
数据源查询：查询数据源聚合列表、详情、Schema 和表名。
MySQL 数据库：MySQL RESTful 数据库操作。
云函数：调用云函数和函数型云托管。
云托管：调用云托管容器服务。
APIs：调用 APIs 接口。
云存储：文件上传、下载、删除、复制、移动等操作。
更新日志：各版本变更记录。

安装

.NET 项目（NuGet）
Unity 项目（UPM）
从源码引用

推荐通过 NuGet 安装：

dotnet add package Tencent.CloudBase

或在 .csproj 中添加引用：

<ItemGroup>
  <PackageReference Include="Tencent.CloudBase" Version="1.0.0" />
</ItemGroup>

自动选用 net10.0 目标（含 DI 集成）。

推荐通过 UPM Git URL 一步安装。在 Unity 中打开 Window → Package Manager → +（左上角）→ Add package from git URL...，粘贴：

https://github.com/TencentCloudBase/cloudbase-csharp-sdk.git?path=unity/com.tencent.cloudbase#v1.0.0

无需任何外部工具，自带 Unity 适配层，全平台（含 WebGL）即装即用。

适用于本地开发 / 贡献场景：

# 构建 SDK
dotnet build src/CloudBase/CloudBase.csproj

# 或构建整个解决方案（含示例）
dotnet build CloudBase.sln

在项目中添加项目引用：

<ItemGroup>
  <ProjectReference Include="path/to/src/CloudBase/CloudBase.csproj" />
</ItemGroup>

示例项目

仓库的 examples 目录提供了三个可直接运行的完整示例，覆盖从控制台到 Unity 的不同使用场景：

示例	类型	说明
QuickStart	.NET 控制台	最小化快速上手示例，演示初始化、匿名登录、获取用户等核心流程。
TerminalUI	.NET 交互式终端	基于 Spectre.Console 的交互式测试工具，菜单式逐项体验认证、云函数、数据模型、MySQL、云存储、文档数据库等能力。
UnityGame	Unity 工程	可用 Unity Hub 打开、按 Play 即可运行的完整小游戏工程，演示在 Unity 中集成登录、数据模型、文档数据库、云存储、云函数并渲染到 UI。

QuickStart（快速上手）
TerminalUI（终端测试工具）
UnityGame（Unity 游戏）

最小化控制台示例，演示初始化、匿名登录与获取用户信息。

# 设置环境变量后运行
export CLOUDBASE_ENV=your-env-id
export CLOUDBASE_ACCESS_KEY=your-publishable-key   # 可选，匿名访问用

dotnet run --project examples/QuickStart

交互式菜单工具，可逐项选择执行认证、云函数、数据模型、MySQL、云存储、文档数据库（NoSQL）等测试。

dotnet run --project examples/TerminalUI

完整可运行的 Unity 工程，演示在 Unity 中使用 SDK 的核心能力：

用 Unity Hub「Add project from disk」选择 examples/UnityGame 目录（推荐 Unity 2022.3 LTS）。
在 Assets/CloudBaseGame/Resources/CloudBaseConfig.txt 中填入环境 ID（或运行时在界面上填写）。
打开场景 Assets/CloudBaseGame/Scenes/Demo.unity，点 Play 进入交互式演示菜单。

工程通过 UPM 包 com.tencent.cloudbase 引入 SDK，涵盖登录、数据模型、文档数据库、云存储、云函数等能力。

基础使用示例

初始化配置
登录状态检查
用户注册流程
密码登录
调用云函数

accessKey 可前往云开发平台/API Key 配置中生成

using CloudBase;

// 初始化（异步静态工厂）
var app = await CloudBase.InitAsync(
    env: "your-env-id",          // 替换为您的环境ID
    region: "ap-shanghai",        // 地域，默认为上海
    accessKey: "your-key",        // 填入生成的 Publishable Key
    authConfig: new AuthConfig
    {
        DetectSessionInUrl = true // 可选：自动检测 URL 中的 OAuth 参数
    }
);

var auth = app.Auth;

InitAsync 完整参数：

参数	类型	默认值	说明
`env`	`string`	必填	TCB 环境 ID
`region`	`string`	`ap-shanghai`	地域
`lang`	`string`	`zh-CN`	语言
`accessKey`	`string?`	`null`	Publishable Key，用于匿名访问
`authConfig`	`AuthConfig?`	`null`	认证配置（如 `DetectSessionInUrl`）
`captchaConfig`	`CaptchaConfig?`	`null`	验证码配置（如 `OnCaptchaRequired` 回调）
`store`	`IKeyValueStore?`	`null`	键值存储实现，为 null 时使用默认文件存储；服务端多租户建议注入自定义实现
`httpClient`	`HttpClient?`	`null`	自定义 `HttpClient`（WebGL 平台不可用）
`transport`	`IHttpTransport?`	`null`	自定义 HTTP 传输层
`intl`	`bool`	`false`	是否国际站

初始化后可通过 app.Auth、app.Storage、app.MySql、app.Apis、app.Functions、app.CloudRun、app.Models、app.Database(...) 访问各模块。使用完毕后可调用 app.Dispose() 释放底层 HttpClient（DI 场景由容器自动管理，无需手动释放）。

// 检查登录状态
async Task<bool> CheckAuthStatusAsync()
{
    var result = await auth.GetSessionAsync();

    if (result.Error != null)
    {
        Console.WriteLine($"检查登录状态失败: {result.Error.Message}");
        return false;
    }

    if (result.Data?.Session != null)
    {
        Console.WriteLine($"用户已登录: {result.Data.User?.Id}");
        return true;
    }
    else
    {
        Console.WriteLine("用户未登录");
        return false;
    }
}

// 用户注册示例（两步验证流程）
async Task RegisterUserAsync(string email, string password)
{
    // 第一步：发送验证码
    var signUpResult = await auth.SignUpAsync(new SignUpReq
    {
        Email = email,
        Password = password,
    });

    if (signUpResult.Error != null)
    {
        Console.WriteLine($"发送验证码失败: {signUpResult.Error.Message}");
        return;
    }

    Console.WriteLine("验证码已发送，等待用户输入...");

    // 第二步：验证验证码并完成注册
    var verifyResult = await signUpResult.Data!.VerifyOtp!(
        new VerifyOtpParams { Token = "用户输入的验证码" }
    );

    if (verifyResult.Error != null)
    {
        Console.WriteLine($"注册失败: {verifyResult.Error.Message}");
    }
    else
    {
        Console.WriteLine($"注册成功: {verifyResult.Data?.User?.Id}");
    }
}

// 密码登录示例
async Task LoginWithPasswordAsync(string email, string password)
{
    var result = await auth.SignInWithPasswordAsync(new SignInWithPasswordReq
    {
        Username = email,
        Password = password,
    });

    if (result.Error != null)
    {
        Console.WriteLine($"登录失败: {result.Error.Message}");
        return;
    }

    Console.WriteLine($"登录成功: {result.Data?.User?.Id}");
}

// 调用云函数示例
var result = await app.CallFunctionAsync(
    name: "hello",
    data: new Dictionary<string, object?> { ["name"] = "CloudBase" }
);

if (result.IsSuccess)
{
    Console.WriteLine($"执行结果: {result.Result}");
}
else
{
    Console.WriteLine($"执行失败: {result.Message}");
}

依赖注入

在 ASP.NET Core / Blazor Server / Worker 等基于 Microsoft.Extensions.DependencyInjection 的场景中，可通过 AddCloudBase 扩展方法将 SDK 注册到 DI 容器。内部通过 IHttpClientFactory 复用连接池，CloudBase 实例以单例懒加载方式初始化（仅初始化一次）。

note

该能力仅在 .NET（net10.0）目标下可用。

AddCloudBase

IServiceCollection services.AddCloudBase(Action<CloudBaseOptions> configure)

将 CloudBase 注册到依赖注入容器。由于 CloudBase.InitAsync 是异步工厂，DI 无法直接构造，因此注册的是一个访问器 ICloudBaseAccessor，通过 GetAsync() 按需异步获取实例。

参数

configure

Action<CloudBaseOptions>

配置委托

Envstring

TCB 环境 ID（必填）

Region可选string

地域，默认 ap-shanghai

Lang可选string

语言，默认 zh-CN

AccessKey可选string?

Publishable Key，用于匿名访问

AuthConfig可选AuthConfig?

认证配置

CaptchaConfig可选CaptchaConfig?

验证码配置

Intl可选bool

是否国际站

Store可选IKeyValueStore?

键值存储实现，为 null 时使用默认文件存储；服务端多租户建议注入自定义实现

IServiceCollection

服务集合（便于链式调用）

示例

注册
消费（注入访问器）

using CloudBase.DependencyInjection;

// Program.cs
builder.Services.AddCloudBase(options =>
{
    options.Env = "your-env-id";
    options.Region = "ap-shanghai";
    options.AccessKey = "your-key"; // 可选，匿名访问用
});

using CloudBase.DependencyInjection;

// 注入 ICloudBaseAccessor，按需异步获取实例（线程安全，全程复用同一实例）
public class TodoService(ICloudBaseAccessor cloudbase)
{
    public async Task<int> CountAsync(CancellationToken ct)
    {
        var app = await cloudbase.GetAsync(ct);
        var res = await app.Database().Collection("todos").Count();
        return res.Total;
    }
}

认证登录

SignUpAsync

Task<CloudBaseResponse<SignUpResData>> auth.SignUpAsync(SignUpReq @params)

注册新用户账户，采用智能注册并登录流程。

创建一个新的用户账户
采用智能注册并登录流程：发送验证码 → 等待用户输入 → 智能判断用户存在性 → 自动登录或注册并登录
如果用户已存在则直接登录，如果用户不存在则注册新用户并自动登录

参数

@params

SignUpReq

Task

CloudBaseResponse<SignUpResData>

DataSignUpResData

VerifyOtp

可选

Func<VerifyOtpParams, Task<CloudBaseResponse<SignInResData>>>?

验证码回调函数，用于验证用户输入的验证码

ErrorCloudBaseError?

错误信息，成功时为 null

示例

邮箱注册
手机号注册
错误处理

var result = await auth.SignUpAsync(new SignUpReq
{
    Email = "user@example.com",
    Password = "securePassword123",
    Nickname = "新用户",
});

if (result.Error != null)
{
    Console.WriteLine($"注册失败: {result.Error.Message}");
    return;
}

// 验证码验证
var verifyResult = await result.Data!.VerifyOtp!(
    new VerifyOtpParams { Token = "123456" }
);

if (verifyResult.IsSuccess)
{
    Console.WriteLine($"注册成功: {verifyResult.Data?.User?.Id}");
}

var result = await auth.SignUpAsync(new SignUpReq
{
    Phone = "13800138000",
    Password = "securePassword123",
});

if (result.Error != null)
{
    Console.WriteLine($"发送验证码失败: {result.Error.Message}");
    return;
}

var verifyResult = await result.Data!.VerifyOtp!(
    new VerifyOtpParams { Token = "123456" }
);

if (verifyResult.IsSuccess)
{
    Console.WriteLine($"注册成功: {verifyResult.Data?.User?.Phone}");
}

var result = await auth.SignUpAsync(new SignUpReq
{
    Email = "user@example.com",
    Password = "password123",
});

if (result.Error != null)
{
    var code = result.Error.Code;
    switch (code)
    {
        case "already_exists":
            Console.WriteLine("邮箱已被注册");
            break;
        case "password_too_weak":
            Console.WriteLine("密码强度不足");
            break;
        case "invalid_email":
            Console.WriteLine("邮箱格式错误");
            break;
        default:
            Console.WriteLine($"注册失败: {result.Error.Message}");
            break;
    }
}

SignInAnonymouslyAsync

Task<CloudBaseResponse<SignInResData>> auth.SignInAnonymouslyAsync(string? providerToken = null)

匿名登录，无需用户提供任何凭证即可创建临时账户。

参数

providerToken

string?

可选的第三方 provider token

Task

CloudBaseResponse<SignInResData>

示例

匿名登录

var result = await auth.SignInAnonymouslyAsync();

if (result.IsSuccess)
{
    Console.WriteLine($"匿名登录成功: {result.Data?.User?.Id}");
}
else
{
    Console.WriteLine($"匿名登录失败: {result.Error?.Message}");
}

SignInWithPasswordAsync

Task<CloudBaseResponse<SignInResData>> auth.SignInWithPasswordAsync(SignInWithPasswordReq @params)

使用用户名（或邮箱、手机号）和密码登录。

参数

@params

SignInWithPasswordReq

Task

CloudBaseResponse<SignInResData>

示例

密码登录

var result = await auth.SignInWithPasswordAsync(new SignInWithPasswordReq
{
    Username = "user@example.com",
    Password = "securePassword123",
});

if (result.IsSuccess)
{
    Console.WriteLine($"登录成功: {result.Data?.User?.Id}");
}
else
{
    Console.WriteLine($"登录失败: {result.Error?.Message}");
}

SignInWithUsernameAsync

Task<CloudBaseResponse<SignInResData>> auth.SignInWithUsernameAsync(
    VerificationInfo verificationInfo,
    string verificationCode,
    string username,
    string? loginType = null,
    Dictionary<string, object?>? bindInfo = null)

使用用户名（或邮箱、手机号）配合验证码登录。verificationInfo 由 GetVerificationAsync 获取，verificationCode 为用户输入的验证码。

参数

verificationInfo

VerificationInfo

验证信息（由 GetVerificationAsync 返回）

verificationCode

string

验证码

username

string

用户名 / 邮箱 / 手机号

loginType

string?

登录类型（可选）

bindInfo

Dictionary<string, object?>?

绑定信息（可选）

Task

CloudBaseResponse<SignInResData>

示例

用户名 + 验证码登录

// 1. 先获取验证信息（发送验证码）
var verifyRes = await auth.GetVerificationAsync(new GetVerificationReq
{
    Username = "user@example.com",
});

if (verifyRes.Error != null)
{
    Console.WriteLine($"获取验证信息失败: {verifyRes.Error.Message}");
    return;
}

// 2. 使用验证信息 + 用户输入的验证码登录
var result = await auth.SignInWithUsernameAsync(
    verificationInfo: verifyRes.Data!.VerificationInfo!,
    verificationCode: "123456",
    username: "user@example.com"
);

if (result.IsSuccess)
{
    Console.WriteLine($"登录成功: {result.Data?.User?.Id}");
}
else
{
    Console.WriteLine($"登录失败: {result.Error?.Message}");
}

SignInWithOtpAsync

Task<CloudBaseResponse<SignInWithOtpResData>> auth.SignInWithOtpAsync(SignInWithOtpReq @params)

使用一次性验证码（OTP）登录。发送验证码后，通过返回数据中的 VerifyOtp 回调完成验证。

参数

@params

SignInWithOtpReq

Task

CloudBaseResponse<SignInWithOtpResData>

示例

邮箱验证码登录

var result = await auth.SignInWithOtpAsync(new SignInWithOtpReq
{
    Email = "user@example.com",
});

if (result.Error != null)
{
    Console.WriteLine($"发送验证码失败: {result.Error.Message}");
    return;
}

var verifyResult = await result.Data!.VerifyOtp!(
    new VerifyOtpParams { Token = "123456" }
);

if (verifyResult.IsSuccess)
{
    Console.WriteLine($"登录成功: {verifyResult.Data?.User?.Id}");
}

SignInWithOAuthAsync

Task<CloudBaseResponse<SignInOAuthResData>> auth.SignInWithOAuthAsync(SignInWithOAuthReq @params)

使用第三方 OAuth 提供商登录（如微信、GitHub 等）。

参数

@params

SignInWithOAuthReq

Task

CloudBaseResponse<SignInOAuthResData>

示例

OAuth 登录

var result = await auth.SignInWithOAuthAsync(new SignInWithOAuthReq
{
    Provider = "wechat",
    RedirectTo = "https://your-app.com/callback",
});

if (result.IsSuccess)
{
    Console.WriteLine($"请跳转至授权地址: {result.Data?.Url}");
}

SignInWithIdTokenAsync

Task<CloudBaseResponse<SignInResData>> auth.SignInWithIdTokenAsync(SignInWithIdTokenReq @params)

使用第三方 ID Token 登录。

参数

@params

SignInWithIdTokenReq

Task

CloudBaseResponse<SignInResData>

示例

ID Token 登录

var result = await auth.SignInWithIdTokenAsync(new SignInWithIdTokenReq
{
    IdToken = "your-id-token",
    Provider = "google",
});

if (result.IsSuccess)
{
    Console.WriteLine($"登录成功: {result.Data?.User?.Id}");
}

SignInWithCustomTicketAsync

Task<CloudBaseResponse<SignInResData>> auth.SignInWithCustomTicketAsync(Func<Task<string>> getTicketFn)

使用自定义登录票据（Custom Ticket）登录。通过传入一个异步函数动态获取票据。

参数

getTicketFn

Func<Task<string>>

返回自定义登录票据的异步函数

Task

CloudBaseResponse<SignInResData>

示例

自定义票据登录

var result = await auth.SignInWithCustomTicketAsync(async () =>
{
    // 从您的服务端获取自定义登录票据
    return await FetchTicketFromServerAsync();
});

if (result.IsSuccess)
{
    Console.WriteLine($"登录成功: {result.Data?.User?.Id}");
}

会话管理

GetSessionAsync

Task<CloudBaseResponse<SignInResData>> auth.GetSessionAsync()

获取当前登录会话信息。如果本地存在有效会话则返回该会话，否则 Data.Session 为 null。

参数

无参数

Task

CloudBaseResponse<SignInResData>

示例

获取会话

var result = await auth.GetSessionAsync();

if (result.Data?.Session != null)
{
    Console.WriteLine($"用户已登录: {result.Data.User?.Id}");
}
else
{
    Console.WriteLine("用户未登录");
}

RefreshSessionAsync

Task<CloudBaseResponse<SignInResData>> auth.RefreshSessionAsync(string? refreshToken = null)

刷新会话令牌。可传入指定的 refresh token，不传则使用当前会话的 refresh token。

参数

refreshToken

string?

刷新令牌，不传则使用当前会话的令牌

Task

CloudBaseResponse<SignInResData>

示例

刷新会话

var result = await auth.RefreshSessionAsync();

if (result.IsSuccess)
{
    Console.WriteLine($"会话已刷新: {result.Data?.Session?.AccessToken}");
}

SetSessionAsync

Task<CloudBaseResponse<SignInResData>> auth.SetSessionAsync(SetSessionReq @params)

手动设置会话（例如从服务端恢复会话）。

参数

@params

SetSessionReq

Task

CloudBaseResponse<SignInResData>

示例

设置会话

var result = await auth.SetSessionAsync(new SetSessionReq
{
    AccessToken = "your-access-token",
    RefreshToken = "your-refresh-token",
});

if (result.IsSuccess)
{
    Console.WriteLine($"会话已设置: {result.Data?.User?.Id}");
}

SignOutAsync

Task<CloudBaseResponse<object?>> auth.SignOutAsync(SignOutReq? @params = null)

退出登录，清除本地会话。

参数

@params

SignOutReq?

退出登录参数，可选

Task

CloudBaseResponse<object?>

示例

退出登录

var result = await auth.SignOutAsync();

if (result.IsSuccess)
{
    Console.WriteLine("已退出登录");
}

OnAuthStateChange

CloudBaseResponse<OnAuthStateChangeResultData> auth.OnAuthStateChange(OnAuthStateChangeCallback callback)

监听登录状态变化。当用户登录、登出或令牌刷新时触发回调。该方法为同步方法，返回一个可用于取消订阅的对象。

参数

callback

OnAuthStateChangeCallback

状态变化回调，接收事件类型与会话数据

Return

CloudBaseResponse<OnAuthStateChangeResultData>

示例

监听登录状态

var subscription = auth.OnAuthStateChange((eventType, session) =>
{
    Console.WriteLine($"登录状态变化: {eventType}");
    if (session != null)
    {
        Console.WriteLine($"当前用户: {session.User?.Id}");
    }
});

// 取消订阅
subscription.Data?.Unsubscribe();

GetClaimsAsync

Task<CloudBaseResponse<GetClaimsResData>> auth.GetClaimsAsync()

获取当前用户的 JWT Claims 信息。

参数

无参数

Task

CloudBaseResponse<GetClaimsResData>

示例

获取 Claims

var result = await auth.GetClaimsAsync();

if (result.IsSuccess)
{
    Console.WriteLine($"Claims: {result.Data}");
}

用户管理

GetUserAsync

Task<CloudBaseResponse<GetUserResData>> auth.GetUserAsync()

获取当前登录用户的详细信息。

参数

无参数

Task

CloudBaseResponse<GetUserResData>

示例

获取用户信息

var result = await auth.GetUserAsync();

if (result.IsSuccess)
{
    Console.WriteLine($"用户 ID: {result.Data?.User?.Id}");
    Console.WriteLine($"昵称: {result.Data?.User?.Nickname}");
}

RefreshUserAsync

Task<CloudBaseResponse<SignInResData>> auth.RefreshUserAsync()

刷新并重新拉取当前用户信息。

参数

无参数

Task

CloudBaseResponse<SignInResData>

示例

刷新用户信息

var result = await auth.RefreshUserAsync();

if (result.IsSuccess)
{
    Console.WriteLine($"用户已刷新: {result.Data?.User?.Nickname}");
}

UpdateUserAsync

Task<CloudBaseResponse<UpdateUserResData>> auth.UpdateUserAsync(UpdateUserReq @params)

更新当前用户的资料信息。

参数

@params

UpdateUserReq

Task

CloudBaseResponse<UpdateUserResData>

示例

更新用户资料

var result = await auth.UpdateUserAsync(new UpdateUserReq
{
    Nickname = "新昵称",
    AvatarUrl = "https://example.com/avatar.png",
});

if (result.IsSuccess)
{
    Console.WriteLine("用户资料已更新");
}

DeleteUserAsync

Task<CloudBaseResponse<object?>> auth.DeleteUserAsync(DeleteUserReq @params)

删除（注销）当前用户账户。

参数

@params

DeleteUserReq

删除用户参数

Task

CloudBaseResponse<object?>

示例

删除用户

var result = await auth.DeleteUserAsync(new DeleteUserReq());

if (result.IsSuccess)
{
    Console.WriteLine("账户已注销");
}

身份源管理

GetUserIdentitiesAsync

Task<CloudBaseResponse<GetUserIdentitiesResData>> auth.GetUserIdentitiesAsync()

获取当前用户已绑定的身份源列表。

参数

无参数

Task

CloudBaseResponse<GetUserIdentitiesResData>

示例

获取身份源列表

var result = await auth.GetUserIdentitiesAsync();

if (result.IsSuccess)
{
    Console.WriteLine($"身份源: {result.Data}");
}

LinkIdentityAsync

Task<CloudBaseResponse<LinkIdentityResData>> auth.LinkIdentityAsync(LinkIdentityReq @params)

为当前用户绑定新的第三方身份源。

参数

@params

LinkIdentityReq

Task

CloudBaseResponse<LinkIdentityResData>

示例

绑定身份源

var result = await auth.LinkIdentityAsync(new LinkIdentityReq
{
    Provider = "wechat",
});

if (result.IsSuccess)
{
    Console.WriteLine("身份源已绑定");
}

UnlinkIdentityAsync

Task<CloudBaseResponse<object?>> auth.UnlinkIdentityAsync(UnlinkIdentityReq @params)

解绑当前用户的某个第三方身份源。

参数

@params

UnlinkIdentityReq

Task

CloudBaseResponse<object?>

示例

解绑身份源

var result = await auth.UnlinkIdentityAsync(new UnlinkIdentityReq
{
    Provider = "wechat",
});

if (result.IsSuccess)
{
    Console.WriteLine("身份源已解绑");
}

密码管理

ResetPasswordForEmailAsync

Task<CloudBaseResponse<ResetPasswordForEmailResData>> auth.ResetPasswordForEmailAsync(string emailOrPhone, string? redirectTo = null)

通过邮箱或手机号发起密码重置流程。

参数

emailOrPhone

string

邮箱或手机号

redirectTo

string?

重置成功后的重定向地址

Task

CloudBaseResponse<ResetPasswordForEmailResData>

示例

邮箱重置密码

var result = await auth.ResetPasswordForEmailAsync(
    "user@example.com",
    "https://your-app.com/reset"
);

if (result.IsSuccess)
{
    Console.WriteLine("密码重置邮件已发送");
}

ResetPasswordForOldAsync

Task<CloudBaseResponse<SignInResData>> auth.ResetPasswordForOldAsync(ResetPasswordForOldReq @params)

通过旧密码修改为新密码。

参数

@params

ResetPasswordForOldReq

Task

CloudBaseResponse<SignInResData>

示例

修改密码

var result = await auth.ResetPasswordForOldAsync(new ResetPasswordForOldReq
{
    OldPassword = "oldPassword123",
    NewPassword = "newPassword456",
});

if (result.IsSuccess)
{
    Console.WriteLine("密码已修改");
}

ReauthenticateAsync

Task<CloudBaseResponse<ReauthenticateResData>> auth.ReauthenticateAsync()

对当前用户进行二次身份验证（敏感操作前的重新认证）。

参数

无参数

Task

CloudBaseResponse<ReauthenticateResData>

示例

二次验证

var result = await auth.ReauthenticateAsync();

if (result.IsSuccess)
{
    Console.WriteLine("二次验证成功");
}

验证管理

GetVerificationAsync

Task<CloudBaseResponse<GetVerificationResData>> auth.GetVerificationAsync(string? email = null, string? phoneNumber = null)

发送验证码到指定邮箱或手机号，返回验证 ID 用于后续验证。

参数

string?

邮箱（与 phoneNumber 二选一）

phoneNumber

string?

手机号（与 email 二选一）

Task

CloudBaseResponse<GetVerificationResData>

示例

发送验证码

var result = await auth.GetVerificationAsync(email: "user@example.com");

if (result.IsSuccess)
{
    Console.WriteLine($"验证 ID: {result.Data?.VerificationId}");
}

VerifyAsync

Task<CloudBaseResponse<VerifyCodeResData>> auth.VerifyAsync(string verificationId, string verificationCode)

校验用户输入的验证码。

参数

verificationId

string

GetVerificationAsync 返回的验证 ID

verificationCode

string

用户输入的验证码

Task

CloudBaseResponse<VerifyCodeResData>

示例

校验验证码

var result = await auth.VerifyAsync("verification-id", "123456");

if (result.IsSuccess)
{
    Console.WriteLine("验证码校验通过");
}

VerifyOtpAsync

Task<CloudBaseResponse<SignInResData>> auth.VerifyOtpAsync(VerifyOtpReq @params)

校验 OTP 验证码并完成登录 / 注册。通常通过注册或登录返回数据中的 VerifyOtp 回调调用，也可直接使用此方法。

参数

@params

VerifyOtpReq

Task

CloudBaseResponse<SignInResData>

示例

校验 OTP

var result = await auth.VerifyOtpAsync(new VerifyOtpReq
{
    Token = "123456",
    VerificationId = "verification-id",
});

if (result.IsSuccess)
{
    Console.WriteLine($"登录成功: {result.Data?.User?.Id}");
}

VerifyOAuthAsync

Task<CloudBaseResponse<VerifyOAuthResData>> auth.VerifyOAuthAsync(VerifyOAuthReq? @params = null)

校验 OAuth 登录回调，完成 OAuth 登录流程。

参数

@params

VerifyOAuthReq?

OAuth 校验参数，可选（默认从 URL 中检测）

Task

CloudBaseResponse<VerifyOAuthResData>

示例

校验 OAuth

var result = await auth.VerifyOAuthAsync();

if (result.IsSuccess)
{
    Console.WriteLine($"OAuth 登录成功: {result.Data}");
}

ResendAsync

Task<CloudBaseResponse<ResendResData>> auth.ResendAsync(ResendReq @params)

重新发送验证码。

参数

@params

ResendReq

Task

CloudBaseResponse<ResendResData>

示例

重发验证码

var result = await auth.ResendAsync(new ResendReq
{
    VerificationId = "verification-id",
});

if (result.IsSuccess)
{
    Console.WriteLine("验证码已重新发送");
}

GetCaptchaTokenAsync

Task<string?> app.Captcha.GetCaptchaTokenAsync(bool forceNew = false, string state = "")

获取图形验证码 token。当需要人机验证时，SDK 会通过 CaptchaConfig.OnCaptchaRequired 回调收集用户输入。

参数

forceNew

bool

是否强制获取新的 token，默认 false

state

string

验证状态标识，默认空字符串

Task

string?

验证码 token，获取失败时为 null

示例

获取验证码 token

// 初始化时配置人机验证回调
var app = await CloudBase.InitAsync(
    env: "your-env-id",
    captchaConfig: new CaptchaConfig
    {
        OnCaptchaRequired = async (state) =>
        {
            // 弹出您的验证码 UI，返回用户完成验证后的 token
            return await ShowCaptchaUiAsync(state);
        }
    }
);

var token = await app.Captcha.GetCaptchaTokenAsync();
Console.WriteLine($"验证码 token: {token}");

CreateCaptchaDataAsync

Task<CreateCaptchaDataRes> app.Captcha.CreateCaptchaDataAsync(string state)

创建图形验证码数据。

参数

state

string

验证状态标识

Task

CreateCaptchaDataRes

验证码数据

示例

创建验证码数据

var data = await app.Captcha.CreateCaptchaDataAsync("login");
Console.WriteLine($"验证码数据: {data}");

VerifyCaptchaDataAsync

Task<VerifyCaptchaRes> app.Captcha.VerifyCaptchaDataAsync(string token, string key)

校验图形验证码数据。

参数

token

string

验证码 token

key

string

验证 key

Task

VerifyCaptchaRes

校验结果

示例

校验验证码

var result = await app.Captcha.VerifyCaptchaDataAsync("token", "key");
Console.WriteLine($"校验结果: {result}");

AppendCaptchaTokenToUrlAsync

Task<string> app.Captcha.AppendCaptchaTokenToUrlAsync(
    string url,
    string state,
    bool forceNew = false)

获取验证码 token 并将其作为查询参数追加到指定 URL 上，返回拼接后的 URL。

参数

url

string

原始 URL

state

string

业务侧的 state 标识

forceNew

bool

是否强制获取新的 token，默认 false

Task

string

追加验证码 token 后的 URL

示例

追加 token 到 URL

var url = await app.Captcha.AppendCaptchaTokenToUrlAsync(
    "https://example.com/api",
    "login"
);
Console.WriteLine($"URL: {url}");

FindCaptchaTokenAsync

Task<string?> app.Captcha.FindCaptchaTokenAsync()

查找本地缓存中有效的验证码 token，若不存在或已过期则返回 null。

参数

无参数

Task

string?

缓存的验证码 token，不存在时为 null

示例

查找缓存 token

var token = await app.Captcha.FindCaptchaTokenAsync();
Console.WriteLine($"缓存 token: {token}");

ClearCaptchaTokenAsync

Task app.Captcha.ClearCaptchaTokenAsync()

清除本地缓存的验证码 token。

参数

无参数

Task

void

无返回值

示例

清除验证码 token

await app.Captcha.ClearCaptchaTokenAsync();
Console.WriteLine("验证码 token 已清除");

文档型数据库

文档型（NoSQL）数据库通过 app.Database() 获取操作入口 CloudBaseDb，采用链式（fluent）调用风格，与 JS SDK 的 app.database() 对齐。

var db = app.Database();                 // 默认实例 / 数据库
var db2 = app.Database("instance", "db"); // 指定实例与数据库
var _ = db.Command;                      // 获取操作符集合

Database

CloudBaseDb app.Database(string? instance = null, string? database = null)

获取文档型数据库操作入口。

参数

instance

string?

数据库实例标识，默认 (default)

database

string?

数据库名，默认 (default)

CloudBaseDb

文档型数据库操作入口

示例

获取入口

var db = app.Database();

Collection

CollectionReference db.Collection(string collectionName)

获取集合引用，用于链式调用。

参数

collectionName

string

集合名称

CollectionReference

集合引用

示例

获取集合引用

var collection = db.Collection("todos");

CreateCollectionAsync

Task<DbCollectionResult> db.CreateCollectionAsync(string collectionName)

创建集合。

参数

collectionName

string

集合名称

Task

DbCollectionResult

示例

创建集合

var result = await db.CreateCollectionAsync("todos");

if (result.IsSuccess)
{
    Console.WriteLine("集合创建成功");
}

Add

Task<DbAddResult> db.Collection(name).Add(object data)

新增记录。传入单个对象为单条新增（返回 Id），传入对象集合为批量新增（返回 Ids）。

参数

data

object

单个文档对象或文档对象集合

Task

DbAddResult

示例

新增单条
批量新增

var result = await db.Collection("todos").Add(new
{
    title = "学习 CloudBase",
    completed = false,
});

Console.WriteLine($"新增文档 ID: {result.Id}");

var result = await db.Collection("todos").Add(new[]
{
    new { title = "任务 A", completed = false },
    new { title = "任务 B", completed = false },
});

Console.WriteLine($"新增 {result.Ids.Count} 条");

Where

Query query.Where(object condition)

设置查询条件，可多次调用合并条件。条件中的字段值可结合 db.Command 操作符使用。

参数

condition

object

查询条件对象（匿名对象 / 字典 / 含操作符的字段）

Query

查询构建器（支持继续链式调用）

示例

条件查询

var _ = db.Command;

var result = await db.Collection("todos")
    .Where(new Dictionary<string, object?>
    {
        ["completed"] = false,
        ["priority"] = _.Gte(2),
    })
    .Get();

foreach (var doc in result.Data)
{
    Console.WriteLine(doc["title"]);
}

OrderBy

Query query.OrderBy(string fieldPath, string direction = "asc")

设置排序，可多次调用按多字段排序。

参数

fieldPath

string

排序字段路径

direction

string

排序方向：asc 升序（默认），desc 降序

Query

查询构建器

示例

排序

var result = await db.Collection("todos")
    .OrderBy("createdAt", "desc")
    .Get();

Limit

Query query.Limit(int max)

限制返回的最大记录数。

参数

max

int

最大记录数

Query

查询构建器

示例

限制条数

var result = await db.Collection("todos").Limit(10).Get();

Skip

Query query.Skip(int offset)

设置结果偏移量，用于分页。

参数

offset

int

偏移量

Query

查询构建器

示例

分页

var result = await db.Collection("todos")
    .Skip(20)
    .Limit(10)
    .Get();

Field

Query query.Field(object projection)

指定返回字段（投影）。

参数

projection

object

字段投影，如 new { title = true, content = false }

Query

查询构建器

示例

指定字段

var result = await db.Collection("todos")
    .Field(new { title = true, completed = true })
    .Get();

Get

Task<DbQueryResult> query.Get()

执行查询，返回匹配的文档列表。Query / CollectionReference / DocumentReference 均支持直接 await，等价于调用 Get()。

参数

无参数

Task

DbQueryResult

示例

查询列表
直接 await

var result = await db.Collection("todos")
    .Where(new { completed = false })
    .OrderBy("createdAt", "desc")
    .Limit(10)
    .Get();

foreach (var doc in result.Data)
{
    Console.WriteLine(doc["title"]);
}

// 省略 .Get()，直接 await 查询构建器
var result = await db.Collection("todos").Where(new { completed = false });

Count

Task<DbCountResult> query.Count()

统计匹配条件的文档数量。

参数

无参数

Task

DbCountResult

示例

统计数量

var result = await db.Collection("todos")
    .Where(new { completed = false })
    .Count();

Console.WriteLine($"未完成: {result.Total}");

Update

Task<DbUpdateResult> query.Update(object data)

批量更新匹配条件的文档。普通字段自动归入 $set，操作符（如 _.Inc(1)）按语义归组。

参数

data

object

更新内容

Task

DbUpdateResult

示例

批量更新

var _ = db.Command;

var result = await db.Collection("todos")
    .Where(new { completed = false })
    .Update(new Dictionary<string, object?>
    {
        ["completed"] = true,
        ["views"] = _.Inc(1),
    });

Console.WriteLine($"更新 {result.Updated} 条");

Remove

Task<DbDeleteResult> query.Remove()

批量删除匹配条件的文档。

参数

无参数

Task

DbDeleteResult

示例

批量删除

var result = await db.Collection("todos")
    .Where(new { completed = true })
    .Remove();

Console.WriteLine($"删除 {result.Deleted} 条");

Doc

DocumentReference db.Collection(name).Doc(string docId)

通过文档 ID 获取文档引用，用于对单条记录进行 Get / Set / Update / Remove。

参数

docId

string

文档 ID

DocumentReference

文档引用

示例

查询单条
设置文档（覆盖）
更新 / 删除单条

var result = await db.Collection("todos").Doc("doc-id-123").Get();

if (result.IsSuccess && result.Data.Count > 0)
{
    Console.WriteLine(result.Data[0]["title"]);
}

// Set：完全替换文档内容，不存在则创建
await db.Collection("todos").Doc("doc-id-123").Set(new
{
    title = "新标题",
    completed = true,
});

// Update：合并更新
await db.Collection("todos").Doc("doc-id-123").Update(new { completed = true });

// Remove：删除
await db.Collection("todos").Doc("doc-id-123").Remove();

OfType

TypedQuery<T> db.Collection(name).OfType<T>()

进入强类型查询模式，返回基于表达式树的 TypedQuery<T>，支持 Where(x => x.Completed == false) 等编译期类型安全的查询、排序与分页。

参数

无参数

TypedQuery<T>

强类型查询构建器

示例

强类型查询

public class Todo
{
    public string Title { get; set; } = "";
    public bool Completed { get; set; }
    public int Priority { get; set; }
    public long CreatedAt { get; set; }
}

var res = await db.Collection("todos").OfType<Todo>()
    .Where(x => !x.Completed && x.Priority >= 2)
    .OrderByDescending(x => x.CreatedAt)
    .Limit(10)
    .Get();

foreach (var todo in res.Data)
{
    Console.WriteLine(todo.Title); // todo 为强类型 Todo
}

Aggregate

DbAggregate db.Collection(name).Aggregate()

获取聚合操作对象，按顺序追加聚合阶段，最后以 End() 执行。支持 Match / Group / Sort / Project / Limit / Skip / Lookup / Unwind / AddFields / Count / Sample / ReplaceRoot / SortByCount / Bucket / BucketAuto / GeoNear 等阶段。

参数

无参数

DbAggregate

聚合操作对象

示例

聚合查询

var result = await db.Collection("orders")
    .Aggregate()
    .Match(new { status = "paid" })
    .Group(new Dictionary<string, object?>
    {
        ["_id"] = "$userId",
        ["total"] = new Dictionary<string, object?> { ["$sum"] = "$amount" },
    })
    .Sort(new { total = -1 })
    .Limit(10)
    .End();

foreach (var row in result.Data)
{
    Console.WriteLine($"{row["_id"]}: {row["total"]}");
}

StartTransactionAsync

Task<DbTransaction> db.StartTransactionAsync()

开启事务，返回可链式操作的事务对象 DbTransaction。通过 transaction.Collection(name) 在事务内操作文档，最后 CommitAsync() 提交或 RollbackAsync() 回滚。

参数

无参数

Task

DbTransaction

示例

事务操作

var transaction = await db.StartTransactionAsync();

if (transaction.IsSuccess)
{
    try
    {
        await transaction.Collection("accounts").Doc("a")
            .Update(new Dictionary<string, object?> { ["balance"] = db.Command.Inc(-100) });
        await transaction.Collection("accounts").Doc("b")
            .Update(new Dictionary<string, object?> { ["balance"] = db.Command.Inc(100) });

        await transaction.CommitAsync();   // 提交
    }
    catch
    {
        await transaction.RollbackAsync(); // 回滚
    }
}

RunCommandsAsync

Task<DbCommandResult> db.RunCommandsAsync(
    IEnumerable<object?> commands,
    string? transactionId = null)

执行 MongoDB 原生命令。

参数

commands

IEnumerable<object?>

命令数组，每个元素为一个 MongoDB 原生命令对象

transactionId

string?

事务 ID（在事务中执行所有命令，可选）

Task

DbCommandResult

示例

执行原生命令

var result = await db.RunCommandsAsync(new object?[]
{
    new Dictionary<string, object?>
    {
        ["find"] = "todos",
        ["filter"] = new Dictionary<string, object?> { ["completed"] = false },
    },
});

if (result.IsSuccess)
{
    Console.WriteLine($"命令数: {result.List.Count}");
}

RegExp

Dictionary<string, object?> db.RegExp(string regexp, string? options = null)

构造正则表达式匹配对象，用于 Where 中的模糊匹配，等价 MongoDB { $regex, $options }。

参数

regexp

string

正则表达式字符串

options

string?

正则选项，如 "i" 表示忽略大小写

Dictionary<string, object?>

正则匹配对象

示例

模糊匹配

var result = await db.Collection("todos")
    .Where(new Dictionary<string, object?>
    {
        ["title"] = db.RegExp("cloud", "i"),
    })
    .Get();

Command

DbCommand db.Command

数据库操作符集合（对齐 db.command），分为查询操作符与更新操作符两类，返回 MongoDB 风格的操作符对象，可直接作为字段值参与 Where / Update。

参数

无参数

DbCommand

操作符集合

示例

查询操作符
更新操作符

var _ = db.Command;

// 比较：Eq / Neq / Gt / Gte / Lt / Lte / In / Nin
// 逻辑：And / Or / Not / Nor
// 字段/数组：Exists / Mod / All / ElemMatch / Size
var result = await db.Collection("users")
    .Where(new Dictionary<string, object?>
    {
        ["age"] = _.Gt(18),
        ["tags"] = _.In(new[] { "vip", "new" }),
    })
    .Get();

var _ = db.Command;

// 字段：Set / Remove / Inc / Mul / Min / Max / Rename / Bit
// 数组：Push / Pop / Shift / Unshift / Pull / PullAll / AddToSet
await db.Collection("posts").Doc("id-1").Update(new Dictionary<string, object?>
{
    ["views"] = _.Inc(1),
    ["tags"] = _.Push("hot"),
});

数据模型

数据模型通过 app.Models 访问。可以使用索引器 app.Models["modelName"] 或 app.Models.Model("modelName") 获取绑定到指定模型的操作句柄（CloudBaseModel），也可以直接调用 app.Models 上带 modelName 参数的方法。

var models = app.Models;
var userModel = models["user"];   // 绑定句柄，方法无需再传 modelName

GetByIdAsync

Task<ModelFindResponse> models.GetByIdAsync(string modelName, string recordId)
// 或使用绑定句柄
Task<ModelFindResponse> model.GetByIdAsync(string recordId)

根据记录 ID 获取单条记录。

参数

modelName

string

模型（数据表）名称（使用绑定句柄时无需传入）

recordId

string

记录 ID

Task

ModelFindResponse

示例

按 ID 查询

var result = await app.Models.GetByIdAsync("user", "record-id-123");

if (result.IsSuccess)
{
    Console.WriteLine($"记录: {result.Data}");
}

GetAsync

Task<ModelFindResponse> models.GetAsync(string modelName, Dictionary<string, object?>? filter = null, Dictionary<string, object?>? select = null)

根据过滤条件获取单条记录。

参数

modelName

string

模型名称

filter

Dictionary<string, object?>?

过滤条件

select

Dictionary<string, object?>?

选择返回的字段

Task

ModelFindResponse

示例

条件查询单条

var result = await app.Models.GetAsync(
    "user",
    filter: new Dictionary<string, object?>
    {
        ["where"] = new Dictionary<string, object?>
        {
            ["email"] = new Dictionary<string, object?> { ["$eq"] = "user@example.com" }
        }
    }
);

if (result.IsSuccess)
{
    Console.WriteLine($"记录: {result.Data}");
}

ListAsync

Task<ModelFindManyResponse> models.ListAsync(
    string modelName,
    Dictionary<string, object?>? filter = null,
    Dictionary<string, object?>? select = null,
    int? pageSize = null,
    int? pageNumber = null,
    bool? getCount = null,
    List<Dictionary<string, string>>? orderBy = null)

分页查询多条记录。

参数

modelName

string

模型名称

filter

Dictionary<string, object?>?

过滤条件

select

Dictionary<string, object?>?

选择返回的字段

pageSize

int?

每页数量

pageNumber

int?

页码

getCount

bool?

是否返回总数

orderBy

List<Dictionary<string, string>>?

排序规则

Task

ModelFindManyResponse

示例

分页查询

var result = await app.Models.ListAsync(
    "user",
    filter: new Dictionary<string, object?>
    {
        ["where"] = new Dictionary<string, object?>
        {
            ["status"] = new Dictionary<string, object?> { ["$eq"] = "active" }
        }
    },
    pageSize: 10,
    pageNumber: 1,
    getCount: true,
    orderBy: new List<Dictionary<string, string>>
    {
        new() { ["createdAt"] = "desc" }
    }
);

if (result.IsSuccess)
{
    Console.WriteLine($"记录列表: {result.Data}");
}

ListSimpleAsync

Task<ModelFindManyResponse> models.ListSimpleAsync(string modelName, int? pageSize = null, int? pageNumber = null, bool? getCount = null)

分页查询多条记录的简化版本（无过滤 / 排序）。

参数

modelName

string

模型名称

pageSize

int?

每页数量

pageNumber

int?

页码

getCount

bool?

是否返回总数

Task

ModelFindManyResponse

示例

简单分页查询

var result = await app.Models.ListSimpleAsync("user", pageSize: 20, pageNumber: 1, getCount: true);

if (result.IsSuccess)
{
    Console.WriteLine($"记录列表: {result.Data}");
}

CreateAsync

Task<ModelCreateResponse> models.CreateAsync(string modelName, Dictionary<string, object?> data)

创建单条记录。

参数

modelName

string

模型名称

data

Dictionary<string, object?>

记录数据

Task

ModelCreateResponse

示例

创建记录

var result = await app.Models.CreateAsync("user", new Dictionary<string, object?>
{
    ["name"] = "张三",
    ["email"] = "zhangsan@example.com",
});

if (result.IsSuccess)
{
    Console.WriteLine($"创建成功: {result.Data}");
}

CreateManyAsync

Task<ModelCreateManyResponse> models.CreateManyAsync(string modelName, List<Dictionary<string, object?>> data)

批量创建多条记录。

参数

modelName

string

模型名称

data

List<Dictionary<string, object?>>

记录数据列表

Task

ModelCreateManyResponse

示例

批量创建

var result = await app.Models.CreateManyAsync("user", new List<Dictionary<string, object?>>
{
    new() { ["name"] = "张三" },
    new() { ["name"] = "李四" },
});

if (result.IsSuccess)
{
    Console.WriteLine($"批量创建成功: {result.Data}");
}

UpdateAsync

Task<ModelUpdateDeleteResponse> models.UpdateAsync(string modelName, Dictionary<string, object?> filter, Dictionary<string, object?> data)

更新符合条件的单条记录。

参数

modelName

string

模型名称

filter

Dictionary<string, object?>

过滤条件

data

Dictionary<string, object?>

更新数据

Task

ModelUpdateDeleteResponse

示例

更新记录

var result = await app.Models.UpdateAsync(
    "user",
    filter: new Dictionary<string, object?>
    {
        ["where"] = new Dictionary<string, object?>
        {
            ["_id"] = new Dictionary<string, object?> { ["$eq"] = "record-id-123" }
        }
    },
    data: new Dictionary<string, object?> { ["name"] = "张三三" }
);

if (result.IsSuccess)
{
    Console.WriteLine($"更新成功: {result.Data}");
}

UpdateManyAsync

Task<ModelUpdateDeleteManyResponse> models.UpdateManyAsync(string modelName, Dictionary<string, object?> filter, Dictionary<string, object?> data)

批量更新符合条件的多条记录。

参数

modelName

string

模型名称

filter

Dictionary<string, object?>

过滤条件

data

Dictionary<string, object?>

更新数据

Task

ModelUpdateDeleteManyResponse

示例

批量更新

var result = await app.Models.UpdateManyAsync(
    "user",
    filter: new Dictionary<string, object?>
    {
        ["where"] = new Dictionary<string, object?>
        {
            ["status"] = new Dictionary<string, object?> { ["$eq"] = "inactive" }
        }
    },
    data: new Dictionary<string, object?> { ["status"] = "active" }
);

if (result.IsSuccess)
{
    Console.WriteLine($"批量更新成功: {result.Data}");
}

UpsertAsync

Task<ModelUpsertResponse> models.UpsertAsync(
    string modelName,
    Dictionary<string, object?> filter,
    Dictionary<string, object?>? create = null,
    Dictionary<string, object?>? update = null)

根据过滤条件更新记录，不存在时则创建。

参数

modelName

string

模型名称

filter

Dictionary<string, object?>

过滤条件

create

Dictionary<string, object?>?

记录不存在时创建的数据

update

Dictionary<string, object?>?

记录存在时更新的数据

Task

ModelUpsertResponse

示例

Upsert 记录

var result = await app.Models.UpsertAsync(
    "user",
    filter: new Dictionary<string, object?>
    {
        ["where"] = new Dictionary<string, object?>
        {
            ["email"] = new Dictionary<string, object?> { ["$eq"] = "user@example.com" }
        }
    },
    create: new Dictionary<string, object?> { ["email"] = "user@example.com", ["name"] = "新用户" },
    update: new Dictionary<string, object?> { ["name"] = "更新用户" }
);

if (result.IsSuccess)
{
    Console.WriteLine($"Upsert 成功: {result.Data}");
}

DeleteByIdAsync

Task<ModelUpdateDeleteResponse> models.DeleteByIdAsync(string modelName, string recordId)

根据记录 ID 删除单条记录。

参数

modelName

string

模型名称

recordId

string

记录 ID

Task

ModelUpdateDeleteResponse

示例

按 ID 删除

var result = await app.Models.DeleteByIdAsync("user", "record-id-123");

if (result.IsSuccess)
{
    Console.WriteLine("删除成功");
}

DeleteRecordAsync

Task<ModelUpdateDeleteResponse> models.DeleteRecordAsync(string modelName, Dictionary<string, object?> filter)

删除符合条件的单条记录（对应绑定句柄的 DeleteAsync）。

参数

modelName

string

模型名称

filter

Dictionary<string, object?>

过滤条件

Task

ModelUpdateDeleteResponse

示例

条件删除单条

var result = await app.Models.DeleteRecordAsync(
    "user",
    filter: new Dictionary<string, object?>
    {
        ["where"] = new Dictionary<string, object?>
        {
            ["email"] = new Dictionary<string, object?> { ["$eq"] = "user@example.com" }
        }
    }
);

if (result.IsSuccess)
{
    Console.WriteLine("删除成功");
}

DeleteManyAsync

Task<ModelUpdateDeleteManyResponse> models.DeleteManyAsync(string modelName, Dictionary<string, object?> filter)

批量删除符合条件的多条记录。

参数

modelName

string

模型名称

filter

Dictionary<string, object?>

过滤条件

Task

ModelUpdateDeleteManyResponse

示例

批量删除

var result = await app.Models.DeleteManyAsync(
    "user",
    filter: new Dictionary<string, object?>
    {
        ["where"] = new Dictionary<string, object?>
        {
            ["status"] = new Dictionary<string, object?> { ["$eq"] = "deleted" }
        }
    }
);

if (result.IsSuccess)
{
    Console.WriteLine($"批量删除成功: {result.Data}");
}

MysqlCommandAsync

Task<ModelMysqlCommandResponse> models.MysqlCommandAsync(
    string sqlTemplate,
    List<ModelMysqlParameter>? parameter = null,
    ModelMysqlConfig? config = null)

通过数据模型执行 MySQL 命令（参数化 SQL 模板）。

参数

sqlTemplate

string

参数化 SQL 模板

parameter

List<ModelMysqlParameter>?

SQL 参数列表

config

ModelMysqlConfig?

执行配置

Task

ModelMysqlCommandResponse

示例

执行 SQL 命令

var result = await app.Models.MysqlCommandAsync(
    "SELECT * FROM user WHERE age > ?",
    parameter: new List<ModelMysqlParameter>
    {
        new() { Value = 18 }
    }
);

if (result.IsSuccess)
{
    Console.WriteLine($"查询结果: {result.Data}");
}

数据源查询

GetAggregateDataSourceListAsync

Task<AggregateDataSourceListResponse> models.GetAggregateDataSourceListAsync(
    int pageSize,
    string? envId = null,
    int? pageIndex = null,
    int? queryAll = null,
    List<string>? dataSourceIds = null,
    List<string>? dataSourceNames = null,
    string? dataSourceType = null,
    List<string>? viewIds = null,
    List<string>? appIds = null,
    int? appLinkStatus = null,
    int? queryBindToApp = null,
    int? queryConnector = null,
    List<string>? channelList = null,
    bool? queryDataSourceRelationList = null,
    string? dbInstanceType = null,
    List<string>? databaseTableNames = null,
    bool? querySystemModel = null)

根据条件查询数据源聚合列表。envId 可选，默认使用初始化时的环境 ID。

参数

pageSize

int

每页条数

envId

string?

环境 ID（可选，默认使用初始化时的 env）

pageIndex

int?

页码

queryAll

int?

是否查询全部（0 或 1）

dataSourceIds

List<string>?

数据源 ID 列表

dataSourceNames

List<string>?

数据源名称列表

dataSourceType

string?

数据源类型

querySystemModel

bool?

是否查询系统模型

Task

AggregateDataSourceListResponse

示例

示例

var result = await app.Models.GetAggregateDataSourceListAsync(
    pageSize: 10,
    pageIndex: 0
);

if (result.IsSuccess)
{
    Console.WriteLine($"总数: {result.Count}");
}

GetDataSourceAggregateDetailAsync

Task<DataSourceAggregateDetailResponse> models.GetDataSourceAggregateDetailAsync(
    string? datasourceId = null,
    string? dataSourceName = null,
    string? viewId = null,
    int? queryPublish = null,
    bool? queryModelRelation = null,
    string? dbInstanceType = null,
    string? databaseTableName = null)

查询数据源聚合详情。

参数

datasourceId

string?

数据源 ID（与 dataSourceName 二选一）

dataSourceName

string?

数据源名称

queryModelRelation

bool?

是否查询模型关联

Task

DataSourceAggregateDetailResponse

示例

示例

var result = await app.Models.GetDataSourceAggregateDetailAsync(
    dataSourceName: "user"
);

if (result.IsSuccess)
{
    Console.WriteLine($"详情: {result}");
}

GetDataSourceByTableNameAsync

Task<DataSourceByTableNameResponse> models.GetDataSourceByTableNameAsync(List<string> tableNames)

根据数据库表名列表查询对应的数据源。

参数

tableNames

List<string>

数据库表名列表

Task

DataSourceByTableNameResponse

示例

示例

var result = await app.Models.GetDataSourceByTableNameAsync(
    new List<string> { "user_table" }
);

if (result.IsSuccess)
{
    Console.WriteLine($"数据源: {result}");
}

GetBasicDataSourceListAsync

Task<BasicDataSourceListResponse> models.GetBasicDataSourceListAsync(
    List<string>? idList = null,
    List<string>? nameList = null,
    int? pageNum = null,
    int? pageSize = null,
    bool? queryAll = null,
    List<DataSourceQueryFilter>? queryFilterList = null,
    bool? onlyFlexDb = null)

根据条件查询基础数据源信息列表。

参数

idList

List<string>?

数据源 ID 列表

nameList

List<string>?

数据源名称列表

pageNum

int?

页码

pageSize

int?

每页条数

queryAll

bool?

是否查询全部

queryFilterList

List<DataSourceQueryFilter>?

查询过滤条件列表

onlyFlexDb

bool?

是否仅查询柔性数据库

Task

BasicDataSourceListResponse

示例

示例

var result = await app.Models.GetBasicDataSourceListAsync(pageNum: 1, pageSize: 10);

if (result.IsSuccess)
{
    Console.WriteLine($"列表: {result}");
}

GetBasicDataSourceAsync

Task<BasicDataSourceResponse> models.GetBasicDataSourceAsync(
    string? datasourceId = null,
    string? dataSourceName = null,
    string? viewId = null,
    int? queryPublish = null,
    bool? queryModelRelation = null,
    string? dbInstanceType = null,
    string? databaseTableName = null)

根据条件查询单个基础数据源信息。

参数

datasourceId

string?

数据源 ID（与 dataSourceName 二选一）

dataSourceName

string?

数据源名称

viewId

string?

视图 ID

queryModelRelation

bool?

是否查询模型关联

Task

BasicDataSourceResponse

示例

示例

var result = await app.Models.GetBasicDataSourceAsync(dataSourceName: "user");

if (result.IsSuccess)
{
    Console.WriteLine($"数据源: {result}");
}

GetSchemaListAsync

Task<DataSourceSchemaListResponse> models.GetSchemaListAsync(List<string>? dataSourceNameList = null)

查询环境下所有数据源 Schema，可按数据源名称列表过滤。

参数

dataSourceNameList

List<string>?

数据源名称列表（可选，为空则查询全部）

Task

DataSourceSchemaListResponse

示例

示例

var result = await app.Models.GetSchemaListAsync();

if (result.IsSuccess)
{
    Console.WriteLine($"Schema 列表: {result}");
}

GetTableNameAsync

Task<DataSourceTableNameResponse> models.GetTableNameAsync(string? dataSourceName = null)

根据数据源名称查询对应的数据库表名。

参数

dataSourceName

string?

数据源名称

Task

DataSourceTableNameResponse

示例

示例

var result = await app.Models.GetTableNameAsync("user");

if (result.IsSuccess)
{
    Console.WriteLine($"表名: {result}");
}

MySQL 数据库

MySQL RESTful 数据库操作通过 app.MySql 访问，提供两种风格：

扁平方法：QueryAsync、InsertAsync、UpdateAsync、DeleteAsync、CountAsync，一次调用传入表名与选项。过滤条件运算符支持：eq、neq、gt、gte、lt、lte、like、in、is。
链式查询构建器：app.MySql.From(table)....，PostgREST 风格，可读性更好，支持直接 await。

QueryAsync

Task<MySqlResponse> mysql.QueryAsync(
    string table,
    string? schema = null,
    string? instance = null,
    MySqlQueryOptions? options = null)

查询 MySQL 表数据。

参数

table

string

表名

schema

string?

Schema 名称

instance

string?

实例标识

options

MySqlQueryOptions?

查询选项（Select/Limit/Offset/Order/Filters/WithCount）

Task

MySqlResponse

示例

查询

var result = await app.MySql.QueryAsync(
    "users",
    options: new MySqlQueryOptions
    {
        Select = "id,name,email",
        Limit = 10,
        Filters = new Dictionary<string, string> { ["age"] = "gte.18" },
        WithCount = true
    }
);

if (result.IsSuccess)
{
    Console.WriteLine($"数据: {result.Data}, 总数: {result.Total}");
}

InsertAsync

Task<MySqlWriteResponse> mysql.InsertAsync(
    string table,
    object data,
    string? schema = null,
    string? instance = null,
    bool upsert = false,
    string? onConflict = null)

向 MySQL 表插入数据，可选 upsert。

参数

table

string

表名

data

object

要插入的数据（单条对象或数组）

upsert

bool

是否为 upsert，默认 false

onConflict

string?

冲突判定字段（upsert 时）

Task

MySqlWriteResponse

示例

插入

var result = await app.MySql.InsertAsync("users", new
{
    name = "张三",
    email = "zhangsan@example.com",
    age = 25
});

if (result.IsSuccess)
{
    Console.WriteLine($"插入成功: {result.Data}");
}

UpdateAsync (MySQL)

Task<MySqlWriteResponse> mysql.UpdateAsync(
    string table,
    Dictionary<string, object?> data,
    Dictionary<string, string> filters,
    string? schema = null,
    string? instance = null)

更新 MySQL 表中符合条件的数据。

参数

table

string

表名

data

Dictionary<string, object?>

更新的字段与值

filters

Dictionary<string, string>

过滤条件，值格式如 eq.value

Task

MySqlWriteResponse

示例

更新

var result = await app.MySql.UpdateAsync(
    "users",
    data: new Dictionary<string, object?> { ["name"] = "李四" },
    filters: new Dictionary<string, string> { ["id"] = "eq.1" }
);

if (result.IsSuccess)
{
    Console.WriteLine($"更新成功: {result.Data}");
}

DeleteAsync (MySQL)

Task<MySqlWriteResponse> mysql.DeleteAsync(
    string table,
    Dictionary<string, string> filters,
    string? schema = null,
    string? instance = null)

删除 MySQL 表中符合条件的数据。

参数

table

string

表名

filters

Dictionary<string, string>

过滤条件，值格式如 eq.value

Task

MySqlWriteResponse

示例

删除

var result = await app.MySql.DeleteAsync(
    "users",
    filters: new Dictionary<string, string> { ["id"] = "eq.1" }
);

if (result.IsSuccess)
{
    Console.WriteLine("删除成功");
}

CountAsync

Task<MySqlCountResponse> mysql.CountAsync(
    string table,
    Dictionary<string, string>? filters = null,
    string? schema = null,
    string? instance = null)

统计 MySQL 表中符合条件的记录数。

参数

table

string

表名

filters

Dictionary<string, string>?

过滤条件，值格式如 eq.value

Task

MySqlCountResponse

示例

统计

var result = await app.MySql.CountAsync(
    "users",
    filters: new Dictionary<string, string> { ["age"] = "gte.18" }
);

if (result.IsSuccess)
{
    Console.WriteLine($"记录数: {result.Count}");
}

链式查询构建器

除上述扁平方法外，app.MySql 还提供 PostgREST 风格的链式查询构建器，写法更贴近 SQL、可读性更好，并支持直接 await（无需显式调用 ExecuteAsync）。

// 入口一：默认实例/数据库
app.MySql.From("articles")

// 入口二：指定实例 / 数据库
app.MySql.Rdb(instance: "inst-xxx", database: "mydb").From("articles")

From(table) / Rdb(instance, database).From(table)：选择数据表，返回 MySqlQueryBuilder。
操作：Select、Insert、Update、Upsert、Delete。
过滤算子：Eq、Neq、Gt、Gte、Lt、Lte、Like、Is、In、Match、Not、Or、Filter。
修饰符：Order、Limit、Range、Single、MaybeSingle。
执行：ExecuteAsync()，或直接 await 构建器（内部通过 GetAwaiter() 支持）。

tip

Update 与 Delete 必须至少带一个过滤条件（WHERE），否则会直接返回 BadApiRequest 错误，以避免全表误操作。

// 等价于 SELECT id,title FROM articles WHERE views > 100 ORDER BY views DESC LIMIT 10
var res = await app.MySql
    .From("articles")
    .Select("id,title,views")
    .Gt("views", 100)
    .Order("views", ascending: false)
    .Limit(10);

if (res.IsSuccess)
{
    foreach (var row in res.Data)
    {
        Console.WriteLine($"{row["id"]}: {row["title"]}");
    }
    Console.WriteLine($"总数: {res.Total}");
}

// 插入并返回受影响的行（追加 .Select() 即请求 return=representation）
var res = await app.MySql
    .From("articles")
    .Insert(new { title = "Hello", views = 0 })
    .Select();

// 批量插入：传数组
var batch = await app.MySql
    .From("articles")
    .Insert(new[]
    {
        new { title = "A" },
        new { title = "B" },
    });

// 更新（必须带过滤条件）
var upd = await app.MySql
    .From("articles")
    .Update(new { title = "New Title" })
    .Eq("id", 1);

// 删除（必须带过滤条件）
var del = await app.MySql
    .From("articles")
    .Delete()
    .In("id", new[] { 1, 2, 3 });

var res = await app.MySql
    .From("articles")
    .Upsert(
        new { id = 1, title = "Upserted" },
        new MySqlUpsertOptions { OnConflict = "id" } // 冲突字段（唯一索引/主键）
    );

// 恰好一行（Single）或零/一行（MaybeSingle）
var one = await app.MySql
    .From("articles")
    .Select()
    .Eq("id", 1)
    .Single();

// 区间分页：从第 0 条到第 9 条（含边界），等价 LIMIT 10 OFFSET 0
var page = await app.MySql
    .From("articles")
    .Select()
    .Order("id")
    .Range(0, 9);

// or：filters 使用原始 MySQL 语法
var res = await app.MySql
    .From("articles")
    .Select()
    .Or("views.gt.100,title.like.*hot*");

// not：Not(column, operator, value)
var res2 = await app.MySql
    .From("articles")
    .Select()
    .Not("title", "is", null);

// match：多列等值匹配
var res3 = await app.MySql
    .From("articles")
    .Select()
    .Match(new Dictionary<string, object?> { ["author"] = "alice", ["status"] = "published" });

过滤算子对照表

方法	说明	示例
`Eq(col, v)`	等于	`.Eq("id", 1)`
`Neq(col, v)`	不等于	`.Neq("status", "draft")`
`Gt / Gte / Lt / Lte`	大于 / 大于等于 / 小于 / 小于等于	`.Gt("views", 100)`
`Like(col, pattern)`	模糊匹配，`%` 通配	`.Like("title", "%hot%")`
`Is(col, v)`	判空 / 布尔判定	`.Is("title", null)`
`In(col, values)`	包含于数组	`.In("id", new[] {1,2,3})`
`Match(dict)`	多列等值匹配	`.Match(new Dictionary<string, object?> {...})`
`Not(col, op, v)`	取反过滤	`.Not("title", "is", null)`
`Or(filters)`	逻辑或（原始语法）	`.Or("id.eq.2,title.eq.x")`
`Filter(col, op, v)`	通用过滤（原始语法）	`.Filter("views", "gte", 10)`

云函数

云函数通过顶层的 app.CallFunctionAsync 调用（推荐）。若需分别指定调用底层通道，也可使用 app.Functions 上的 CallRealFunctionAsync（普通云函数）与 CallCloudRunFunctionAsync（函数型云托管）。

CallFunctionAsync

Task<FunctionResponse> app.CallFunctionAsync(
    string name,
    FunctionType type = FunctionType.Function,
    IDictionary<string, object?>? data = null,
    HttpMethod method = HttpMethod.Post,
    string path = "/",
    IDictionary<string, string>? header = null,
    bool parse = true,
    CancellationToken cancellationToken = default)

调用云函数或函数型云托管。通过 type 指定调用类型（FunctionType.Function 或 FunctionType.CloudRun）。

参数

name

string

云函数名称

type

FunctionType

调用类型：Function（云函数，默认）或 CloudRun（函数型云托管）

data

IDictionary<string, object?>?

传递给云函数的参数

method

HttpMethod

HTTP 方法，默认 POST

path

string

请求路径，默认 /

header

IDictionary<string, string>?

自定义请求头

parse

bool

是否解析返回结果，默认 true

Task

FunctionResponse

示例

调用云函数
调用函数型云托管

var result = await app.CallFunctionAsync(
    name: "hello",
    data: new Dictionary<string, object?> { ["name"] = "CloudBase" }
);

if (result.IsSuccess)
{
    Console.WriteLine($"返回结果: {result.Result}");
}
else
{
    Console.WriteLine($"调用失败: {result.Message}");
}

var result = await app.CallFunctionAsync(
    name: "my-cloudrun-func",
    type: FunctionType.CloudRun,
    data: new Dictionary<string, object?> { ["key"] = "value" }
);

if (result.IsSuccess)
{
    Console.WriteLine($"返回结果: {result.Result}");
}

CallRealFunctionAsync

Task<FunctionResponse> app.Functions.CallRealFunctionAsync(
    string name,
    IDictionary<string, object?>? data = null,
    bool parse = true,
    CancellationToken cancellationToken = default)

直接调用普通云函数（底层通道），等价于 CallFunctionAsync 且 type 为 Function。

参数

name

string

云函数名称

data

IDictionary<string, object?>?

传递给云函数的参数

parse

bool

是否解析返回结果，默认 true

Task

FunctionResponse

示例

调用普通云函数

var result = await app.Functions.CallRealFunctionAsync(
    "hello",
    new Dictionary<string, object?> { ["name"] = "CloudBase" }
);

if (result.IsSuccess)
{
    Console.WriteLine($"返回结果: {result.Result}");
}

CallCloudRunFunctionAsync

Task<FunctionResponse> app.Functions.CallCloudRunFunctionAsync(
    string name,
    HttpMethod method = HttpMethod.Post,
    string path = "/",
    IDictionary<string, string>? header = null,
    IDictionary<string, object?>? data = null,
    CancellationToken cancellationToken = default)

调用函数型云托管（底层通道），等价于 CallFunctionAsync 且 type 为 CloudRun。

参数

name

string

函数型云托管服务名称

method

HttpMethod

HTTP 方法，默认 POST

path

string

请求路径，默认 /

header

IDictionary<string, string>?

自定义请求头

data

IDictionary<string, object?>?

请求数据

Task

FunctionResponse

示例

调用函数型云托管

var result = await app.Functions.CallCloudRunFunctionAsync(
    "my-cloudrun-func",
    data: new Dictionary<string, object?> { ["key"] = "value" }
);

if (result.IsSuccess)
{
    Console.WriteLine($"返回结果: {result.Result}");
}

云托管

CallContainerAsync

Task<CloudRunResponse> app.CallContainerAsync(
    string name,
    HttpMethod method = HttpMethod.Get,
    string path = "/",
    IDictionary<string, string>? header = null,
    IDictionary<string, object?>? data = null,
    CancellationToken cancellationToken = default)

调用云托管容器服务。

参数

name

string

云托管服务名称

method

HttpMethod

HTTP 方法，默认 GET

path

string

请求路径，默认 /

header

IDictionary<string, string>?

自定义请求头

data

IDictionary<string, object?>?

请求数据

Task

CloudRunResponse

示例

调用云托管

var result = await app.CallContainerAsync(
    name: "my-service",
    method: HttpMethod.Post,
    path: "/api/data",
    data: new Dictionary<string, object?> { ["key"] = "value" }
);

Console.WriteLine($"返回结果: {result.Result}");

APIs

APIs 通过 app.Apis 访问。使用索引器 app.Apis["apiName"] 或 app.Apis.Api("apiName") 获取方法代理（ApiMethodProxy），然后按 HTTP 方法调用 GetAsync、PostAsync、PutAsync、DeleteAsync、HeadAsync、OptionsAsync、PatchAsync，或使用通用的 RequestAsync(method, ...)。也可直接调用 app.Apis.CallApiAsync(CallApiOptions)。app.Apis.GatewayOrigin 可用于读取/设置网关来源。

Apis[name]

ApiMethodProxy app.Apis[string apiName]

获取指定 API 的方法代理 ApiMethodProxy。app.Apis.Api("apiName") 与索引器 app.Apis["apiName"] 等价。

ApiMethodProxy 提供以下方法，均返回 Task<ApiResponse>：

方法	HTTP	签名（省略 `cancellationToken`）
`GetAsync`	GET	`(string path = "", Dictionary<string,string>? headers = null, string? token = null)`
`PostAsync`	POST	`(Dictionary<string,object?>? body = null, string path = "", Dictionary<string,string>? headers = null, string? token = null)`
`PutAsync`	PUT	同 `PostAsync`
`PatchAsync`	PATCH	同 `PostAsync`
`DeleteAsync`	DELETE	同 `PostAsync`
`HeadAsync`	HEAD	同 `GetAsync`
`OptionsAsync`	OPTIONS	同 `GetAsync`
`RequestAsync`	任意	`(string method, Dictionary<string,object?>? body = null, string path = "", ...)`

参数

apiName

string

API 名称

Return

ApiMethodProxy

API 方法代理，提供 GetAsync/PostAsync/PutAsync/PatchAsync/DeleteAsync/HeadAsync/OptionsAsync/RequestAsync 等方法

示例

GET 请求
POST 请求
PUT / PATCH / DELETE
HEAD / OPTIONS
通用请求 / 自定义 Token

var result = await app.Apis["myApi"].GetAsync(path: "/users");

if (result.IsSuccess)
{
    Console.WriteLine($"数据: {result.Data}");
}

var result = await app.Apis["myApi"].PostAsync(
    body: new Dictionary<string, object?> { ["name"] = "张三" },
    path: "/users"
);

if (result.IsSuccess)
{
    Console.WriteLine($"创建结果: {result.Data}");
}

// 更新（整体）
await app.Apis["myApi"].PutAsync(
    body: new Dictionary<string, object?> { ["age"] = 26 },
    path: "/users/1"
);

// 更新（部分）
await app.Apis["myApi"].PatchAsync(
    body: new Dictionary<string, object?> { ["age"] = 27 },
    path: "/users/1"
);

// 删除
await app.Apis["myApi"].DeleteAsync(path: "/users/1");

// HEAD：仅探测，无响应体
await app.Apis["myApi"].HeadAsync(path: "/users");

// OPTIONS
await app.Apis["myApi"].OptionsAsync(path: "/users");

// 通用请求：method 支持 GET/POST/PUT/DELETE/HEAD/OPTIONS/PATCH（非法值会抛 ArgumentException）
var result = await app.Apis["myApi"].RequestAsync(
    "PUT",
    body: new Dictionary<string, object?> { ["age"] = 26 },
    path: "/users/1",
    headers: new Dictionary<string, string> { ["X-Trace"] = "1" },
    token: "custom-bearer-token"
);

Api(name)

ApiMethodProxy app.Apis.Api(string apiName)

以方法调用的方式获取 API 方法代理，与索引器 app.Apis[apiName] 完全等价。

var result = await app.Apis.Api("myApi").GetAsync(path: "/users");

GatewayOrigin

string? app.Apis.GatewayOrigin { get; set; }

自定义网关地址（可选），用于覆盖默认的 API 网关地址。

app.Apis.GatewayOrigin = "https://your-gateway.example.com";
var result = await app.Apis["myApi"].GetAsync(path: "/users");

CallApiAsync

Task<ApiResponse> app.Apis.CallApiAsync(
    CallApiOptions options,
    CancellationToken cancellationToken = default)

以选项对象的方式直接调用 API，ApiMethodProxy 的各 HTTP 方法均是对此方法的封装。

参数

options

CallApiOptions

调用选项（Name/Method/Path/Body/Headers/Token 等）

Task

ApiResponse

示例

调用 API

var result = await app.Apis.CallApiAsync(new CallApiOptions("myApi")
{
    Method = "POST",
    Path = "/users",
    Body = new Dictionary<string, object?> { ["name"] = "张三" }
});

if (result.IsSuccess)
{
    Console.WriteLine($"数据: {result.Data}");
}

云存储

云存储通过 app.Storage 访问。使用 app.Storage.From() 获取文件操作句柄（CloudBaseStorageFileApi），再进行上传、下载、删除、复制、移动等操作。所有方法返回 StorageResponse<T>（含 Data、Error、IsSuccess）。

var storage = app.Storage.From();

错误处理模式（ThrowOnError）：默认情况下各操作失败时通过返回值的 Error 字段报告错误。若调用 ThrowOnError()，则改为在失败时抛出 StorageException（更贴合异常式错误处理），该方法返回当前实例以支持链式调用：

// 失败时抛出 StorageException，而非返回 Error
var storage = app.Storage.From().ThrowOnError();

try
{
    var res = await storage.UploadAsync("a.png", bytes);
}
catch (StorageException ex)
{
    Console.WriteLine($"上传失败: {ex.Message}");
}

UploadAsync

Task<StorageResponse<StorageUploadResult>> storage.UploadAsync(
    string path,
    byte[] fileData,
    StorageUploadOptions? options = null)

上传文件到云存储。内部通过获取上传信息并直传至 COS 完成，返回文件 ID 与路径。

参数

path

string

云存储上的文件路径

fileData

byte[]

文件二进制数据

options

StorageUploadOptions?

上传选项（CacheControl/ContentType/Metadata/Upsert）

Task

StorageResponse<StorageUploadResult>

示例

上传文件

var fileData = await File.ReadAllBytesAsync("local/photo.png");

var result = await app.Storage.From().UploadAsync(
    "images/photo.png",
    fileData,
    new StorageUploadOptions
    {
        ContentType = "image/png",
        Upsert = true
    }
);

if (result.IsSuccess)
{
    Console.WriteLine($"上传成功: {result.Data?.Id}");
}
else
{
    Console.WriteLine($"上传失败: {result.Error?.Message}");
}

UpdateAsync (Storage)

Task<StorageResponse<StorageUploadResult>> storage.UpdateAsync(
    string path,
    byte[] fileData,
    StorageUploadOptions? options = null)

覆盖上传（更新）文件，等价于 UploadAsync 且强制 Upsert = true。

参数

path

string

云存储上的文件路径

fileData

byte[]

文件二进制数据

options

StorageUploadOptions?

上传选项（内部会强制 Upsert 为 true）

Task

StorageResponse<StorageUploadResult>

示例

更新文件

var fileData = await File.ReadAllBytesAsync("local/photo.png");

var result = await app.Storage.From().UpdateAsync("images/photo.png", fileData);

if (result.IsSuccess)
{
    Console.WriteLine($"更新成功: {result.Data?.Id}");
}

GetUploadInfoAsync

Task<StorageResponse<List<StorageUploadInfo>>> storage.GetUploadInfoAsync(List<string> paths)

获取指定路径的上传信息（用于自定义直传流程）。

参数

paths

List<string>

文件路径列表

Task

StorageResponse<List<StorageUploadInfo>>

示例

获取上传信息

var result = await app.Storage.From().GetUploadInfoAsync(
    new List<string> { "images/a.png", "images/b.png" }
);

if (result.IsSuccess)
{
    Console.WriteLine($"上传信息: {result.Data}");
}

GetDownloadUrlsAsync

Task<StorageResponse<List<StorageDownloadInfo>>> storage.GetDownloadUrlsAsync(
    List<string> fileIds,
    int? expiresIn = null)

批量获取文件的下载链接。

参数

fileIds

List<string>

文件 ID 列表

expiresIn

int?

链接有效期（秒）

Task

StorageResponse<List<StorageDownloadInfo>>

示例

获取下载链接

var result = await app.Storage.From().GetDownloadUrlsAsync(
    new List<string> { "cloud://env.xxx/images/photo.png" },
    expiresIn: 3600
);

if (result.IsSuccess)
{
    Console.WriteLine($"下载链接: {result.Data}");
}

CreateSignedUrlAsync

Task<StorageResponse<string>> storage.CreateSignedUrlAsync(
    string fileId,
    int expiresIn,
    StorageSignedUrlOptions? options = null)

为单个文件创建带签名的临时访问 URL。

参数

fileId

string

文件 ID

expiresIn

int

有效期（秒）

options

StorageSignedUrlOptions?

签名 URL 选项（如图片转换）

Task

StorageResponse<string>

示例

创建签名 URL

var result = await app.Storage.From().CreateSignedUrlAsync(
    "cloud://env.xxx/images/photo.png",
    expiresIn: 3600
);

if (result.IsSuccess)
{
    Console.WriteLine($"签名 URL: {result.Data}");
}

CreateSignedUrlsAsync

Task<StorageResponse<List<StorageDownloadInfo>>> storage.CreateSignedUrlsAsync(
    List<string> fileIds,
    int expiresIn)

批量创建带签名的临时访问 URL。

参数

fileIds

List<string>

文件 ID 列表

expiresIn

int

有效期（秒）

Task

StorageResponse<List<StorageDownloadInfo>>

示例

批量创建签名 URL

var result = await app.Storage.From().CreateSignedUrlsAsync(
    new List<string> { "cloud://env.xxx/a.png", "cloud://env.xxx/b.png" },
    expiresIn: 3600
);

if (result.IsSuccess)
{
    Console.WriteLine($"签名 URL 列表: {result.Data}");
}

CreateSignedUploadUrlAsync

Task<StorageResponse<StorageUploadInfo>> storage.CreateSignedUploadUrlAsync(string path)

为指定路径创建带签名的上传信息（用于自定义直传流程）。

参数

path

string

云存储上的文件路径

Task

StorageResponse<StorageUploadInfo>

示例

创建签名上传信息

var result = await app.Storage.From().CreateSignedUploadUrlAsync("images/photo.png");

if (result.IsSuccess)
{
    Console.WriteLine($"上传信息: {result.Data}");
}

GetPublicUrlAsync

Task<StorageResponse<string>> storage.GetPublicUrlAsync(
    string pathOrFileId,
    StorageTransformOptions? options = null)

获取文件的公有访问链接，支持可选的图片转换参数。

参数

pathOrFileId

string

文件路径或文件 ID

options

StorageTransformOptions?

图片转换选项（可选）

Task

StorageResponse<string>

示例

获取公有链接

var result = await app.Storage.From().GetPublicUrlAsync("images/photo.png");

if (result.IsSuccess)
{
    Console.WriteLine($"公有链接: {result.Data}");
}

DownloadAsync

Task<StorageResponse<byte[]>> storage.DownloadAsync(
    string fileId,
    StorageTransformOptions? options = null)

下载文件内容，返回二进制数据。

参数

fileId

string

文件 ID

options

StorageTransformOptions?

图片转换选项（可选）

Task

StorageResponse<byte[]>

示例

下载文件

var result = await app.Storage.From().DownloadAsync("cloud://env.xxx/images/photo.png");

if (result.IsSuccess)
{
    await File.WriteAllBytesAsync("local/photo.png", result.Data!);
}

InfoAsync

Task<StorageResponse<StorageFileInfo>> storage.InfoAsync(string pathOrFileId)

获取文件的元信息（大小、类型等）。

参数

pathOrFileId

string

文件路径或文件 ID

Task

StorageResponse<StorageFileInfo>

示例

获取文件信息

var result = await app.Storage.From().InfoAsync("images/photo.png");

if (result.IsSuccess)
{
    Console.WriteLine($"文件信息: {result.Data}");
}

ExistsAsync

Task<StorageResponse<bool>> storage.ExistsAsync(string pathOrFileId)

判断文件是否存在。

参数

pathOrFileId

string

文件路径或文件 ID

Task

StorageResponse<bool>

示例

判断文件是否存在

var result = await app.Storage.From().ExistsAsync("images/photo.png");

if (result.IsSuccess)
{
    Console.WriteLine($"是否存在: {result.Data}");
}

RemoveAsync

Task<StorageResponse<List<StorageDeleteResult>>> storage.RemoveAsync(List<string> fileIds)

批量删除文件。

参数

fileIds

List<string>

要删除的文件 ID 列表

Task

StorageResponse<List<StorageDeleteResult>>

示例

删除文件

var result = await app.Storage.From().RemoveAsync(
    new List<string> { "cloud://env.xxx/images/photo.png" }
);

if (result.IsSuccess)
{
    Console.WriteLine("删除成功");
}

CopyAsync

Task<StorageResponse<StorageCopyResult>> storage.CopyAsync(
    string fromPath,
    string toPath,
    bool overwrite = true)

复制单个文件。

参数

fromPath

string

源文件路径

toPath

string

目标文件路径

overwrite

bool

是否覆盖，默认 true

Task

StorageResponse<StorageCopyResult>

示例

复制文件

var result = await app.Storage.From().CopyAsync(
    "images/photo.png",
    "backup/photo.png"
);

if (result.IsSuccess)
{
    Console.WriteLine("复制成功");
}

CopyBatchAsync

Task<StorageResponse<List<StorageCopyResult>>> storage.CopyBatchAsync(
    List<Dictionary<string, object?>> items)

批量复制文件。

参数

items

List<Dictionary<string, object?>>

复制项列表，每项包含源路径与目标路径

Task

StorageResponse<List<StorageCopyResult>>

示例

批量复制

var result = await app.Storage.From().CopyBatchAsync(new List<Dictionary<string, object?>>
{
    new() { ["from"] = "images/a.png", ["to"] = "backup/a.png" },
    new() { ["from"] = "images/b.png", ["to"] = "backup/b.png" },
});

if (result.IsSuccess)
{
    Console.WriteLine("批量复制成功");
}

MoveAsync

Task<StorageResponse<StorageCopyResult>> storage.MoveAsync(
    string fromPath,
    string toPath,
    bool overwrite = true)

移动（重命名）文件。

参数

fromPath

string

源文件路径

toPath

string

目标文件路径

overwrite

bool

是否覆盖，默认 true

Task

StorageResponse<StorageCopyResult>

示例

移动文件

var result = await app.Storage.From().MoveAsync(
    "images/photo.png",
    "images/renamed.png"
);

if (result.IsSuccess)
{
    Console.WriteLine("移动成功");
}

更新日志

SDK 版本号遵循语义化版本，完整变更记录见仓库 CHANGELOG.md。

1.0.0 - 2026-07-23

首个正式发布版本，覆盖云开发核心能力，并与 HTTP API 保持一致。

多目标框架：支持 net10.0（含依赖注入集成）等目标，适用于 .NET Core、控制台、服务端及 Unity 等场景。
身份认证：匿名 / 密码 / 用户名验证码 / OTP 登录、注册登出、会话与用户管理、身份源绑定、密码重置等。
图形验证码：验证码创建、验证与管理。
文档型数据库：集合与文档 CRUD、链式查询、聚合管道、事务、强类型操作。
数据模型：数据模型 CRUD 与数据源聚合查询。
MySQL 数据库：扁平方法与 PostgREST 风格链式查询构建器。
云函数 / 云托管 / APIs：调用云函数、云托管容器与 APIs 网关接口。
云存储：文件上传、下载、删除、复制、移动，支持异常式错误处理（ThrowOnError）。
依赖注入：提供 AddCloudBase 扩展方法，适配 ASP.NET Core 等场景。
Unity 支持：UPM Git URL 一步安装，自带 Unity 适配层，全平台（含 WebGL）即装即用。

安装​

示例项目​

基础使用示例​

依赖注入​

AddCloudBase​

参数

返回

示例

认证登录​

SignUpAsync​

参数

返回

示例

SignInAnonymouslyAsync​

参数

返回

示例

SignInWithPasswordAsync​

参数

返回

示例

SignInWithUsernameAsync​

参数

返回

示例

SignInWithOtpAsync​

参数

返回

示例

SignInWithOAuthAsync​

参数

返回

示例

SignInWithIdTokenAsync​

参数

返回

示例

SignInWithCustomTicketAsync​

参数

返回

示例

会话管理​

GetSessionAsync​

参数

返回

示例

RefreshSessionAsync​

参数

返回

示例

SetSessionAsync​

参数

返回

示例

SignOutAsync​

参数

返回

示例

OnAuthStateChange​

参数

返回

示例

GetClaimsAsync​

参数

返回

示例

用户管理​

GetUserAsync​

参数

返回

示例

RefreshUserAsync​

参数

返回

示例

UpdateUserAsync​

参数

返回

示例

DeleteUserAsync​

安装

示例项目

基础使用示例

依赖注入

AddCloudBase

认证登录

SignUpAsync

SignInAnonymouslyAsync

SignInWithPasswordAsync

SignInWithUsernameAsync

SignInWithOtpAsync

SignInWithOAuthAsync

SignInWithIdTokenAsync

SignInWithCustomTicketAsync

会话管理

GetSessionAsync

RefreshSessionAsync

SetSessionAsync

SignOutAsync

OnAuthStateChange

GetClaimsAsync

用户管理

GetUserAsync

RefreshUserAsync

UpdateUserAsync

DeleteUserAsync

身份源管理

GetUserIdentitiesAsync

LinkIdentityAsync

UnlinkIdentityAsync

密码管理

ResetPasswordForEmailAsync

ResetPasswordForOldAsync

ReauthenticateAsync

验证管理

GetVerificationAsync

VerifyAsync

VerifyOtpAsync

VerifyOAuthAsync

ResendAsync

GetCaptchaTokenAsync

CreateCaptchaDataAsync

VerifyCaptchaDataAsync

AppendCaptchaTokenToUrlAsync

FindCaptchaTokenAsync