跳到主要内容

概述

NuGet Version GitHub

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 接口。
  • 云存储：文件上传、下载、删除、复制、移动等操作。
  • 更新日志：各版本变更记录。

安装​

推荐通过 NuGet 安装：

dotnet add package Tencent.CloudBase

或在 .csproj 中添加引用：

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

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

示例项目​

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

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

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

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

dotnet run --project examples/QuickStart

基础使用示例​

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 完整参数：

参数类型默认值说明
envstring必填CloudBase 环境 ID
regionstringap-shanghai地域
langstringzh-CN语言
accessKeystring?nullPublishable Key，用于匿名访问
authConfigAuthConfig?null认证配置（如 DetectSessionInUrl）
captchaConfigCaptchaConfig?null验证码配置（如 OnCaptchaRequired 回调）
storeIKeyValueStore?null键值存储实现，为 null 时使用默认文件存储；服务端多租户建议注入自定义实现
httpClientHttpClient?null自定义 HttpClient（WebGL 平台不可用）
transportIHttpTransport?null自定义 HTTP 传输层
intlboolfalse是否国际站

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

依赖注入​

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

备注

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

AddCloudBase​

IServiceCollection services.AddCloudBase(Action<CloudBaseOptions> configure)

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

参数

configure
Action<CloudBaseOptions>

配置委托

返回

IServiceCollection
IServiceCollection

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

示例

using CloudBase.DependencyInjection;

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

认证登录​

SignUpAsync​

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

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

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

参数

@params
SignUpReq

返回

Task
CloudBaseResponse<SignUpResData>

示例

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}");
}

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>

示例

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>

示例

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>

示例

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 用于后续验证。

参数

email
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>

示例

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>

示例

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

示例

// 初始化时配置人机验证回调
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

示例

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

示例

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

ClearCaptchaTokenAsync​

Task app.Captcha.ClearCaptchaTokenAsync()

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

参数

无参数

返回

Task
void

无返回值

示例

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
CloudBaseDb

文档型数据库操作入口

示例

var db = app.Database();

Collection​

CollectionReference db.Collection(string collectionName)

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

参数

collectionName
string

集合名称

返回

CollectionReference
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}");

Where​

Query query.Where(object condition)

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

参数

condition
object

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

返回

Query
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
Query

查询构建器

示例

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

Limit​

Query query.Limit(int max)

限制返回的最大记录数。

参数

max
int

最大记录数

返回

Query
Query

查询构建器

示例

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

Skip​

Query query.Skip(int offset)

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

参数

offset
int

偏移量

返回

Query
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
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

示例

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"]);
}

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
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"]);
}

OfType​

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

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

参数

无参数

返回

TypedQuery<T>
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
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?>
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
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();

数据模型​

数据模型通过 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

示例

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

示例

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

示例

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

示例

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() 支持）。
提示

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}");
}

过滤算子对照表

方法说明示例
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}");
}

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）
GetAsyncGET(string path = "", Dictionary<string,string>? headers = null, string? token = null)
PostAsyncPOST(Dictionary<string,object?>? body = null, string path = "", Dictionary<string,string>? headers = null, string? token = null)
PutAsyncPUT同 PostAsync
PatchAsyncPATCH同 PostAsync
DeleteAsyncDELETE同 PostAsync
HeadAsyncHEAD同 GetAsync
OptionsAsyncOPTIONS同 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 等方法

示例

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

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

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

示例

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>

示例

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>>

示例

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.1 - 2026-07-23​

聚焦网络可靠性与并发安全的增强版本，向后兼容 1.0.0（新增能力均为可选参数，默认行为保持不变）。

Added​

  • HTTP 自动重试（RetryOptions）：对幂等且瞬时失败的请求（网络超时、连接失败、429、5xx）执行**指数退避 + 抖动（jitter）**的自动重试。默认最多重试 2 次、基础退避 200ms、封顶 5s，并遵循服务端 Retry-After 头（429/503）；认证错误（401/token 过期）与 429 之外的 4xx 不重试。可通过 RetryOptions.Disabled 关闭或自定义各参数。
  • 客户端并发限流（ConcurrencyOptions）：以信号量限制单个客户端同时在途（in-flight）的请求数，作为客户端侧「限流阀」避免打满连接池 / socket 或压垮后端。默认不限流；可选 AcquireTimeout 让长时间拿不到额度的请求快速失败（concurrency_limit_timeout）。
  • 连接池调优工厂 HttpClientTransport.CreatePooled（仅 net）：基于 SocketsHttpHandler 预置 PooledConnectionLifetime、MaxConnectionsPerServer、PooledConnectionIdleTimeout 等参数，面向长驻进程手动持有单例的场景（使用 IHttpClientFactory 的 DI 场景无需此工厂）。
  • 异步释放 CloudBase.DisposeAsync：新增 IAsyncDisposable 支持，await using 释放时会先等待挂起的会话持久化完成再释放底层 HTTP 资源，避免进程退出丢数据。
  • 本地存储持久化错误可观测：FileKeyValueStore 新增 onPersistError 回调与 LastPersistError 属性，落盘失败不再静默丢弃，便于调用方记录日志 / 上报监控。
  • 依赖注入透传新选项：CloudBaseOptions 新增 RetryOptions 与 ConcurrencyOptions，可经 AddCloudBase 配置并透传给内部客户端。
  • 发布脚本支持版本号自动升级：scripts/publish.sh 与 scripts/publish.ps1 在打包命令后可附加 --bump major|minor|patch（PowerShell 为 -Bump）按语义化规则递增版本号，或 --set-version x.y.z（PowerShell 为 -SetVersion）显式设置版本号，脚本会先改写 CloudBase.csproj 的 <Version> 再打包并同步 UPM 包 package.json；同时新增独立的 bump 命令，仅升级版本号而不打包。
  • 测试补充：新增重试与并发（HttpRetryAndConcurrencyTests、RetryExecutorTests）、本地存储（FileKeyValueStoreTests）、版本号解析（SdkVersionTests）等单元 / 集成测试。

Changed​

  • 本地存储采用原子落盘：FileKeyValueStore 改为「写临时文件 + 原子替换」，并将「读-改-写」纳入同一把锁，避免写入中途崩溃损坏整份存储或并发写相互覆盖。
  • SdkVersion.Version 改为单一来源：运行期通过反射读取程序集的 AssemblyInformationalVersion（对应 csproj 的 <Version>），不再与 csproj 分散维护导致版本漂移。
  • 默认超时改为常量 HttpClientTransport.DefaultTimeout：消除多处硬编码的 30s 超时。

Fixed​

  • Token 刷新并发安全：将「过期判断」与「合并到刷新任务」纳入同一临界区，避免多条并发请求各自发起刷新导致一次性 refresh_token 被重复消费而第二次刷新失败。
  • 认证状态监听线程安全：NotifyListeners 在锁内取监听器快照、锁外回调，修复 Add/Remove 与遍历并发时可能抛出的 InvalidOperationException，同时避免回调中再订阅 / 退订造成的重入死锁。
  • 未知 HTTP 方法不再静默降级为 GET：HttpClientTransport 遇到不支持的方法时直接抛 ArgumentOutOfRangeException，避免难以排查的错误请求。

1.0.0 - 2026-07-23​

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

Added​

  • 多目标框架：支持 netstandard2.1 与 net10.0（后者含依赖注入集成），可用于 .NET Core、控制台、服务端及 Unity 等场景。
  • 身份认证（Auth）：匿名登录、密码登录、用户名/邮箱/手机号 + 验证码登录、OTP 登录、注册、登出、会话管理、用户信息管理、身份源绑定/解绑、密码重置/修改等完整认证能力。
  • 图形验证码（Captcha）：验证码创建、验证、管理等能力。
  • 文档型数据库（Database）：集合、文档的增删改查，链式查询、聚合管道、事务，以及强类型（Typed）操作接口。
  • 数据模型（DataModel）：数据模型 CRUD 与数据源聚合查询（列表、详情、Schema、表名）。
  • MySQL 数据库：扁平方法（QueryAsync/InsertAsync/UpdateAsync/DeleteAsync/CountAsync）与 PostgREST 风格链式查询构建器（From/Rdb + Select/Insert/Upsert/Delete + 过滤算子）。
  • 云函数（Functions）：调用云函数与函数型云托管。
  • 云托管（CloudRun）：调用云托管容器服务。
  • APIs（CallApis）：调用 APIs 网关接口，支持 GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS 及自定义网关地址。
  • 云存储（Storage）：文件上传、下载、删除、复制、移动，支持返回值式与异常式（ThrowOnError）两种错误处理模式。
  • 依赖注入：提供 AddCloudBase 扩展方法，可在 ASP.NET Core / Blazor Server / Worker 等场景注册 SDK，内部复用 IHttpClientFactory 连接池。
  • Unity 支持：通过 UPM Git URL 一步安装，自带 Unity 适配层（CloudBaseUnity、UnityKeyValueStore、UnityWebRequestTransport、UnityMainThreadDispatcher），全平台（含 WebGL）即装即用。
  • 示例项目：QuickStart（控制台快速上手）、TerminalUI（交互式终端测试工具）、UnityGame（Unity 游戏工程）。