DingTalkApiClient 1.0.1

DingTalkApiClient

DingTalkApiClient 是一个对接钉钉 OpenAPI 的 C# 客户端库，底层基于 WebApiClientCore 构建，以便提供强类型和声明式的接口调用体验。当前支持 net8.0、net9.0 和 net10.0。

安装

dotnet add package DingTalkApiClient

已实现的接口能力

为了更好地组织和使用，本库按照钉钉 API 的分类进行了整理。以下是目前支持的所有接口能力列表：

• auth：IAccessTokenApi、ISsoAuthApi
• OA审批：IWorkflowApi
• teambition项目管理：ITeambitionProjectApi、ITeambitionWorkspaceTopApi
• 上下游和上下级：ICooperateCorpsApi、IUnionCooperateApi
• 专属开放：IExclusiveOpenApi、IExclusiveOpenServiceAccountApi
• 事件订阅：IEventSubscriptionApi
• 互动卡片：ICardInstancesApi、IInteractiveCardApi
• 企业文化：IOrgCultureApi
• 公告：IBlackboardApi
• 即时通讯：IChatApi、ICorpConversationApi、IRobotApi、ISceneGroupApi、IInterconnectionsApi
• 宜搭应用开发：IYidaApi
• 客户管理CRM：ICrmApi
• 客服：IInterconnectionsApi
• 工作台：IWorkbenchApi
• 应用管理：IApplicationManagementApi
• 待办任务：ITodoApi
• 文档文件：IDocumentFileApi
• 日志：IReportApi
• 日程：ICalendarApi
• 智能人事：IHumanResourcesApi
• 智能填表：ISmartFillApi
• 智能硬件：ISmartDeviceApi
• 服务窗：IServiceWindowApi
• 生态开放：IEcosystemApi、IEcosystemTopApi
• 签到：ICheckinApi
• 考勤：IAttendanceApprovalsApi、IAttendanceGroupsApi、IAttendanceMachinesApi、IAttendanceMachinesV1Api、IAttendanceRecordsApi、IAttendanceReportsApi、IAttendanceSchedulesApi、IAttendanceSettingsApi、IAttendanceShiftsApi、IAttendanceVacationsApi
• 行业开放：IIndustryOpenApi、IIndustryOpenTopApi
• 通讯录：IAuthScopesApi、IContactSettingsApi、IContactUsersApi、IDepartmentManageApi、IEmployeeRecordsApi、IExternalContactsApi、IIndustryContactsApi、IOrgAccountsApi、IRoleManageApi、ISeniorSettingsApi、IStaffAttributesApi、IUserManageApi
• 钉工牌：IBadgeApi
• 音视频：ILiveApi、IMeetingRoomsApi、IVideoConferencesApi

配置说明与 WebApiClientCore

由于本库依赖于 WebApiClientCore，你可以利用 WebApiClientCore.Extensions.OAuths 或本库提供的扩展，在 ASP.NET Core 服务中轻松挂载并管理 Http 客户端。

1. appsettings.json 配置示例

本库会根据调用 AddDingTalk 时传入的 ProviderName，从 DingTalk:{ProviderName} 节点读取对应的密钥配置。未传入 ProviderName 时，默认注册 Internal，即读取 DingTalk:Internal。

{
  "DingTalk": {
    "EnableLogging": false,
    "Internal": {
      "ClientId": "your_client_id",
      "ClientSecret": "your_client_secret",
      "CropId": "your_crop_id"
    },
    "Corp": {
      "ClientId": "your_corp_client_id",
      "ClientSecret": "your_corp_client_secret",
      "SuiteKey": "your_suite_key",
      "SuiteSecret": "your_suite_secret",
      "AuthCorpId": "",
      "SuiteTicket": ""
    },
    "MicroApp": {
      "ClientId": "your_micro_app_client_id",
      "CropId": "your_crop_id",
      "SsoSecret": "your_sso_secret"
    }
  }
}

内置的 ProviderName 包括 Internal（内部应用）、Corp（定制应用）和 MicroApp（微应用）。例如：

builder.Services.AddDingTalk(builder.Configuration, ProviderNames.Internal, ProviderNames.Corp);

上面的代码会读取 DingTalk:Internal 和 DingTalk:Corp 两组配置，并注册对应的 AccessToken Provider。

EnableLogging 用于控制 WebApiClientCore 的异常日志是否启用。开启后，仅当响应状态码不是 200，或请求在发出/反序列化阶段发生异常时，才会记录请求头、请求体、响应头和响应体；默认建议在生产环境保持 false，排查联调问题时再打开。

机器人消息发送示例

// 发送自定义机器人文本消息 (使用工厂方法)
var robotMsg = CustomRobotMessageRequest.Create(
    RobotMsgType.Text,
    new CustomRobotMessageRequest.TextObj { Content = "您有一条新的告警消息" }
);

var response = await robotApi.SendCustomRobotMessageAsync("your_access_token", robotMsg);

// 发送群聊 Markdown 消息
var request = new SendGroupMessageRequest(
    robotCode: "your_robot_code",
    openConversationId: "cidXXXXXX",
    msgKey: "sampleMarkdown",
    msgParam: "{\"title\":\"Hello\",\"text\":\"World\"}"
);

var response = await robotApi.SendGroupMessageAsync(request);

Source Generation 与序列化说明

项目支持并使用 System.Text.Json Source Generation。所有已实现接口涉及的请求、响应模型会注册到 DingTalkJsonSerializerContext，以减少运行时反射依赖，并更好地支持 AOT、裁剪和高性能序列化场景。

针对机器人消息和工作通知，项目通过工厂模式保证了类型安全与序列化的一致性。

1. 继承自 DingTalkResult 以统一处理错误。
2. 属性使用 PascalCase 命名，并通过 [JsonPropertyName] 映射。
3. 通过 Create<TBody> 静态方法构建消息，强制校验消息体类型。

2. 依赖注入 (DI) 调用示例

在 Startup.cs 或者 Program.cs (.NET 6+) 中调用扩展方法进行依赖注入：

using DingTalkApiClient;

var builder = WebApplication.CreateBuilder(args);

// 未传入 ProviderName 时默认读取 DingTalk:Internal，并注册所有已支持的钉钉 HttpApi
builder.Services.AddDingTalk(builder.Configuration);

完成注入后，即可在任意的控制器、服务或者使用依赖注入的类中获取接口（如 ICorpConversationApi）：

using DingTalkApiClient.Apis.IM;
using DingTalkApiClient.Models.IM.CorpConversation;

public class NotificationService
{
    private readonly ICorpConversationApi _corpConversationApi;

    public NotificationService(ICorpConversationApi corpConversationApi)
    {
        _corpConversationApi = corpConversationApi;
    }

    public async Task NotifyUserAsync()
    {
        // 构建工作通知请求：使用静态泛型工厂方法 Create 确保消息类型的类型安全
        var request = new AsyncSendCorpConversationV2Request(
            AgentId: 10001,
            UserIdList: "user1,user2",
            DeptIdList: "",
            ToAllUser: false,
            Msg: CorpConversationMsgRequest.Create(
                CorpConversationMsgType.Text, 
                new CorpConversationMsgRequest.TextObj { Content = "您有一条新的提醒待查看！" }
            )
        );

        // 即可直接调用钉钉接口进行工作通知，无须手动处理 AccessToken 的获取与拼接
        var result = await _corpConversationApi.AsyncSendCorpConversationV2Async(request);
        
        if (result.IsSuccess)
        {
            Console.WriteLine($"任务创建成功！任务ID: {result.TaskId}");
        }
    }
}

如果需要使用非默认的 AccessToken Provider，可以在调用接口时指定 tokenProviderName：

var result = await _corpConversationApi.AsyncSendCorpConversationV2Async(
    request,
    tokenProviderName: ProviderNames.Corp
);