简介这份资源面向从事中控考勤机二次开发的程序员尤其是使用C#或VB.NET进行设备集成与考勤系统搭建的开发者。包内提供中控SDK、API函数说明、完整开发文档以及多种示例代码覆盖设备连接、用户管理、考勤记录读取、数据上传下载等核心环节帮助开发者快速理解通讯协议与接口调用方式避免从零摸索。资源共1264个文件以cs源码、dll类库、exe程序、resx资源、txt说明、sln与csproj工程文件为主另含mdb数据库、bat注册脚本及少量图片与文档压缩包约11.08MB工程结构完整可直接参考。目前已有2619人学习下载适合需要快速搭建考勤管理原型、研究SDK调用细节或排查设备通讯问题的开发者示例代码与文档配合使用可显著缩短开发周期。1. 中控考勤机二次开发从 SDK 到 C# 上位机的落地路径手里有一台中控考勤机想把它接进自己的 MES 或者 HR 系统第一反应往往是去官网找 SDK。但真拿到开发包之后很多人会卡在同一个地方文档是 CHM 或者 PDF例子是 C# 的可设备连不上、数据拉不下来、回调不触发。中控考勤机开发文件加 SDK 加文档加各种 C# 例子这套资源解决的就是这个断层——它把设备通信协议、SDK 封装、C# 调用示例和常见业务场景考勤记录拉取、人员下发、实时事件订阅打包在一起适合做上位机、做考勤集成、做门禁联动的 C# 开发者。下面按「资源里有什么 → 怎么跑通第一条记录 → 坑在哪 → 怎么用到生产」的顺序拆一遍。2. 拆开开发包SDK 结构、通信方式与 C# 例子的对应关系2.1 开发包里到底有什么中控ZKTeco的考勤机开发资源通常不是单一文件而是一个组合包。以常见的 Standalone SDK 为例核心目录结构大致如下目录/文件内容用途SDK/zkemkeeper.dll、standalone.dll核心通信库COM 组件形式提供Demo/C#/多个.sln工程拉记录、下发用户、实时事件三类示例Doc/Standalone SDK Manual.pdf、PULL SDK 说明协议说明、接口参数、错误码Tools/zkemkeeper 注册脚本、端口检测工具环境准备Driver/部分型号的 USB 驱动老设备直连用这里要区分两套 SDKStandalone SDK和PULL SDK。前者是 COM 组件C# 里通过Interop.zkemkeeper调用适合局域网内主动连接设备后者是 HTTP 协议设备主动推数据到服务器适合跨网段、设备数量多的场景。C# 例子大多基于 Standalone SDK因为调用直观但生产环境如果设备分散PULL 模式更省心。2.2 通信方式TCP、UDP 还是 USB中控考勤机支持三种连接方式SDK 里对应不同的连接参数TCP默认端口 4370最常用适合局域网。Connect_Net(IP, Port)走的就是这条。UDP同样 4370但丢包时不会重传只建议在设备响应慢时临时用。USB老型号用Connect_USB需要先装驱动现在新设备基本淘汰了。C# 例子里的连接代码通常长这样// 引用 Interop.zkemkeeper.dll 后 private zkemkeeper.CZKEMClass axCZKEM1 new zkemkeeper.CZKEMClass(); private bool bIsConnected false; private int iMachineNumber 1; public bool ConnectDevice(string ip, int port 4370) { // 连接设备iMachineNumber 是设备句柄单设备固定为 1 bIsConnected axCZKEM1.Connect_Net(ip, port); if (bIsConnected) { // 启用设备状态事件否则实时事件不触发 axCZKEM1.RegEvent(iMachineNumber, 65535); } return bIsConnected; }Connect_Net返回bool失败时不要只看返回值要调GetLastError拿错误码。RegEvent的第二个参数是事件掩码65535表示订阅所有事件包括指纹验证、卡刷卡、开门记录。很多人只连接不注册事件然后问为什么实时回调不触发问题就出在这。2.3 C# 例子的三种典型模式开发包里的 C# 例子基本围绕三个场景拉取考勤记录调ReadGeneralLogData把记录读到内存再用SSR_GetGeneralLogData逐条取。注意ReadGeneralLogData只是把数据从设备读到 SDK 缓冲区不是直接返回列表。// 拉取所有考勤记录 if (axCZKEM1.ReadGeneralLogData(iMachineNumber)) { string enrollNumber ; int verifyMode 0, inOutMode 0, year 0, month 0, day 0; int hour 0, minute 0, second 0, workCode 0; // 循环读取缓冲区里的每一条记录 while (axCZKEM1.SSR_GetGeneralLogData(iMachineNumber, out enrollNumber, out verifyMode, out inOutMode, out year, out month, out day, out hour, out minute, out second, ref workCode)) { // enrollNumber 是人员工号verifyMode 是验证方式 Console.WriteLine(${enrollNumber} {year}-{month}-{day} {hour}:{minute}:{second}); } }SSR_GetGeneralLogData的参数全是outC# 里必须用out或ref接收。workCode是ref不是out因为它是工号字段部分固件版本会回填。这个细节文档里写得含糊但例子代码里能看出来。下发人员用SSR_SetUserInfo写用户信息再用SetUserInfo或SSR_SetUserInfo配合RefreshData生效。注意工号enrollNumber是字符串但设备内部按数字处理前导零会被截断建议统一用固定长度。实时事件订阅注册OnAttTransactionEx事件设备有人刷卡时触发。事件是 COM 回调C# 里要加[ComVisible(true)]或者用委托绑定。// 绑定实时事件 axCZKEM1.OnAttTransactionEx new zkemkeeper._IZKEMEvents_OnAttTransactionExEventHandler( (enrollNumber, isInValid, attState, verifyMethod, year, month, day, hour, minute, second, workCode) { // isInValid: 1 表示验证通过0 表示失败 Console.WriteLine($实时事件: {enrollNumber} 验证{(isInValid 1 ? 通过 : 失败)}); });事件回调里不要做耗时操作否则会阻塞 SDK 的通信线程导致后续事件丢失。常见做法是回调里只入队列另起线程处理业务。3. 跑通第一条考勤记录环境准备与最小可运行工程3.1 环境准备注册 COM 组件与平台位数Standalone SDK 是 COM 组件C# 调用前必须注册。开发包里一般带reg.bat或register.bat内容类似# 以管理员身份运行注册 32 位 COM 组件 regsvr32 C:\SDK\zkemkeeper.dll注意zkemkeeper.dll是 32 位的C# 工程必须把目标平台设为x86不能是Any CPU或x64。这是新手翻车最多的地方——编译通过运行时报Class not registered或Retrieving the COM class factory failed九成是位数不对。如果工程必须用 64 位常见做法是改用 PULL SDKHTTP 协议或者用 32 位宿主进程单独跑 SDK 通信再通过 IPC 把数据传给主进程。3.2 最小可运行工程连接、拉记录、断开新建一个 C# WinForms 或 Console 工程引用Interop.zkemkeeper.dll开发包 Demo 里通常已经生成好然后按下面步骤写using System; using zkemkeeper; class Program { static void Main(string[] args) { var sdk new CZKEMClass(); int machineNumber 1; // 1. 连接设备 if (!sdk.Connect_Net(192.168.1.201, 4370)) { int errCode 0; sdk.GetLastError(ref errCode); Console.WriteLine($连接失败错误码: {errCode}); return; } Console.WriteLine(设备已连接); // 2. 拉取考勤记录 if (sdk.ReadGeneralLogData(machineNumber)) { string enrollNumber ; int verifyMode 0, inOutMode 0; int year 0, month 0, day 0; int hour 0, minute 0, second 0, workCode 0; int count 0; while (sdk.SSR_GetGeneralLogData(machineNumber, out enrollNumber, out verifyMode, out inOutMode, out year, out month, out day, out hour, out minute, out second, ref workCode)) { count; Console.WriteLine(${enrollNumber},{year}-{month}-{day} {hour}:{minute}:{second}); } Console.WriteLine($共拉取 {count} 条记录); } else { int errCode 0; sdk.GetLastError(ref errCode); Console.WriteLine($读取记录失败错误码: {errCode}); } // 3. 断开连接 sdk.Disconnect(); } }关键参数说明Connect_Net的 IP 和端口要和设备菜单里「通信设置」一致端口默认 4370部分设备改过。machineNumber单设备固定为 1多设备时每连接一台要递增但同一个 SDK 实例不建议同时连多台容易串数据。ReadGeneralLogData返回true只表示读取指令成功不代表有记录。记录数为 0 时SSR_GetGeneralLogData第一次就返回false。GetLastError的错误码要对照文档里的错误码表常见的有-2连接失败、-3设备忙、-6参数错误。3.3 验证数据是否正确拉到的记录要和设备菜单里的「考勤记录」条数对得上。如果数量不一致先检查设备是否开启了「循环存储」——开启后旧记录会被覆盖SDK 只能读到当前存储的记录。另外ReadGeneralLogData读的是「新记录」如果之前已经读过且没清空设备可能只返回增量。要全量拉取先调ClearGLog清空设备缓冲区再重新读。4. 避坑与排查连接、回调、数据三类高频问题4.1 连接失败错误码 -2 与端口占用现象Connect_Net返回falseGetLastError得到-2。原因三种可能——IP 不通、端口被防火墙拦、设备通信协议不是 Standalone。中控部分新型号默认走 PULL 协议4370 端口不响应 TCP 连接。解决先用telnet IP 4370测端口不通就进设备菜单把「通信协议」改成「Standalone SDK」或「ZKTeco Protocol」。防火墙关掉或放行 4370。如果设备只支持 PULL换 PULL SDK 的 HTTP 接口。4.2 实时事件不触发RegEvent 没调或掩码不对现象连接成功能拉记录但刷卡时 C# 事件不执行。原因RegEvent没调用或者事件掩码设成了0。另外部分固件要求先调EnableDevice再RegEvent。解决连接后立即调RegEvent(iMachineNumber, 65535)并在事件绑定后调EnableDevice(iMachineNumber, true)。如果还不触发检查设备是否开启了「实时上传」选项。4.3 记录时间错乱设备时区与 SDK 解析现象拉到的考勤时间比实际早或晚几小时。原因设备内部用本地时间存储SDK 返回的year/month/day/hour/minute/second是设备时间不是 UTC。如果服务器时区和设备不一致直接入库会错。解决在 C# 里用DateTime组装时明确指定DateTimeKind.Local或者统一在入库前做时区转换。不要用DateTime.Parse直接解析字符串容易受服务器区域设置影响。4.4 人员下发后不生效RefreshData 漏调现象SSR_SetUserInfo返回true但设备上查不到新人员。原因SDK 写数据到设备缓冲区后需要调RefreshData才会写入闪存。解决每次批量下发后调RefreshData(iMachineNumber)。批量操作时不要每写一条就刷新攒一批再刷否则设备写入频繁会变慢甚至卡死。4.5 多设备连接串数据SDK 实例复用问题现象同时连两台设备拉到的记录混在一起。原因一个CZKEMClass实例内部只有一个machineNumber上下文多设备复用时后连接的会覆盖前面的。解决每台设备用独立的 SDK 实例或者串行处理——连一台、拉完、断开、再连下一台。生产环境建议用 PULL 模式设备主动推数据服务端按设备序列号区分。5. 从 Demo 到生产批量拉取、增量同步与异常重连的工程化写法Demo 能跑通不代表能上生产。实际项目里设备可能几十台网络会抖SDK 会卡死。下面是我在几个考勤集成项目里沉淀下来的写法。5.1 增量同步用「最后一条记录时间」做水位全量拉取每次都要读设备全部记录设备存储有限记录多了会慢。常见做法是维护一个水位表记录每台设备最后一次同步的时间戳每次只拉这个时间之后的记录。// 伪代码增量同步逻辑 DateTime lastSyncTime GetLastSyncTime(deviceId); // 从数据库读水位 var records new ListAttendanceRecord(); if (sdk.ReadGeneralLogData(machineNumber)) { string enrollNumber ; int verifyMode 0, inOutMode 0; int year 0, month 0, day 0; int hour 0, minute 0, second 0, workCode 0; while (sdk.SSR_GetGeneralLogData(machineNumber, out enrollNumber, out verifyMode, out inOutMode, out year, out month, out day, out hour, out minute, out second, ref workCode)) { var recordTime new DateTime(year, month, day, hour, minute, second); // 只保留水位之后的记录 if (recordTime lastSyncTime) { records.Add(new AttendanceRecord { DeviceId deviceId, EnrollNumber enrollNumber, RecordTime recordTime, VerifyMode verifyMode }); } } } // 同步完成后更新水位 if (records.Count 0) { UpdateLastSyncTime(deviceId, records.Max(r r.RecordTime)); }水位用「最大记录时间」而不是「当前时间」因为设备时间可能和服务器有偏差。如果设备时间被改过水位会错乱所以生产环境要定期校准设备时间或者用设备返回的记录序号做辅助判断。5.2 异常重连SDK 卡死时的兜底Standalone SDK 在设备断网时Connect_Net可能阻塞几十秒。如果放在主线程界面直接假死。常见做法是连接和拉取放在后台线程用Task.Run包起来。设置超时Connect_Net本身没有超时参数可以用Task.Wait(timeout)控制。连接失败后不要立即重试加退避——第一次等 5 秒第二次 15 秒第三次 30 秒避免把设备打挂。// 带超时和退避的连接 private bool ConnectWithRetry(CZKEMClass sdk, string ip, int maxRetry 3) { int[] delays { 5000, 15000, 30000 }; for (int i 0; i maxRetry; i) { var task Task.Run(() sdk.Connect_Net(ip, 4370)); if (task.Wait(10000) task.Result) { return true; } if (i maxRetry - 1) { Thread.Sleep(delays[i]); } } return false; }注意Task.Wait超时后底层连接可能还在跑SDK 实例状态不确定建议直接丢弃这个实例新建一个再试。复用卡死的实例是血泪经验会一直返回错误。5.3 数据落地批量插入与去重拉到的记录要入库用SqlBulkCopy批量插入比逐条INSERT快一个数量级。去重靠设备 ID 加人员工号加记录时间的唯一索引插入时用MERGE或INSERT ... ON DUPLICATE KEY UPDATE。-- 考勤记录表唯一索引防重复 CREATE TABLE AttendanceRecord ( Id BIGINT IDENTITY(1,1) PRIMARY KEY, DeviceId VARCHAR(50) NOT NULL, EnrollNumber VARCHAR(20) NOT NULL, RecordTime DATETIME NOT NULL, VerifyMode INT, SyncTime DATETIME DEFAULT GETDATE() ); CREATE UNIQUE INDEX UX_Attendance_Device_User_Time ON AttendanceRecord (DeviceId, EnrollNumber, RecordTime);有了唯一索引重复拉取同一时间段也不会产生脏数据增量同步的水位偶尔回退也不怕。5.4 验证同步完整性每次同步后对比设备端记录数和本地新增数。设备端记录数可以用GetDeviceStatus或GetGeneralLogDataCount拿不同固件接口名不同。如果差异超过阈值触发告警。另外定期抽查几条记录和设备菜单里的时间、工号比对确认没有解析错误。从那以后我每次接中控考勤机都先把 SDK 位数、RegEvent 掩码、RefreshData 这三件事在最小工程里跑一遍确认无误再往业务代码里搬。希望帮到你。本文还有配套的精品资源点击获取