ZL.License 2.3.0

dotnet add package ZL.License --version 2.3.0
                    
NuGet\Install-Package ZL.License -Version 2.3.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="ZL.License" Version="2.3.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="ZL.License" Version="2.3.0" />
                    
Directory.Packages.props
<PackageReference Include="ZL.License" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add ZL.License --version 2.3.0
                    
#r "nuget: ZL.License, 2.3.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package ZL.License@2.3.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=ZL.License&version=2.3.0
                    
Install as a Cake Addin
#tool nuget:?package=ZL.License&version=2.3.0
                    
Install as a Cake Tool

ZL.License

轻量离线授权校验库:RSA 签名证书 + 机器指纹绑定 + 试用期 + 功能位(ushort 掩码)。

零第三方依赖 —— 不引 Newtonsoft / NLog / System.Text.Json(连 JSON 都是 16 行的固定字段提取)。 目标框架:netstandard2.0 / net48 / net8.0 / net10.0。


装什么

dotnet add package ZL.License

30 秒接入

// ① 启动时初始化一次(不传参 = 自动读环境变量 + 配置文件)
LicenseManager.Initialize();

// ② 判状态
if (LicenseManager.State is LicenseState.Trial or LicenseState.Authorized)
{
    // 可用
}
else
{
    // 拦截:Invalid / Expired / Uninitialized
}

// ③ 连接 / 操作前检查(**推荐统一入口**)
if (!LicenseManager.AllowOperation("siemens-s7")) return;   // 协议键;连接层传 null

// ④ 设备计数:连接时 +1、断开时 -1(Trial 超限抛 LicenseException;释放幂等、不抛)
LicenseManager.IncrementDeviceCount();
// ... 使用中 ...
LicenseManager.DecrementDeviceCount();

⚠️ Initialize() 可重复调用(幂等);配置变更时会自动 Reset() 重新判定。


三条授权路径(Initialize 内部按序判定,命中即返回)

2026-11-12 变更:原「DevMode(开发模式)」路径已彻底删除(理由与迁移指南见 docs/678)。 它曾要求 ZL_LICENSE_DEV_TOKEN / ZL_LICENSE_DEV_SECRET 令牌校验,但在发布包(Release 构建)里恒被强制关闭 ⇒ 使用方永远无法使用,却被本文档当成特性宣传。

顺序 路径 触发条件 结果
1 EvaluationMode EvaluationMode = true + EvaluationProduct 在白名单内 Authorized(30 天 / 100 台,全功能位)
2 证书 LicenseCertificateBase64(或 LicenseCode) Authorized;证书过期则降级 Trial(Info.ExpiredFromLicense = true)
3 试用 以上都没有 Trial(按产品给默认时长/设备数,见下表)

开发/测试期如何拿到 Authorized(推荐做法)

不需要任何"开发模式" —— 用自签名证书即可,而且走的是真实验签路径:

using System.Security.Cryptography;
using ZL.License;

using var rsa = RSA.Create(2048);
var cert = LicenseCertificateHelper.Create(
    holder: "my-dev",
    machineFingerprint: MachineFingerprint.GetCurrent(),   // 必须与本机一致
    validFrom: DateTime.UtcNow.AddDays(-1),
    validTo:   DateTime.UtcNow.AddDays(365),
    featureMask: 0xFFFF,                                    // 全功能位
    privateKey: rsa);

LicenseManager.Reset();
LicenseManager.Initialize(new LicenseConfig
{
    PublicKeyDer             = rsa.ExportSubjectPublicKeyInfo(),
    LicenseCertificateBase64 = LicenseCertificateHelper.ExportBase64(cert),
});
// ⇒ State = Authorized

四种状态都能造出来(可用于覆盖不同分支):

配置 State AllowOperation
有效证书(指纹=本机、未过期) Authorized true
过期证书 Trial(优雅降级) true
指纹不匹配的证书 Invalid false
new LicenseConfig()(空) Trial true

只需"跑通集成"时,直接用 Trial(零配置、30 天 / 3 台)即可。

证书校验链(任一失败 ⇒ Invalid):反序列化 → RSA-SHA256 验签 → 机器指纹匹配 → 未到生效时间拒绝 → 过期降级 Trial。


配置来源(优先级:环境变量 > 配置文件 > 内嵌默认公钥)

环境变量({prefix} 默认 ZL_LICENSE_)

变量 含义
{prefix}CODE 授权码
{prefix}CERT 证书 Base64(与 CODE 同一格式,CODE 为空时用 CERT)
{prefix}PUBLIC_KEY RSA 公钥(DER Base64);留空用内嵌默认公钥

配置文件(所有产品共用一个)

平台 路径
Windows %APPDATA%\ZL.License\config.json
Linux / macOS ~/.config/zl.license/config.json

支持的字段:licenseCode / licenseCertificateBase64 / devMode / trialDeviceLimit(未知字段忽略)。


功能位(LicenseFeature,ushort 掩码,bit0~15 全部已分配)

位 含义
bit0~7 协议位:Basic / SiemensS7 / ModbusTcp / OmronFins / MitsubishiMc / BacnetIp / IEC61850 / FetchWrite
bit8~10 通用位:BasicRead / Write / MultiDevice
bit11~15 自定义位:CustomFeature1~5(其它产品按需认领;CustomFeature3 已由 KNXnet/IP 认领)

AllowOperation(feature) 的解析规则

  1. Trial 态 ⇒ 放行所有功能(只靠时长 + 设备数兜底)
  2. Authorized 态 ⇒ 查 FeatureMap 得位,再查证书的 FeatureMask; 未登记的键回落 Basic 位

⚠️ 本仓有硬门禁 LicenseRegistrationCompletenessTests:每个注册协议键(含全部别名)都必须显式登记 FeatureMap,否则测试红。⇒ 新增协议不会静默回落。 另有 LicenseSiblingMappingTests 守"同族变体(TCP/串口/UDP/透传)必须同授权位"。


多产品同机部署(隔离并不完整,请先读)

机制 按产品隔离? 依据
环境变量(CODE/CERT/PUBLIC_KEY) ✅ 是 ProductPrefix(如 ZL_GEAR_)
试用戳文件 ✅ 是 ZL.License.{productName}/trial.stamp
配置文件 config.json ❌ 否 GetConfigFilePath() 无产品参数 ⇒ 共用一份
FeatureMap ❌ 共用 设计如此(一张表)

⇒ 已知边界:同机多产品共用 config.json。 · 各产品用不同公钥 ⇒ 证书互相验签失败(安全,但需各自配 {prefix}PUBLIC_KEY) · 各产品用同一公钥 ⇒ 一张证书会同时解锁所有产品

若要真正隔离,需让 GetConfigFilePath() 接受产品名(属破坏性变更:已有安装的 config.json 位置会变),须先做"新路径优先 + 旧路径回退"的迁移方案。


默认试用额度(按 ProductName / ProductPrefix 自动识别)

产品族 试用时长 设备上限
ZL.IotHub / ZL.IotEngine(含未设置 ProductName 的默认情况) 不限时 10 台
ZL.Gear 30 天 3 台
ZLDebug 7 天 2 台
其它(自定义 prefix 且未命中上述家族) 不限时(DefaultTrialDuration) 3 台

免费版"不限时 + 10 台"是定型决策(docs/192);ZL.Gear / ZLDebug 的专属默认见 ResolveTrialDuration / ResolveTrialDeviceLimit。可用 LicenseConfig.TrialDuration / TrialDeviceLimit 覆盖。


公开 API

成员 说明
Initialize(LicenseConfig? = null, string? productPrefix = null) 初始化(幂等)
State LicenseState:Uninitialized / Trial / Authorized / Expired / Invalid
Info LicenseInfo 深拷贝快照(改它不影响内部)
IsAuthorized / IsTrial 便捷判定
AllowOperation(string? feature = null) 推荐统一入口(= CommercialCheck,保留语义化名称)
CommercialCheck(string? feature = null) 纯功能位检查
TrialCheck() 只查试用期时间(含时钟回拨判定:开始时间在将来 ⇒ Expired)
IncrementDeviceCount() / DecrementDeviceCount() 设备计数(超限抛 LicenseException;释放幂等不抛)
ActivatedDevices 当前计数
Revalidate(LicenseConfig? = null) 热重校验(保留设备计数与 Evaluation 倒计时)
Reset() 清空状态(测试 / 热重载)
StateChanged 状态变更事件(处理器异常被隔离,不影响状态)

签发:LicenseCertificateHelper.Create(...) 是 public,可自建签发器(本包不含签发工具)。


边界(重要,请先读)

  1. 只做校验,不做签发 —— 证书生成需你自己的签发工具(用 LicenseCertificateHelper.Create + 私钥)。
  2. 客户端防篡改有上限:试用戳用 HMAC 绑定「机器指纹 + 产品盐」,能挡 顺手改日期 与 跨机/跨产品复用;但删掉 trial.stamp 即重置试用(刻意折中)。 ⇒ 若试用期防重置在商业上重要,唯一有效方案是服务端校验。
  3. 发布包一律 Release 构建(scripts/pack-release.sh),构建产物经混淆后发布; dotnet pack 默认是 Debug,手工打包务必显式 -c Release。
  4. 配置文件读取失败会静默降级(不阻止启动),仅在 Debug 构建输出一行诊断。 ⚠️ Release 下无任何痕迹 ⇒ 排查时请先确认 config.json 是否存在且可读。
  5. FeatureMap 是静态表,新增协议需改 ZL.License 源码(有完备性门禁提示改哪一行)。

与 ZL.IotHub 的关系

ZL.License 是独立基础设施(零 ProjectReference),ZL.IotEngine → ZL.License 单向依赖。 FeatureMap 里登记的是 ZL.IotHub 的协议键;其它产品可用 CustomFeature1~5 扩展, 但请注意认领冲突(当前无机器可读的认领登记,仅 LicenseFeature.cs 注释说明 bit13=KNX)。

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 is compatible.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (3)

Showing the top 3 NuGet packages that depend on ZL.License:

Package Downloads
ZL.IotHub

工业 PLC 数据采集运行时(.NET:netstandard2.0 / net48 / net8.0 / net10.0)。解决的不是「能不能连上 PLC」,而是「连上之后」:几百上千个点位如何采得快、采得稳,坏一个点如何不拖垮整块。实测 300 个点位合并为 4 个块(请求数减少 98.67%),稳定场景约 670 次读取/秒、约 50,277 点位/秒;内置坏点隔离(Quarantine)与变化上报(Deadband)、多速率采样、实时通知订阅、OPC UA 服务端与嵌入式诊断(报告可落盘 JSON/Markdown)。原生驱动覆盖:西门子、三菱(MC/A1E/FX/FX-Links)、松下(MEWTOCOL)、基恩士、欧姆龙(FINS/HostLink)、Allen-Bradley(CIP)、倍福(ADS)、Fatek、Modbus(TCP/RTU/RTU-over-TCP/ASCII)、台达、汇川、信捷、埃斯顿、麦格米特、DALI、DLMS、M-Bus、HART-IP、MTConnect、HTTP-REST、DNP3(TCP;最小可用:Class-0 连通性探测 + 单点读,写入待补)与串口。免费额度:≤10 台设备、协议全开,可直接用于生产验证;>10 台需正式设备授权(一次性设备授权码)。授权咨询:微信 qwdingyu

ZL.IotEngine

工业 PLC 数据采集运行时内核(.NET:netstandard2.0 / net48 / net8.0 / net10.0)——编排、地址合并、批量采集、变化上报与事件通知。解决的不是「能不能连上 PLC」,而是「连上之后」:几百上千个点位如何采得快、采得稳,坏一个点如何不拖垮整块。实测 300 个点位合并为 4 个块(请求数减少 98.67%),稳定场景约 670 次读取/秒、约 50,277 点位/秒;内置坏点隔离(Quarantine)与变化上报(Deadband)、多速率采样、实时通知订阅、OPC UA 服务端与嵌入式诊断(报告可落盘 JSON/Markdown)。⚠️ 协议驱动在**配套插件包 ZL.IotDriver**(本包不引用它,需另行引用;宿主输出目录存在 ZL.Iot*.dll 即自动加载)。驱动覆盖:西门子、三菱(MC/A1E/FX/FX-Links)、松下(MEWTOCOL)、基恩士、欧姆龙(FINS/HostLink)、Allen-Bradley(CIP)、倍福(ADS)、Fatek、Modbus(TCP/RTU/RTU-over-TCP/ASCII)、台达、汇川、信捷、埃斯顿、麦格米特、DALI、DLMS、M-Bus、HART-IP、MTConnect、HTTP-REST、DNP3(TCP;最小可用:Class-0 连通性探测 + 单点读,写入待补)与串口。免费额度:≤10 台设备、协议全开,可直接用于生产验证;>10 台需正式设备授权(一次性设备授权码)。授权咨询:微信 qwdingyu

ZL.IotAbstraction

ZL IoT 契约层:接口 / DTO / 枚举 / 无状态工具 / 轻量日志(无第三方日志框架)

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
2.3.0 0 11/19/2026
2.2.19 186 11/7/2026
2.2.18 281 11/7/2026
2.2.17 236 10/27/2026
2.2.16-beta.3 94 10/15/2026
2.2.16-beta.2 107 10/15/2026
2.2.15 225 10/8/2026
2.2.14 218 10/6/2026
2.2.13 217 9/29/2026
2.2.12 222 9/28/2026
2.2.11 245 9/23/2026
2.2.10 194 9/21/2026
2.2.8 214 9/11/2026
2.2.7 193 9/11/2026
2.2.6 198 9/10/2026
2.2.5 200 9/10/2026
2.2.4 239 9/6/2026
2.2.3 201 9/4/2026