diff --git a/.github/workflows/dotnet.yml b/.github/workflows/dotnet.yml index b307bc6d..3568f5ba 100644 --- a/.github/workflows/dotnet.yml +++ b/.github/workflows/dotnet.yml @@ -47,6 +47,14 @@ jobs: - name: Test with Coverage (net8.0) run: dotnet test tests/StdUnit.Tags.Tests/StdUnit.Tags.Tests.csproj -f net8.0 -c Release --no-build --nologo --collect:"XPlat Code Coverage" --results-directory ./TestResults + # net8.0 专属的测试(BlazorLib.Core / WebUi / ASP.NET Core)不在上面那个项目里。 + # 它们此前只在 release 工作流里跑 —— 于是 2.0 的主打新增(WebUi)在 PR 阶段只能保证"编译通过", + # 回归要等发版当天才发现。AOT job 已在 Linux 上跑 AspNetCore,因此这里放 ubuntu 没有平台障碍。 + # 与主测试**分两步顺序跑**(理由同 release 工作流):`dotnet test` 直接打解决方案会并行拉起多个 testhost, + # 4 vCPU 的 CI runner 上会把"机器忙"变成随机红。 + - name: Test with Coverage (net8.0-only BlazorLib.Core / WebUi) + run: dotnet test tests/StdUnit.Tags.Tests.NetCoreOnly/StdUnit.Tags.Tests.NetCoreOnly.csproj -f net8.0 -c Release --no-build --nologo --collect:"XPlat Code Coverage" --results-directory ./TestResults + - name: Upload Coverage to Codecov uses: codecov/codecov-action@v4 env: @@ -58,11 +66,13 @@ jobs: fail_ci_if_error: true verbose: true - # 迭代产物通道:这**不是**发布,只是把每次构建的 13 个包传上来,好让现场用户/公测者提前试。 - # 版本号故意写成"构建号"(<基础版本>-dev..),它不是语义化版本: + # 迭代产物通道:这**不是**发布,只是把每次构建的包全部传上来(清单见 src/publish-packages.ps1),好让现场用户/公测者提前试。 + # 版本号是 <下一个正式号>-dev.<构建号>,构建号取 UTC 的 yyMMdd.HHmm(如 2.0.0-dev.261113.0930): + # * 单调、唯一、零输入——手工发布(release-baget.yml 的 versionKind=dev)用的是同一个公式, + # 不要换成"run_number"或"本月第几版":那会让 CI 与手工各有一套编号,混进同一个源后互相压过; # * 落在"下一个计划发布的正式号"的预发布位上 ⇒ 排序上低于该正式号(正式版一发就自然覆盖), - # 又高于此前任何正式版(装了它还能正常往前走,不会出现版本降级); - # * 每次构建都唯一 ⇒ 不需要人工决定"这算 minor 还是 major",也不占任何正式号位。 + # 又高于此前任何正式版(装了它还能正常往前走); + # * 预发布只有这一种形态:alpha / beta / rc 已停用(`-dev.*` 天然排在它们之后)。 # 基础版本号**不在这里写死**:唯一来源是仓库根的 next-release-version.txt, # 本步只传构建号,由 publish-packages.ps1 读该文件并拼成 <基础版本>-dev.<构建号>。 # ⚠ 维护点:正式版发布后,把 next-release-version.txt 改成下一个计划发布的号 @@ -75,7 +85,7 @@ jobs: - name: Pack dev packages (迭代产物,不发布) if: github.event_name == 'push' working-directory: ./src - run: dotnet pwsh ./publish-packages.ps1 -DevBuildNumber "${{ github.run_number }}.${{ github.run_attempt }}" -SkipPush -OutputDir ../dev-packages + run: dotnet pwsh ./publish-packages.ps1 -DevBuildNumber "$(date -u +%y%m%d.%H%M)" -SkipPush -OutputDir ../dev-packages - name: Upload dev packages if: github.event_name == 'push' diff --git a/.github/workflows/release-baget.yml b/.github/workflows/release-baget.yml index 25893934..0768ff1b 100644 --- a/.github/workflows/release-baget.yml +++ b/.github/workflows/release-baget.yml @@ -6,9 +6,15 @@ name: Release (baget.stdunit.com) on: workflow_dispatch: inputs: - releaseVersion: - description: 'Release Version' - required: true + # 与 release-nuget.yml 同一个形状:只选发布类型,版本号由工作流从文件算出,不手填。 + versionKind: + description: '发布类型:release=常规版(取 next-release-version.txt);dev=开发版(<该文件>-dev.)' + type: choice + options: + - dev + - release + # 默认 dev:误触发时最多多出一个预发布包,不会误发正式版 + default: dev jobs: build: @@ -16,6 +22,36 @@ jobs: steps: - uses: actions/checkout@v3 + + # 版本号解析 + 校验:放在最前面,坏输入几秒内就失败,不用等整解构建与测试跑完。 + - name: Resolve version + shell: pwsh + env: + VERSION_KIND: ${{ inputs.versionKind }} + run: | + $kind = "$($env:VERSION_KIND)".Trim() + + # 基线只有一个来源:仓库根的 next-release-version.txt + $base = (Get-Content -LiteralPath 'next-release-version.txt' -Raw).Trim() + if ($base -notmatch '^\d+\.\d+\.\d+$') { + throw "next-release-version.txt 必须是正式号 X.Y.Z(不带预发布后缀):$base" + } + + if ($kind -eq 'release') { + $version = $base + } + elseif ($kind -eq 'dev') { + # 构建号由机器生成:UTC 的 yyMMdd.HHmm(如 261113.0930)——单调、唯一、零输入。 + # CI 的迭代产物用同一条规则(dotnet.yml 里的 `date -u +%y%m%d.%H%M`),两边格式一致; + # 不要改成"人来数本月第几版":那会变成 CI 与手工各维护一套编号,混进同一个源后互相压过。 + $stamp = (Get-Date).ToUniversalTime().ToString('yyMMdd.HHmm') + $version = "$base-dev.$stamp" + } + else { throw "未知的 versionKind:$kind" } + + "EFFECTIVE_VERSION=$version" >> $env:GITHUB_ENV + "### 本次发布:``$version``(baget, $kind)" >> $env:GITHUB_STEP_SUMMARY + Write-Host "effective version = $version ($kind)" - name: Setup .NET uses: actions/setup-dotnet@v3 with: @@ -58,7 +94,7 @@ jobs: - name: push working-directory: ./src - run: dotnet pwsh ./publish-packages.ps1 -packageVersion ${{ github.event.inputs.releaseVersion }} env: NugetSource: ${{ secrets.NUGET_SOURCE }} NugetApiKey: ${{ secrets.NUGET_KEY }} + run: dotnet pwsh ./publish-packages.ps1 -packageVersion ${{ env.EFFECTIVE_VERSION }} diff --git a/.github/workflows/release-nuget.yml b/.github/workflows/release-nuget.yml index b5f7cc28..f1c93f4b 100644 --- a/.github/workflows/release-nuget.yml +++ b/.github/workflows/release-nuget.yml @@ -6,9 +6,15 @@ name: Release (nuget.org) on: workflow_dispatch: inputs: - releaseVersion: - description: 'Release Version' - required: true + # 版本号不手填:正式版取仓库根的 next-release-version.txt,dev 版在本步自动拼上构建号。 + versionKind: + description: '发布类型:release=正式版(取 next-release-version.txt);dev=公测预发布(<该文件>-dev.)' + type: choice + options: + - dev + - release + # 默认 dev:误触发时最多多出一个预发布包,不会把正式版推到 nuget.org(不可撤销) + default: dev jobs: build: permissions: @@ -20,6 +26,43 @@ jobs: steps: - uses: actions/checkout@v4 + # 版本号解析 + 校验放在最前面,坏输入几秒内失败,不用等整解构建与测试跑完。 + # 预发布(-dev.*)是唯一的公测途径(alpha/beta/rc 已停用);nuget.org 上的版本不可撤销, + # 所以 dev 只在你明确选它时才发,日常 dev 仍建议只推私有源。 + - name: Resolve version + shell: pwsh + env: + VERSION_KIND: ${{ inputs.versionKind }} + run: | + $kind = "$($env:VERSION_KIND)".Trim() + + # 基线只有一个来源:仓库根的 next-release-version.txt + $base = (Get-Content -LiteralPath 'next-release-version.txt' -Raw).Trim() + if ($base -notmatch '^\d+\.\d+\.\d+$') { + throw "next-release-version.txt 必须是正式号 X.Y.Z(不带预发布后缀):$base" + } + + if ($kind -eq 'release') { + $version = $base + } + elseif ($kind -eq 'dev') { + # 与 CI / baget 同一条规则:UTC 的 yyMMdd.HHmm + $stamp = (Get-Date).ToUniversalTime().ToString('yyMMdd.HHmm') + $version = "$base-dev.$stamp" + } + else { throw "未知的 versionKind:$kind" } + + "EFFECTIVE_VERSION=$version" >> $env:GITHUB_ENV + if ($kind -eq 'dev') { + "### 本次发布:``$version``(nuget.org,**预发布 / 公测**)" >> $env:GITHUB_STEP_SUMMARY + "> nuget.org 上的版本不可撤销。若不想让它被 ``--prerelease`` 默认选中,发布后到 nuget.org 手动 **unlist**。" >> $env:GITHUB_STEP_SUMMARY + } + else { + "### 本次发布:``$version``(nuget.org)" >> $env:GITHUB_STEP_SUMMARY + } + + Write-Host "effective version = $version ($kind)" + - name: Setup .NET uses: actions/setup-dotnet@v3 with: @@ -74,5 +117,5 @@ jobs: - name: push working-directory: ./src - run: dotnet pwsh ./publish-packages.ps1 -packageVersion ${{ github.event.inputs.releaseVersion }} -nugetKey ${{steps.login.outputs.NUGET_API_KEY}} -nugetSource https://api.nuget.org/v3/index.json + run: dotnet pwsh ./publish-packages.ps1 -packageVersion ${{ env.EFFECTIVE_VERSION }} -nugetKey ${{steps.login.outputs.NUGET_API_KEY}} -nugetSource https://api.nuget.org/v3/index.json diff --git a/AGENTS.md b/AGENTS.md index 459ff044..4d8bc851 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,7 +23,7 @@ dotnet test --no-build --collect:"XPlat Code Coverage" --results-directory ./Tes ``` CI(`.github/workflows/dotnet.yml`)有**三个 job**: -- **`build`(ubuntu-latest,权威)**:整解 `dotnet build StdUnit.Tags.sln -c Release`(含 net472 的**编译**校验——引用程序集由 SDK 隐式引入的 `Microsoft.NETFramework.ReferenceAssemblies` 提供)+ `dotnet test -f net8.0`(带覆盖率上报 codecov)。 +- **`build`(ubuntu-latest,权威)**:整解 `dotnet build StdUnit.Tags.sln -c Release`(含 net472 的**编译**校验——引用程序集由 SDK 隐式引入的 `Microsoft.NETFramework.ReferenceAssemblies` 提供)+ 两个测试项目**分两步顺序**跑 `dotnet test -f net8.0`(`StdUnit.Tags.Tests` 与 `StdUnit.Tags.Tests.NetCoreOnly`,带覆盖率上报 codecov)。 - **`net472-on-mono`(ubuntu-latest)**:`apt-get install -y mono-complete` 自己装 Mono,跑 `dotnet test -f net472`,让 net472 的**运行**测试也自动化、又不占 Windows runner 的排队时间。**mono ≠ .NET Framework**,它绿只说明"大概率没退化",(权威结果仍归发版工作流 `release-nuget.yml` / `release-baget.yml`,windows-latest 全 TFM)+ 本机 Windows。当前是**硬性把关**(未设 `continue-on-error`);万一出现 mono 专有的伪失败,可在 job 上加 `continue-on-error: true` 降级为补充信号。mono job 红时先看是不是"mono 与真框架的差异",别急着改产品代码。 - **`aot-smoke`(ubuntu-latest)**:三个示例各自 `dotnet publish ... -r linux-x64`(需 `clang` + `zlib1g-dev`)后**运行原生产物**:`AotSmokeTest.LogicetPlugins` 验证"无 `` 的正常加载 + `TryAddLogicet` + AOT 下配了 `` 必须快速失败",`AotSmokeTest.SimpleFiles` 验证"基本类型测点 + JSON 测点(源生成元数据)读写 + AOT 下缺元数据必须快速失败",`AotSmokeTest.WebUi` 验证"起 Kestrel + 结构树的多态 JSON 序列化(`[JsonDerivedType]` 源生成)+ SSE 从全量基线到增量"。改了 AOT 相关代码(`IsAotCompatible`、`[DynamicallyAccessedMembers]`、`Compat/*`、插件加载路径、WebUi 的 DTO/序列化)时以它为准;publish 输出里的 `IL2104`/`IL3053` 来自第三方 `McMaster.NETCore.Plugins`,属已知噪声。 - 两条 Linux job 统一遵循 **"`ubuntu-latest` + 依赖自装"**,不钉镜像版本:本仓库自己装依赖(mono / clang+zlib),就没有理由把 job 的寿命绑在镜像标签上——`ubuntu-22.04` 已被官方公告 2026-09-17 起弃用、2027-04-17 退役(`actions/runner-images#14254`,期间还有 brownout 会直接判红),`ubuntu-latest` 也已宣布 2026-11 起为 26.04。 @@ -40,7 +40,7 @@ CI(`.github/workflows/dotnet.yml`)有**三个 job**: ## 目标框架(多目标) -**Core / StdUnit.Tags / Rx / R3 / 全部驱动包(S7、ModbusTcp、Hjzk、ZLan、OpcUaClient、ComScanner、SimpleFiles)/ McpServer 都是 `net8.0;net472`;仅 BlazorLib(.Core) 仍是 `net8.0`。** +**Core / StdUnit.Tags / Rx / R3 / 全部驱动包(S7、ModbusTcp、Hjzk、ZLan、OpcUaClient、ComScanner、SimpleFiles)/ McpServer 都是 `net8.0;net472`;仅 BlazorLib.Core 仍是 `net8.0`。** > McpServer 走 `ModelContextProtocol`(核心包)的 `netstandard2.0` 资产。 > `ModelContextProtocol.AspNetCore` 是 net8-only,与核心包同在 `Mcp` 组,但只被 net8-only 的项目引用,因此不影响 net472。 @@ -49,7 +49,7 @@ CI(`.github/workflows/dotnet.yml`)有**三个 job**: - **有标准库就用标准库。** 跨框架差异用调用点的 `#if NETFRAMEWORK` 或项目内 `Compat/` 目录的单点垫片(如 `StdUnit.Tags.Core/Compat/ReferenceEqualityComparer.cs`、`StdUnit.Tags/Compat/DynamicLoadingCompat.cs`、各驱动的 `Compat/*.cs`)。 - **不要把 `#if` 铺到调用点满屏幕,也不要用 `#if` 去条件修饰公共 API**(那会给库使用者制造两套签名)。 -- `ImplicitUsings`/`Nullable`/`LangVersion`/`GenerateDocumentationFile` 由 `src/` 与 `tests/` 各自的 `Directory.Build.props` 统一提供(`tests/` 那份不含 NuGet 打包元数据,且已把 `GenerateDocumentationFile` 设为 `false`),新建项目不用再写这几项(net472 默认 C# 7.3,少写一次就少一次 CS8630);`TargetFrameworks` 仍写在各 csproj(存在 net8-only 项目)。`src/` 下不生成 XML 文档的项目仍要在本项目显式写 `false`(现有:BlazorLib;它是"尚未补注释"的历史包袱)。 +- `ImplicitUsings`/`Nullable`/`LangVersion`/`GenerateDocumentationFile` 由 `src/` 与 `tests/` 各自的 `Directory.Build.props` 统一提供(`tests/` 那份不含 NuGet 打包元数据,且已把 `GenerateDocumentationFile` 设为 `false`),新建项目不用再写这几项(net472 默认 C# 7.3,少写一次就少一次 CS8630);`TargetFrameworks` 仍写在各 csproj(存在 net8-only 项目)。`src/` 下不生成 XML 文档的项目仍要在本项目显式写 `false`(目前没有这种情况)。`src/Directory.Build.props` 已开启 `TreatWarningsAsErrors`(整解仍是 0 警告);`tests/` 与 `samples/` 有意不加,因为 AOT 冒烟项目的 `dotnet publish` 会带出第三方 `McMaster.NETCore.Plugins` 的 IL2104/IL3053 噪声。 - **AOT 相关**(逐包状态见 `docs/设计决策与边界/4. 目标框架差异.md` 的表,新增包记得补一行并放进对应分组): - `true` ——**TFM 下界必须写 `net8.0`**:`NETSDK1210` 的提示文本里给的是 `'net7.0'`(SDK 的通用下界),**不要照抄**—— @@ -75,6 +75,9 @@ CI(`.github/workflows/dotnet.yml`)有**三个 job**: **必须快速失败**(`TagsProjectNotSupportedException`),**不要**让它被 `LogicetLoader` 的通用 `catch` 吞掉——配了却静默不跑业务逻辑是硬红线。 `tests/AotSmokeTest.LogicetPlugins` / `tests/AotSmokeTest.SimpleFiles` / `tests/AotSmokeTest.WebUi` 是这些链路的端到端验证(CI 的 `aot-smoke` job)。 - net472 缺 init-only setter 时,在 `paket.references` 里加 `IsExternalInit`(已有先例:Core / StdUnit.Tags / ComScanner / OpcUaClient / SimpleFiles)。 +- **net8.0 共享框架里有的 API,在 net472 上一律按需补包引用,且只在 net472 生效**:`paket.references` 写 + `framework: net472`(先例:`System.Threading.Channels`、`System.Diagnostics.DiagnosticSource`——后者是 + `StdUnit.Tags` 暴露 Metrics 所需)。这样 net8.0 的 nuspec / 消费方体验完全不变,代价只落在 net472 组。 - **net472 的引用程序集没有可空标注**,`string.IsNullOrEmpty` 之类的 BCL 后置条件看不到,会出现 net472 专属的 CS8601/CS8603/CS8604 假阳性。改用语言级判空(`x is null || x.Length == 0`),**不要用 `NoWarn` 压掉**。 - 不要用 `| Select-Object -First n` 过滤 `dotnet paket`/`dotnet build` 的长输出:会在第 n 行处终止上游进程。先 `Out-File` 再 grep。 @@ -91,7 +94,7 @@ StdUnit.Tags.Core 硬件无关的核心抽象 + Schemas/tagsproje │ ├── StdUnit.Tags.ComScanner │ ├── StdUnit.Tags.SimpleFiles │ ├── StdUnit.Tags.McpServer -│ └── StdUnit.Tags.BlazorLib(.Core) +│ └── StdUnit.Tags.BlazorLib.Core 维护模式(不再加新功能,界面能力走 WebUi) └── StdUnit.Tags.RxExtensions / R3Extensions 只依赖 Core ``` @@ -100,9 +103,13 @@ StdUnit.Tags.Core 硬件无关的核心抽象 + Schemas/tagsproje 如果驱动会从 `TagDescriptor.Extras` / `TagCbntDescriptor.Extras` 里读**自己的属性**(如 S7 的 `maxlen`、SimpleFiles 的 `autoCreateFile`、ModbusTcp 的 `interpret`),还要在同一个 `appinfo` 里用 `` / `` 声明;核心 schema 因 `xs:anyAttribute` 放行这些属性,但 XSD 1.0 无法给既有类型追加属性,所以"有哪些、什么类型、什么文案"只能由驱动声明(仅供设计器,不参与校验)。详见 `Schemas/README.md`。 - 测试分两个项目(xUnit),且**主测试项目多目标 `net8.0;net472`**: - `tests/StdUnit.Tags.Tests`:主体测试,跑在两个 TFM 上; - - `tests/StdUnit.Tags.Tests.NetCoreOnly`:**仅 net8.0**,专门存放无法面向 net472 的测试(如依赖 `AssemblyLoadContext`,或将来涉及 Blazor / ASP.NET Core 的测试)。目前为空项,作占位预留。 -- **新增测试默认放 `tests/StdUnit.Tags.Tests`**(多目标,两个 TFM 都跑);只有当测试依赖 `net8.0` 专属的包/项目(如 `ModelContextProtocol.AspNetCore`、`BlazorLib`)或 `net8.0` 专属运行期 API(如 `AssemblyLoadContext`)时,才放 `tests/StdUnit.Tags.Tests.NetCoreOnly`。 + - `tests/StdUnit.Tags.Tests.NetCoreOnly`:**仅 net8.0**,专门存放无法面向 net472 的测试(如依赖 `AssemblyLoadContext`,或涉及 Blazor / ASP.NET Core 的测试)。目前承载 `StdUnit.Tags.WebUi` 与 `BlazorLib.Core` 的测试,并已在 PR CI 中执行(不要把它排除出 CI:它曾是"只在发版当天才跑一次"的盲区)。 +- **新增测试默认放 `tests/StdUnit.Tags.Tests`**(多目标,两个 TFM 都跑);只有当测试依赖 `net8.0` 专属的包/项目(如 `ModelContextProtocol.AspNetCore`、`BlazorLib.Core`、`WebUi`)或 `net8.0` 专属运行期 API(如 `AssemblyLoadContext`)时,才放 `tests/StdUnit.Tags.Tests.NetCoreOnly`。 不要在 `tests/StdUnit.Tags.Tests` 里用 `#if NETFRAMEWORK` 排除整个文件——那是编译期开关,解决不了“引用 net8-only 项目”的问题(目前仅 `Core/Logicets/LogicetPluginLifecycleTests.cs` 因这一原因用 `Compile Remove` 在 net472 下排除)。 +- `benchmarks/StdUnit.Tags.Benchmarks`:BenchmarkDotNet 基准(`net8.0`)。它在解决方案内,所以整解构建会编译它 + (防止 API 漂移后悄悄腐烂),但**不**参与 CI 的测试与 AOT 冒烟;完整测量只在本地跑 + `dotnet run -c Release --project benchmarks/StdUnit.Tags.Benchmarks -- --filter *`。 + 依赖走 Paket 的 `Benchmarks` 组(`storage: none`),**绝不能**出现在任何发布包的依赖里。 ## 不可破坏的设计约束 @@ -123,7 +130,7 @@ StdUnit.Tags.Core 硬件无关的核心抽象 + Schemas/tagsproje - **启停语义**:`ITagsProjectCtrl.StopAsync()` 会先**等轮询循环退出**(有界超时,默认 30s)再释放项目、断开通道、触发"已停止"事件;`StartPollAsync` 的 `finally` 是项目的**唯一常规释放点**(只有等待超时那一刻才由 `StopAsync` 兜底释放,因此"只释放一次"是硬约束)。改启停或清理路径时必须保持这个顺序,详见 `docs/设计决策与边界/`。 - **取消不是崩溃**:`StopAsync` 引起的取消不触发 `RunnerCrashed`、不计入连续失败、不按重试策略退避(`TagGrpRunner` 用 `catch (OperationCanceledException) when (ct.IsCancellationRequested)` 单独处理),但通道照常断开、`StartAsync` 仍以 OCE 结束。判据是"令牌确实已取消":驱动因自身原因(如设备超时)抛的 OCE 仍是崩溃。`RunnerStarted` / `RunnerCrashed` / `TurnProcess` 拿到的都是同一个生命周期令牌;**清理类异步操作一律用 `CancellationToken.None`**(见 `DisconnectAllAsync`)。 - 公共编译设置(`ImplicitUsings` + `Nullable` + `LangVersion latest` + XML 文档文件)在 `src/Directory.Build.props`(与 `tests/Directory.Build.props`,后者不含包元数据),NuGet 包元数据(作者/授权/仓库/项目主页/标签/README)只收口在 `src/Directory.Build.props`;**新增会被发布的包时,务必在自己 csproj 里补一行 ``**(否则 nuget.org 上只会显示 SDK 占位文本 `Package Description`),并把项目名加进 `src/publish-packages.ps1` 的列表。 -- **版本号不要写进 workflow**:dev 通道(CI 的迭代产物 / 本地预演)用 `src/publish-packages.ps1 -DevBuildNumber <构建号>`,基础版本由脚本读仓库根的 `next-release-version.txt` 拼成 `<基础版本>-dev.<构建号>`;正式发布仍用 `-packageVersion <语义化版本>`。正式版发布后要改的是那个文件。README **不写**发版细节(它会被打进每个 nupkg),版本通道与发布流程都在 `docs/设计决策与边界/3. 打包与发布.md`。 +- **版本号不要写进 workflow**:dev 通道(CI 的迭代产物 / 本地预演)用 `src/publish-packages.ps1 -DevBuildNumber <构建号>`,基线由脚本读仓库根的 `next-release-version.txt` 拼成 `<基础版本>-dev.<构建号>`;**构建号是 UTC 的 `yyMMdd.HHmm`**(如 `261113.0930`),由 workflow/命令自动生成,不手填。预发布只有 `-dev.*` 一种形态(alpha/beta/rc 已停用);它可以发到私有源(日常)**也可以发到 nuget.org(公测,`release-nuget.yml` 选 `versionKind=dev`)**。两个发布工作流都只有 `versionKind`(`release` / `dev`)一个下拉,版本串从 `next-release-version.txt` 拼出,不手填。正式版发布后要改的是那个文件。README **不写**发版细节(它会被打进每个 nupkg),版本通道与发布流程都在 `docs/设计决策与边界/3. 打包与发布.md`。 - **测试代码必须跨平台**(CI 只跑 Linux),两类路径都要当心: - **分隔符**:相对路径一律用 `/` 或 `Path.Combine` 分段,**不要写 `@"Samples\Web\index.xml"`**——反斜杠在 Linux 是合法文件名字符,`Path.Combine` 不会转换,结果是"Windows 上绿、Linux 上 `File.Exists` 失败"。夹具/示例用 `TestPaths.Fixture("Samples", "Web", "index.xml")` 定位。 - **Windows 专有绝对路径**:`C:\base` 在 Linux 上**不是** rooted 路径,`Path.Combine` 的行为会不同(Windows 丢弃前一段、Linux 拼接),于是同一个用例在两个平台上"测的不是同一件事"。需要"绝对路径"语义的数据请用 `TestPaths.TempPath("base")`(运行时由 `Path.GetTempPath()` 拼出,两个平台都真 rooted)。 diff --git a/CHANGELOG.md b/CHANGELOG.md index a050e3fe..10f3665f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,8 +2,87 @@ 本文件记录**用户可见**的变化。版本号遵循[语义化版本](https://semver.org/lang/zh-CN/) `..`。 - -## 2.0.0-beta8(尚未发布) +> **版本号策略**:预发布只有一种形态 `<下一个正式号>-dev.<构建号>`(构建号是 UTC 时间戳,如 `2.0.0-dev.261113.0930`), +> 不再使用 Alpha / Beta / RC 这类里程碑标签——它们只是 1.x 与 2.0 早先的历史版本号,不追溯改名。 +> 详见 [3. 打包与发布](docs/设计决策与边界/3.%20打包与发布.md)。 + +## 2.0.0(尚未发布) + +2.0.0 预计 2026 年 12 月发布。**`2.0.0-beta9` 从未发布**:beta8 之后直接由 `2.0.0-dev.<构建号>` 预发布通道接正式版。 + +- `ITagsProjectCtrl`:**修复启动/停止之间的潜在竞态问题**:`CancellationTokenSource` 与"轮询已退出"信号此前是两个字段分别发布, + `StopAsync` 可能读到"门已开、但两个手柄都还没写"的中间态——于是取消落空、也不等退出, + 还会顺手把 `_lock` 清零,让新的启动与旧循环并发跑。 + 现在控制器的**全部可变状态收进一个不可变快照**(`State` / `Project` / `RunId` / 运行手柄 / 各类"只做一次"标记), + 迁移一律走"构造新快照 + CAS 替换":读者一次读取即得一致组合,"只做一次"的副作用由 CAS 认领, + 并因此**不再使用 `volatile` 关键字、也不再需要单独的门字段**(`Handles` 非 null 即"有运行在飞")。 + 同时**只有 `StartPollAsync` 的 finally 能释放门**,`StopAsync` 不再碰它 + (超时兜底后旧循环仍活着时,门保持关闭,新的启动会被 `OnStartingException` 拒绝,而不是并发出第二个运行)。 + +StdUnit.Tags.S7: **通道内部简化**(公开行为不变) + - `S7TagChannel.CreateClientAndConnectAsync(ct)` → **`CreateClientAndConnect(channelName)`**:`protected virtual`, + 返回 `S7Client`、失败即抛 `InvalidOperationException`,不再泄露 F# 类型到通道代码里。 + - `Dispose()` 与 `DisconnectAsync()` 收敛为**同一条释放路径**,且不再用 `S7Client.Connected` 当守卫—— + 它是底层 Socket 的快照,半死连接上返回 `false`,恰好会把最该关的连接留下来。 + 报告方式仍按既有约定:`DisconnectAsync` 失败抛出,`Dispose` 只记日志。 + - 连接/断开不再用 `Thread` 把同步调用伪装成异步;读/写本就是"调用方提供缓冲区"的同步实现,限制条件不变。 + +StdUnit.Tags.OpcUaClient / ModbusTcp: **断开失败不再被静默,释放路径收敛** + - `OpcUaClientTagChannel`:`Dispose()` 与 `DisconnectAsync()` 共用同一段会话释放收尾(`ReleaseSession`);会话在关闭后**必须** `Dispose`—— + `Close` / `CloseAsync` 只负责"关闭会话",不释放订阅与传输句柄,此前反复启停会攒下没人认领的对象。 + 已断开的会话不再重复 `Close`(OPC UA 栈会因此抛错),但仍然 `Dispose`。 + - `ModbusTcpChannel`:`Dispose()` 与 `DisconnectAsync()` 收敛到唯一一条关闭路径(`TryCloseConnection`), + 并且不再用 `TcpClient.Connected` 当守卫——它只是上次 I/O 的快照,半死连接上返回 `false`, + 恰好会把最该关的 socket 留下来。`DisconnectAsync` 也不再 `new Thread` 把同步 `Close` 伪装成异步。 + - `DefaultTagGrpRunnerDisconnectStrategy`:已完成的断开任务补一次 `await`,故障才能冒到 `DisconnectAllAsync` 的 + `catch`(此前故障 `Task` 无人观察,那条 `catch` 永远不会触发,断开失败完全不可见)。 + - `ITagChannel` 把报告方式写进公开契约:`DisconnectAsync` 失败以异常 / 故障 `Task` 报告,`Dispose` 只记日志不外抛。 + +StdUnit.Tags: **运行器判脏改用扁平索引,干净轮次不再空写** + - `TagGrpRunner` 在每次(重)启动时把入口子树中的 `ITag` / `ITagCbnt` 收集成扁平数组,每轮判脏 + 由"递归遍历 + `TagUnion` 分发"改为两次数组扫描;并在逻辑处理后判一次,**干净时整趟跳过 `WriteAsync`** + (它原本对干净节点也是空操作)。10k 点位:判脏 52 µs → 26 µs,另省掉约 81 µs/轮的空写遍历。 + - 索引的正确性依据是 `ITagGrp.IsDirty()` 与 `WriteAsync` 的一致性契约:**`IsDirty()` 为 false 时写不得有任何动作; + 只要存在待写节点(`ITag` / `ITagCbnt` 自身的 `IsDirty`)就必须为 true**。这**不是**"父脏必有脏子"—— + `ITagCbnt.IsDirty` 可以独立为 true(整块缓存重写),索引收录的正是 Tag 与组合本身,因此不会漏。 + +StdUnit.Tags.ModbusTcp: **修复每轮存活探测的 15.9 ms 开销** + - `ModbusTcpChannel.Connected` 原先用 `Socket.Poll(1000, SelectRead)` 判断链路是否还活着。 + Windows 的计时器粒度约 15.6 ms,空闲连接上这一步实测 **15.9 ms/次**;而 `TagGrpRunner` + **每轮、每个通道**都会调一次 `EnsureConnectedAsync`,于是扫描周期被凭空拖长(100 ms 周期下约 16% 开销, + 多通道叠加更明显)。 + - 改为 `Poll(0)`:判定逻辑完全不变(`Poll(SelectRead) && Available == 0` 即判定为断), + 但不再阻塞;实测单次 **15.9 ms → 2.3 µs**。 + +StdUnit.Tags.Core: **`access` 的继承修正为逐级冒泡** + - 此前只有组(`ITagGrp`)沿父链递归;`ITag` 与 `ITagCbnt` 只查"直接父级自己配了没",于是 + `TagGrp(access="RO") → TagCbnt(未配)` 下的测点会被判成 `RW`——同样的意图直接挂在组下却是 `RO`。 + 2.0 统一为:自身 → 父级 Cbnt → 各级 Grp → 默认 `RW`。 + - **行为变更**:把 `access` 写在祖先上的配置现在会真正生效。原先被误判成 `RW` 的点会变成 + `RO` / `WO` / `R1W` —— 典型影响是"只读点不再被自动轮询写入"、"`R1W` 点不再每轮重复读"。 + - **访问模式是配置期属性**:加载完成后修改 `TagDescriptor.AccessMode`(或重新赋值 `access`) + 不会生效,需要重新加载项目。原文没有明说,但这是既有实现的实际行为;现在把它写成显式约束, + 运行期因此可以安全缓存解析结果(每点位只解析一次)。 + +StdUnit.Tags.Core: **`TagUnion` 的读写不再逐节点构造闭包** + - `TagUnionExtensions.ReadAsync` / `WriteAsync` 由 `Map(闭包, 闭包, 闭包)` 改为按节点类型 `switch`: + 不再为每个节点构造委托与异步状态机,读同步完成的常见路径直接返回 `Task.CompletedTask`; + 只有真正异步(设备 I/O)时才走"读后标记 `IsScanned`"的续体。 + - 解析出的访问模式缓存在 `TagUnion` 上(它是配置期属性,见上一条),每个点位只解析一次。 + 公开行为不变,`R1W` / `WO` / `RO` 的跳过语义与使能门控照旧。 + +StdUnit.Tags: **新增运行期指标(`System.Diagnostics.Metrics`)** + - Meter 名 `StdUnit.Tags`,四个指标:`stdunit.tags.turns`、`stdunit.tags.turn.duration`(单位 `s`)、 + `stdunit.tags.failures`、`stdunit.tags.reconnects`;维度只有 `entry`(入口定位路径)。 + 指标名 / 单位 / tag 键属于对外契约,只增不改;无监听者时零分配,也没有开关。 + - 新增**公开静态类 `TagsMetricContract`**:上述契约(名称 / 单位 / tag 键)以常量形式集中暴露 + (`MeterName` / `Turns` / `TurnDurationUnit` / `EntryTag` …),订阅与建视图时不用抄字面量。 + - **net472 因此多一个依赖** `System.Diagnostics.DiagnosticSource`(net8.0 由共享框架提供); + `StdUnit.Tags.Core` 仍然零外部依赖。 + - 新增公开扩展 `ITagGrpExtensions.GetLocationPath()`:返回 `TagGrp(a)/TagGrp(b)` 形式的定位路径。 + 它此前只是加载期错误消息的内部工具,现在错误消息与指标的 `entry` 维度共用这一种格式。 + +## 2.0.0-beta8 > 本批仍是 `2.0.0` 的预发布——`2.0.0` 正式版保持未发布。 diff --git a/README.md b/README.md index ee61f480..ee10d390 100644 --- a/README.md +++ b/README.md @@ -71,6 +71,31 @@ dotnet new tags.driver -n your-project.name -D YourDriver - 业务逻辑插件化:`netcore`上支持逻辑组件插件(dll),各插件的依赖相互隔离、支持卸载和热更(`netfx`上降级支持,见“netfx 的插件化限制”)。 - 支持通过MCP方式暴露给AI:把测点项目描述作为上下文,让AI可以轻松操作你的设备 +## Benchmarks + +本类库自身的开销已经量化,并作为回归基线维护在 [benchmarks/README.md](benchmarks/README.md)(含复现命令与每个数字的边界说明)。 +下面是实测基线中的一组代表性数字(i7-8700 3.20 GHz;耗时随机器变化,只看**量级**与堆分配): + +| 场景 | 开销 | 堆分配 | +|---|---|---| +| 轮询-读遍历(每点位) | **~9 ns** | **0 B** | +| 轮询-组合式测点分发(每子测点) | **~2–3 ns** | **0 B** | +| 轮询-每轮判脏(每点位) | **~2.4 ns** | **0 B** | +| 轮询-每轮通道存活探测(Modbus) | **~2.3 µs/通道** | **0 B** | +| 轮询-指标打点(无人订阅 / 有人订阅) | 3.8 ns / 5.7 ns | **0 B** | + +表中的**轮询路径**不产生托管垃圾,意味着对 `GC` 零压力;轮询循环里唯一的固定分配是轮间等待的定时器(几百字节/轮),不在本表范围内。 +而每个点位自身仍需要少量存储空间(目前约 **350–400 B/点**)——这部分属于一次性常驻内存,随点数线性增长,与是否扫描、扫描频率都无关,也不会带来 `GC` 压力。这组数字说明三点: + +- **类库不是瓶颈**:1 万点位的读遍历,在类库自身层面约 **0.09 ms/轮**,而一次 Modbus / OPC UA 往返是 ms 级。 +- **稳态零分配**:上述路径不产生托管垃圾,高频采集时的 GC 压力与点位数无关,也不是由 `StdUnit.Tags` 运行时自身产生的。 +- **常驻内存随点数线性增长**:1 万点位约 3.3–3.8 MB(托管对象图),5 万点位约 17–19 MB,不构成部署障碍。 + +> 例外:直读点位(`DirectTag`,兜底用法)每点每轮有一次地址解析(约 0.8 KB 分配);把点位组织成 `TagCbnt` 时地址只在加载期解析一次。 +> +> 这些数字只用于版本间对比,不作为对具体现场的吞吐承诺。 + + ## 文档与示例 ### 文件夹结构 @@ -78,6 +103,9 @@ dotnet new tags.driver -n your-project.name -D YourDriver - `src/`: 源码,主要包括核心包、驱动包和扩展包 - `tests/`: 自动化测试项目(`StdUnit.Tags.Tests` / `StdUnit.Tags.Tests.NetCoreOnly`)与 AOT 冒烟程序(`AotSmokeTest.*`) - `samples/`:放示例与喂狗程序 +- `benchmarks/`:性能基准(BenchmarkDotNet,`net8.0`)。在解决方案内,所以 `dotnet build` 会编译它以防 API 漂移; + **不**参与 CI 的测试与 AOT 冒烟。最新数据与解读见 [benchmarks/README.md](benchmarks/README.md)。 + 本地跑:`dotnet run -c Release --project benchmarks/StdUnit.Tags.Benchmarks -- --filter *`。 - `.config/` - `dotnet-tools.json`: 本项目用到的 dotnet tools 配置 - `paket.dependencies`: 用 [`paket`](https://github.com/fsprojects/Paket)管理的依赖声明 @@ -100,11 +128,11 @@ dotnet new tags.driver -n your-project.name -D YourDriver 扩展包: - `StdUnit.Tags.RxExtensions`: `dotnet/reactive`扩展,只依赖于`StdUnit.Tags.Core` - `StdUnit.Tags.R3Extensions`: `Cysharp/R3`扩展,只依赖于`StdUnit.Tags.Core` -- `StdUnit.Tags.BlazorLib.Core`: Blazor 类库,包含核心功能抽象,以及一个极简的监控页面。 - `StdUnit.Tags.McpServer`: 这是一个把`StdUnit.Tags`暴露成 [Model Context Protocol Server](https://modelcontextprotocol.io/) 的类库。 - `StdUnit.Tags.WebUi`: 测点项目的 **Web 界面**(ASP.NET Core,不依赖 Blazor / SignalR,可在 NativeAOT 宿主下使用)。监控侧:结构树走一次性 `GET`、值按"入口 + 轮次"以 SSE(`text/event-stream`)推送,内置极简监控页(`GET /stdunit.tags/ui`);设计器侧:把核心 + 各驱动 schema 内省成元数据(`GET /stdunit.tags/catalog`),通道/测点设计器据此渲染表单、导入既有项目 XML 并导出(`GET /stdunit.tags/designer`,未知驱动/元素/属性原样保留)。页面都是单文件 HTML + 内嵌 JS,无需 npm 工程。另有两个写命令(`POST /stdunit.tags/value` 改值、`POST /stdunit.tags/rescan` 标记未扫描)。端点只允许改**路由前缀**(`app.MapTagsStream("/internal/tags")`),相对路径是线协议的一部分;**不内置任何鉴权**,暴露到非受信网络前请对返回的路由组加策略,例如 `app.MapTagsStream().RequireAuthorization()`。 +- `StdUnit.Tags.BlazorLib.Core`: Blazor 类库,**2.0 起进入维护模式**:不再新增功能,新的界面能力(监控 + 设计器)都做在 `StdUnit.Tags.WebUi` 上。 -> 备注:源码目录中还有一个 `StdUnit.Tags.BlazorLib`(不是 `StdUnit.Tags.BlazorLib.Core`),放的是常用硬件设备的编辑器和设计器实现。这些只是我把脑子里的片段随手写下来的实验性代码——因为将来可能做成类库,里面不少东西被标成了`public`——目前它只是实验场,不对外发布。 +> 备注:2.0 起移除了实验性的 `StdUnit.Tags.BlazorLib`(各驱动通道描述符的查看器/编辑器)。它从未对外发布,功能已由 `StdUnit.Tags.WebUi` 的设计器覆盖;需要图形化配置请用 WebUi。 相关测试统一放在 `tests/` 下的两个测试项目中: - `StdUnit.Tags.Tests`: 上述子项目的自动化测试(多目标 `net8.0` + `net472`)。 @@ -126,26 +154,58 @@ dotnet new tags.driver -n your-project.name -D YourDriver | Rx扩展 | `StdUnit.Tags.RxExtensions` | ✅ 支持 | | R3扩展 | `StdUnit.Tags.R3Extensions` | ✅ 支持 | | McpServer扩展 | `StdUnit.Tags.McpServer` | ✅ 支持 | -| BlazorLibCore扩展 | `StdUnit.Tags.BlazorLib.Core` | ✅ 支持 | | Web 界面(监控 + 设计器) | `StdUnit.Tags.WebUi` | 🧪 实验 | +| BlazorLib扩展 | `StdUnit.Tags.BlazorLib.Core` | ✅ 支持(维护模式) | -上表列出的包中,标记为“实验”的,`..` 里的 `` 跳变可能包含破坏性更新;标记为“支持”的,只有 `` 跳变才可能包含破坏性更新。核心包(`StdUnit.Tags`、`StdUnit.Tags.Core`)不属于驱动/扩展、因此不在此表内,按语义化版本处理——同样只有 `` 跳变才可能包含破坏性更新。 +上表列出的包中,标记为“实验”的,`..` 里的 `` 跳变可能包含破坏性更新; +标记为“支持”的,只有 `` 跳变才可能包含破坏性更新。核心包(`StdUnit.Tags`、`StdUnit.Tags.Core`)不属于驱动/扩展、因此不在此表内,按语义化版本处理——同样只有 `` 跳变才可能包含破坏性更新。 > 警告:有一些未在本仓库中列出的驱动及扩展,却由我发布到公开的`nuget.org`上以及私有的测试源上(比如[`StdUnit.Tags.LinuxFs.ProcInfo`](https://www.nuget.org/packages/StdUnit.Tags.LinuxFs.ProcInfo)、[`StdUnit.Tags.WinUsbKeyboardCodeScanners`](https://www.nuget.org/packages/StdUnit.Tags.WinUsbKeyboardCodeScanners/)),只供内部使用——那部分包不对外提供任何质量保证,请谨慎使用。 +### 运行期观测(Metrics) + +`StdUnit.Tags` 用 `System.Diagnostics.Metrics` 暴露入口的运行期指标。net8.0 用共享框架里的实现; +**net472 会因此引入 `System.Diagnostics.DiagnosticSource` 依赖**(`StdUnit.Tags.Core` 仍是零外部依赖)。 + +| 指标 | 类型 | 单位 | 维度 | +|---|---|---|---| +| `stdunit.tags.turns` | `Counter` | `{turn}` | `entry` | +| `stdunit.tags.turn.duration` | `Histogram` | `s` | `entry` | +| `stdunit.tags.failures` | `Counter` | `{failure}` | `entry` | +| `stdunit.tags.reconnects` | `Counter` | `{reconnect}` | `entry` | + +- Meter 名固定为 `StdUnit.Tags`。 +- `entry` 是入口的定位路径(`TagGrp(a)/TagGrp(b)`,与加载期错误消息、`ITagGrpExtensions.GetLocationPath()` 同格式)。 +- **不**带测点名/地址维度(无界基数),也不带 `driver`(失败可能来自入口下的辅通道,标主通道会算错责任人)。 +- 指标名、单位与 tag 键属于对外契约:只会新增,不会改名。它们集中暴露在公开静态类 + `TagsMetricContract`(`MeterName` / `Turns` / `TurnDurationUnit` / `EntryTag` …)里,订阅与建视图时直接引用即可。 +- 没人订阅时记录是零分配、纳秒级的,所以没有“是否启用”的开关。 + +订阅方式二选一: + +```csharp +// OpenTelemetry +builder.Services.AddOpenTelemetry() + .WithMetrics(m => m.AddMeter(TagsMetricContract.MeterName)); +``` + +```powershell +# 或直接用 dotnet-counters 观察 +dotnet-counters monitor --counters StdUnit.Tags -p +``` + ### 给人类的 0. 我们为本类库编写了专门的文档和教程,部署在[https://tags.doc.stdunit.com](https://tags.doc.stdunit.com)。其中由浅入深地讲解了基本概念、常用写法、设计思路和驱动专题,也穿插了不少常见故障与排错手法。 1. 仓库内 [`docs/`](docs/) 放**框架性**内容:[核心模型](docs/核心模型.md)、[外部意图与死锁](docs/外部意图.md)、[扩展点](docs/扩展点.md)、[错误处理](docs/异常处理.md)、[设计决策与边界](docs/设计决策与边界/)(范围与运行期契约、[CI 取舍](docs/设计决策与边界/1.%20CI.md)、[兼容与命名](docs/设计决策与边界/2.%20兼容与命名.md)、[打包与发布](docs/设计决策与边界/3.%20打包与发布.md));详细使用说明见上一点。 2. 本仓库自带的 [Samples](https://github.com/StdUnit/StdUnit.Tags/tree/dev/samples):主要用于开发验证+喂狗。AOT 冒烟程序(`AotSmokeTest.*`)已挪到 [`tests/`](https://github.com/StdUnit/StdUnit.Tags/tree/dev/tests)。(其中 `samples/WpfDemo` 是 WPF 示例,依赖 Windows SDK,所以有意**不纳入到解决方案内**;有需要时,在本地`windows`上用 `dotnet build samples/WpfDemo/WpfDemo.csproj` 单独构建。) 3. 供新手熟悉功能的 [WPFDemo](https://github.com/StdUnit/StdUnit.Tags.WPFDemo):按分支演示功能。 -4. 对于已经开放给公众使用的包,每一个公开的接口、类、方法、属性都写了`XML`注释,所以通过`*.nupkg`安装后即有完整的智能提示,也就没必要另外再提供在线版的`API`文档了,有需要的可以自己用 [`docfx`](https://github.com/dotnet/docfx) 生成(唯一的例外是 `StdUnit.Tags.BlazorLib`:它是只是实验性的代码片段,只对团队内部开放,暂时不发布到公开源上)。 +4. 对于已经开放给公众使用的包,每一个公开的接口、类、方法、属性都写了`XML`注释,所以通过`*.nupkg`安装后即有完整的智能提示,也就没必要另外再提供在线版的`API`文档了,有需要的可以自己用 [`docfx`](https://github.com/dotnet/docfx) 生成。 ### 给AI的 AI 可以直接参考 [StdUnit.Tags —— 给 AI 的参考手册](https://tags.doc.stdunit.com/assets/999.AI.markdown)(机器可读的原始 Markdown),也可以先访问 ,那里是文档站给 AI 准备的索引。 - ## 目标框架 本项目家族同时支持 `net8.0` 与 `net472`(.NET Framework 4.7.2),以便逐步迁移中的旧系统也能用上同一套抽象: @@ -156,7 +216,7 @@ AI 可以直接参考 [StdUnit.Tags —— 给 AI 的参考手册](https://tags. | `StdUnit.Tags.RxExtensions` / `StdUnit.Tags.R3Extensions` | `net8.0` + `net472` | | `StdUnit.Tags.S7` / `ModbusTcp` / `Hjzk` / `ZLan` / `OpcUaClient` / `ComScanner` / `SimpleFiles` | `net8.0` + `net472` | | `StdUnit.Tags.McpServer` | `net8.0` + `net472`(经 `ModelContextProtocol` 核心包的 `netstandard2.0` 资产) | -| `StdUnit.Tags.BlazorLib` / `BlazorLib.Core` | 仅 `net8.0` | +| `StdUnit.Tags.BlazorLib.Core` | 仅 `net8.0` | | `StdUnit.Tags.WebUi` | 仅 `net8.0`(ASP.NET Core;依赖 `Microsoft.AspNetCore.App` 框架引用) | | `StdUnit.Tags.SchemaGenerator` | `netstandard2.0`(源生成器) | diff --git a/StdUnit.Tags.sln b/StdUnit.Tags.sln index c1f8fc14..714db319 100644 --- a/StdUnit.Tags.sln +++ b/StdUnit.Tags.sln @@ -1,4 +1,4 @@ -Microsoft Visual Studio Solution File, Format Version 12.00 +Microsoft Visual Studio Solution File, Format Version 12.00 # Visual Studio Version 18 VisualStudioVersion = 18.8.12023.21 MinimumVisualStudioVersion = 10.0.40219.1 @@ -11,8 +11,6 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Samples", "Samples", "{02EA EndProject Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "StdUnit.Tags", "src\StdUnit.Tags\StdUnit.Tags.csproj", "{9B38BA08-BC35-CB42-62F6-827CE718B8CB}" EndProject -Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "StdUnit.Tags.BlazorLib", "src\StdUnit.Tags.BlazorLib\StdUnit.Tags.BlazorLib.csproj", "{90B26840-43C9-9104-B6C2-B2F315D241E1}" -EndProject Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "StdUnit.Tags.BlazorLib.Core", "src\StdUnit.Tags.BlazorLib.Core\StdUnit.Tags.BlazorLib.Core.csproj", "{B22AB846-B36E-8482-63DF-F55C07698852}" EndProject Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "StdUnit.Tags.ComScanner", "src\StdUnit.Tags.ComScanner\StdUnit.Tags.ComScanner.csproj", "{4363E7BE-55F3-E487-A37A-F5960CDE8A75}" @@ -68,6 +66,10 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "AotSmokeTest.WebUi", "tests EndProject Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "WebMonitor", "samples\WebMonitor\WebMonitor.csproj", "{018E69DC-830B-4DD4-BC68-7716821226E0}" EndProject +Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "benchmarks", "benchmarks", "{DFF2F2C3-1DDD-4DD3-B74C-1070B5EC17A0}" +EndProject +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "StdUnit.Tags.Benchmarks", "benchmarks\StdUnit.Tags.Benchmarks\StdUnit.Tags.Benchmarks.csproj", "{BC9D591B-BE00-422E-AE36-FD8FF31EE66B}" +EndProject Global GlobalSection(SolutionConfigurationPlatforms) = preSolution Debug|Any CPU = Debug|Any CPU @@ -78,10 +80,6 @@ Global {9B38BA08-BC35-CB42-62F6-827CE718B8CB}.Debug|Any CPU.Build.0 = Debug|Any CPU {9B38BA08-BC35-CB42-62F6-827CE718B8CB}.Release|Any CPU.ActiveCfg = Release|Any CPU {9B38BA08-BC35-CB42-62F6-827CE718B8CB}.Release|Any CPU.Build.0 = Release|Any CPU - {90B26840-43C9-9104-B6C2-B2F315D241E1}.Debug|Any CPU.ActiveCfg = Debug|Any CPU - {90B26840-43C9-9104-B6C2-B2F315D241E1}.Debug|Any CPU.Build.0 = Debug|Any CPU - {90B26840-43C9-9104-B6C2-B2F315D241E1}.Release|Any CPU.ActiveCfg = Release|Any CPU - {90B26840-43C9-9104-B6C2-B2F315D241E1}.Release|Any CPU.Build.0 = Release|Any CPU {B22AB846-B36E-8482-63DF-F55C07698852}.Debug|Any CPU.ActiveCfg = Debug|Any CPU {B22AB846-B36E-8482-63DF-F55C07698852}.Debug|Any CPU.Build.0 = Debug|Any CPU {B22AB846-B36E-8482-63DF-F55C07698852}.Release|Any CPU.ActiveCfg = Release|Any CPU @@ -174,6 +172,10 @@ Global {018E69DC-830B-4DD4-BC68-7716821226E0}.Debug|Any CPU.Build.0 = Debug|Any CPU {018E69DC-830B-4DD4-BC68-7716821226E0}.Release|Any CPU.ActiveCfg = Release|Any CPU {018E69DC-830B-4DD4-BC68-7716821226E0}.Release|Any CPU.Build.0 = Release|Any CPU + {BC9D591B-BE00-422E-AE36-FD8FF31EE66B}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {BC9D591B-BE00-422E-AE36-FD8FF31EE66B}.Debug|Any CPU.Build.0 = Debug|Any CPU + {BC9D591B-BE00-422E-AE36-FD8FF31EE66B}.Release|Any CPU.ActiveCfg = Release|Any CPU + {BC9D591B-BE00-422E-AE36-FD8FF31EE66B}.Release|Any CPU.Build.0 = Release|Any CPU EndGlobalSection GlobalSection(SolutionProperties) = preSolution HideSolutionNode = FALSE @@ -202,6 +204,7 @@ Global {1B85FF35-7A81-4CB7-924A-441EC3DA9218} = {2215F920-F9B4-4801-88A1-5F3E3E65B9CA} {87CBE561-3796-48DE-B121-E7534B49FE45} = {B9E1E3A0-6B7E-4A15-AB8C-CB5E3FFB29C8} {018E69DC-830B-4DD4-BC68-7716821226E0} = {02EA681E-C7D8-13C7-8484-4AC65E1B71E8} + {BC9D591B-BE00-422E-AE36-FD8FF31EE66B} = {DFF2F2C3-1DDD-4DD3-B74C-1070B5EC17A0} EndGlobalSection GlobalSection(ExtensibilityGlobals) = postSolution SolutionGuid = {6FF52024-3F01-4AC2-B991-CEE89ACF9FFC} diff --git a/backlog.md b/backlog.md index 85d9e28d..c045d66d 100644 --- a/backlog.md +++ b/backlog.md @@ -1,23 +1,41 @@ # Backlog / 开发计划 -> **v1.0 之前的 todo 已全部完成。** 其中的决策与理由("当时为什么这么选")已按专题整理到 -> [docs/设计决策与边界/](docs/设计决策与边界/)(范围与契约、CI、兼容与命名、打包与发布、错误处理), -> 本文件此后**只保留"还要做什么"**。 - -## v1.0 之后的 todo - -- [ ] 公开面基线工具(`Microsoft.CodeAnalysis.PublicApiAnalyzers` + `PublicAPI.Shipped.txt`):留到 v1.1 之后。 -- [ ] 日志、报错提示、注释文档的多语言支持。 -- [ ] 代码评审后续项(背景与理由见 `docs/设计决策与边界/`): - - [ ] **通道的资源释放完整性**:`ModbusTcpChannel.Dispose()` 只 `Close()` 掉 `TcpClient`,没有释放 `_connSignal`(`SemaphoreSlim`);且 `DisconnectAsync()` 不参与 `_connSignal` 的互斥,`EnsureConnectedAsync` 与它并发时可能"断开后被重连"。`OpcUaClientTagChannel.Dispose()` 只 `Close()` 会话。(根因"StopAsync 与循环并发"已修,这里只剩"Dispose 不完整"的洁癖级问题。) - - [x] ~~**跨驱动一致性**:`TagChannelDescriptor_S7Extensions` 这个类名在 **Hjzk 与 ZLan** 里都是 S7 的复制粘贴残留~~ **已改**:改为 `TagChannelDescriptor_HjzkExtensions` / `TagChannelDescriptor_ZLanTcpExtensions`(1.0 未发布,此刻改名不构成破坏性变更)。 - - [ ] **重复代码收敛**(各驱动 `AddXxxSupport()` 的注册样板、`ToXxxTagChannelDescriptor` 的骨架、`FileAsyncCompat`、`FloatBitsCompat`、DI/DO 的 `Area` 谓词):建议收敛到 `StdUnit.Tags.Core` 或各驱动的公共位置。注意 `FileAsyncCompat`/`FloatBitsCompat` 是跨框架垫片,收敛时要保持"调用点无 `#if`"的既有约定。 - - [ ] **运行期观测**:用 `System.Diagnostics.Metrics` 暴露每轮耗时、失败次数、重连次数、意图被拒次数(日志对"长期趋势"无能为力)。 - - [ ] **热重载 API**(`ReloadAsync(root)`)与"写后读回校验"选项。 -- [ ] 工程化: - - [ ] 覆盖率门槛:`coverlet.collector` 已引入,但尚未设门槛; - - [ ] 启用 NetAnalyzers / `TreatWarningsAsErrors`。 -- [ ] Cache 性能优化:Modbus 读路径 cache 复用——`TagCbnt` 各驱动的 `ReadAsync` 每轮轮询换新 `Cache` 引用(如 `ModbusRegisterTagCbnt` 的 `this.Cache = regs`、位空间 `this.Cache = bits`),`CacheSize` 不变时可复用同一 `T[]` 消除每轮分配;需接口改动(`IModbusRegisterChannel.ReadRegistersAsync`/`IModbusBitsChannel.ReadBitsAsync` 改为写入预分配 buffer 返回元素数) -- [ ] S7 优化:底层基于 Sharp7 一个古老的实现,有两个优化的点: - - 底层通道基于 Sharp7 一个古老的同步实现,用了 `Thread` 伪装成异步接口。将来可以改成真异步(上层异步接口不需要变更)。说明:PLC的并发吞吐能力远小于上位机,而且目前已经在单通道做了串行轮询机制,所以这个改进的收益不大。(2026-10 更新:通道**读写**已改成诚实的同步方法,`Thread` 伪装现在只剩**连接/断开**两条路径。) - - [x] ~~底层有很多无谓的字节拷贝和内存分配操作,借助 C# 的 `Span` 和 `Memory` 可以大幅优化实现。~~ **已改**:Sharp7 0.8.x 的 `DBRead`/`MBRead`/`DBWrite`/`MBWrite` 接受 `Span`,因此通道读写改成"调用方提供缓冲区"的同步方法(`S7TagChannel.Read/Write`,带 `ct` 仅用于等待 I/O 互斥体时可取消)。缓冲区一路透到硬件层:组合式测点直接读写 `TagCbnt.Cache`,直接测点用 `stackalloc`——读/写两条路径都不再产生 `byte[]`。 +> 本文件只保留**还要做什么**;"当时为什么这么选"在 [docs/设计决策与边界/](docs/设计决策与边界/)。 +> **已评估、决定不做**的条目(公开面基线、`WriteIntent` 旧重载、热重载、S7 连接/断开真异步等)也记在那边—— +> 想推翻它们请改 `docs`,不要在本文件里重新开一条。 + +## 现状快照(2026-11-11) + +- 版本:`2.0.0-beta8` 已发布;**不再发 beta9**——beta8 之后由 `2.0.0-dev.<构建号>` 预发布通道直接接 `2.0.0` 正式版 + (预发布只剩 `-dev.*` 一种形态,alpha/beta/rc 停用,见 [3. 打包与发布](docs/设计决策与边界/3.%20打包与发布.md))。 +- **2.0.0 的独占窗口已经空了**:动公开面、动驱动内部、定包清单这三件事都已完成 + (删除 `BlazorLib`、驱动释放路径收敛、S7 通道简化、包清单定稿并写明 `BlazorLib.Core` 维护模式)。 + 剩下的是 2.0.0 发布前收尾与 2.1+ 的增量,**都不必挤在正式版之前**。 +- 构建:整解 `dotnet build StdUnit.Tags.sln -c Release` = 0 警告 0 错误(`src/` 已开 `TreatWarningsAsErrors`); + `StdUnit.Tags.Tests`(两个 TFM)与 `Tests.NetCoreOnly`(net8.0)都绿。 +- PR/push CI:整解构建(net8.0 + net472 编译)→ net8.0 主测试 → net8.0-only 测试 → + net472-on-mono → AOT 三件套 + WebMonitor publish。 +- 发布物与包清单以 [src/publish-packages.ps1](src/publish-packages.ps1) 为唯一准绳。 +- 运行期观测:`StdUnit.Tags` 已暴露 4 个 `System.Diagnostics.Metrics` 指标(`stdunit.tags.*`,维度只到 `entry`)。 +- 性能基准:[benchmarks/StdUnit.Tags.Benchmarks](benchmarks/StdUnit.Tags.Benchmarks)(在解决方案内,CI 只**编译**不运行)。 + +--- + +## 一、RC 前(只收尾,不动公开面) + +- [ ] **2.0 迁移指南**:把各 beta 的破坏性变更汇总成"1.x → 2.0 要改什么"。现在它们散落在 CHANGELOG 的十几条 + beta 条目里,且同一处 API 常被多轮迭代(`ITagGrpRunner` 的 event→属性、`TagsProjectEventArgs.IsStarted` + →扩展方法、S7 的 `CreateClientAndConnectAsync`→`CreateClientAndConnect`),按 beta 顺序读拼不出"我现在该怎么写"。 +- [ ] **发布前复核一次**:Windows 真机全 TFM、NativeAOT 产物、WebUi 端到端(release 工作流已覆盖,要有人看结果)。 +- [ ] **首次 push 后盯一次 CI**:新增的 net8.0-only 测试步骤还没在 GitHub 上跑过——确认 `--no-build` + 两步顺序 + 在 4 vCPU runner 上真能跑通,而不只是本地通过。 +- [ ] **定覆盖率算不算硬门槛**:codecov 已有 `patch 91%` + `project: auto ±5%`,但不确定它是不是 required check。 + 要么确认它已经在拦,要么明确"不拦"——别留成"看起来有、其实靠自觉"。 +- [ ] **XML 注释抽查**:README 承诺"每个公开成员都有注释",抽查一轮,重点是本次新增与改签名的成员。 + +--- + +## 二、2.1+(增量,不阻塞 2.0) + +- [ ] 日志 / 报错 / 注释文档的多语言支持——**不做预留性重构**,真要做时按资源内嵌整体改。 +- [ ] 分析器加码(`AnalysisMode=All`);`net472-on-mono` 从"硬性把关"转正或降级。 \ No newline at end of file diff --git a/benchmarks/Directory.Build.props b/benchmarks/Directory.Build.props new file mode 100644 index 00000000..81b268db --- /dev/null +++ b/benchmarks/Directory.Build.props @@ -0,0 +1,17 @@ + + + + + latest + enable + enable + false + false + + + diff --git a/benchmarks/README.md b/benchmarks/README.md new file mode 100644 index 00000000..50e4bcad --- /dev/null +++ b/benchmarks/README.md @@ -0,0 +1,216 @@ +# 性能基准(StdUnit.Tags.Benchmarks) + +> 本目录是**开发期工具**,不进入任何 NuGet 包(Paket 的 `Benchmarks` 组是 `storage: none`,工程 `IsPackable=false`)。 +> 它在解决方案内,所以 `dotnet build` 会编译它(防止 API 漂移后悄悄腐烂),但**不**参与 CI 的测试与 AOT 冒烟。 + +## 这份报告怎么读 + +- **只用于改动前后对比**:绝对耗时会随机器、runtime、编译选项变化,任何一行都不能当作对外性能承诺。 +- 全部为 `-c Release` 构建,开启 `[MemoryDiagnoser]`;`Allocated` 是单次操作的托管分配量。 +- 采集环境: + + | 项 | 值 | + |---|---| + | 软件版本 | `2.0.0-dev.261113.0930`(2.0.0 发布前的预发布基线) | + | 日期 | 2026-11-12 | + | BenchmarkDotNet | v0.15.8 | + | .NET SDK | 8.0.129(`net8.0`) | + | OS | Windows 10 22H2 (10.0.19045) | + | CPU | Intel Core i7-8700 3.20 GHz,6 物理 / 12 逻辑核 | + +## 怎么跑 + +```powershell +# 全部 +dotnet run -c Release --project benchmarks/StdUnit.Tags.Benchmarks -- --filter * + +# 单个类 +dotnet run -c Release --project benchmarks/StdUnit.Tags.Benchmarks -- --filter "*TagTree*" + +# 只验证"能编译、能跑一次"(秒级,不产生测量意义的数据) +dotnet run -c Release --project benchmarks/StdUnit.Tags.Benchmarks -- --filter "*" --job dry + +# 常驻内存(对象图)报告:BDN 不测这个,走单独模式 +dotnet run -c Release --project benchmarks/StdUnit.Tags.Benchmarks -- --footprint +``` + +--- + +## 1. 读遍历(`TagTreeReadBenchmarks`) + +一棵 N 个测点的树(均分到 10 个子组),叶子是纯内存假测点、通道是空实现,所以测到的只有读遍历、 +访问模式/使能判断与派发,与硬件、网络无关。 + +| 方法 | 点位 | Mean | Allocated | +|---|---|---|---| +| `NoOp`(基线) | — | 0.24 ns | 0 B | +| `ReadAsync` | 1 000 | 8.80 µs | **0 B** | +| `ReadAsync` | 10 000 | 92.22 µs | **0 B** | + +`NoOp`(直接返回 `Task.CompletedTask`,0 B)用来证明 `Allocated` 列不是基准装置自身的开销。 + +**结论**:读遍历每点约 **8.8–9.2 ns**,线性;**整轮零分配**。1 万点位的读约 0.092 ms。 +写遍历见 §2。 + +### 1.1 读遍历的成本拆解(`TraversalBreakdownBenchmarks`,10 000 个扁平叶子) + +| 逐层加回成本 | 总计 | 每点 | +|---|---|---| +| 纯数组遍历 | 4.91 µs | 0.49 ns | +| + 访问模式解析(`SearchAccessMode`,**未走缓存**) | 62.26 µs | 6.23 ns | +| + 派发 + 完成检查 | 19.62 µs | 1.96 ns | +| + 策略判断(R1W/WO)与派发 | 74.46 µs | 7.45 ns | +| 实际遍历(`TagUnion.ReadAsync`,含访问模式缓存命中) | **78.50 µs** | **7.85 ns** | +| `IsDirty`(经 `TagUnion` 分发) | 50.85 µs | 5.09 ns | +| `IsDirty`(扁平数组 + 直接读 `ITag.IsDirty`) | **23.95 µs** | **2.39 ns** | + +**结论**:逐级冒泡解析访问模式本身要 6.2 ns/点,但它是**配置期属性**,解析结果缓存在 +`TagUnion.CachedAccessMode` 上,热路径只做一次空值检查——所以实际遍历低于"裸解析"。 +剩下的就是每个节点必须做的记账(一次派发 + 策略判断 + 状态回写),已经接近下限。 + +## 2. 写遍历:干净 vs 少量脏 vs 全脏(`TagTreeDirtyWriteBenchmarks`) + +叶子是纯内存假测点(写方法不做设备 IO),因此量的是**框架的派发开销**;"脏"叶子用永不自动清脏的假测点表示, +所以不需要在迭代间重置状态。「0% 脏」那一列就是运行器在"无脏数据"时**跳过**的动作(见第 9 节)。 + +| 点位 | 0% 脏 | 1% 脏 | 100% 脏 | +|---|---|---|---| +| 1 000 | 8.02 µs | 7.93 µs | 8.13 µs | +| 10 000 | 83.80 µs | 81.10 µs | 86.87 µs | + +**结论**:写遍历的成本几乎全部来自**遍历本身**(每节点约 8 ns),"有多少节点真的被写"只带来个位数百分比的差异。 +所以"干净时跳过写遍历"(第 9 节)比"让写更便宜"更有价值。真实设备的写入耗时不在本表内。 + +## 3. `CbntFanOutBenchmarks` — “数千点位”的现实形态 + +一次硬件读之后,把值分发给 N 个子测点(组合式测点)。这是 5 000 点位项目的真实形状; +“N 个独立测点各读一次”是 N 次设备往返,现实中不存在,因此不作为基准。 + +| 子测点数 | Mean | Allocated | +|---|---|---| +| 1 000 | 2.12 µs | 72 B | +| 5 000 | 15.60 µs | 72 B | + +**结论**:每点 **2.1–3.1 ns**,逐点零分配(那 72 B 是基准桩里 `Task.FromResult` 的固定开销,不是框架的)。 + +## 4. `S7ChannelReadBenchmarks` — 读一块 DB + +用桩 `S7Client`(只占位、立即返回 0),测的是**我们这层**:地址解析、互斥体、`Span` 传递、错误码检查。 + +| 字节数 | Mean | Allocated | +|---|---|---| +| 1 000 | 606.3 ns | 832 B | +| 20 000 | 601.9 ns | 832 B | + +**结论**:单次读 < 1 µs,分配与字节数无关(零拷贝,缓冲区由调用方提供)。 +**真实耗时里 PLC 响应占绝对多数**,这组数字的用途是确认“我们不是瓶颈”。 +那 832 B 只发生在**直读点位**(`DirectTag`,兜底用法)——地址在每轮解析;组合式测点的地址只在加载期解析一次。 + +## 5. `ModbusCbntReadBenchmarks` — 通道数组的分配 + +组合式测点每轮读;用桩通道对比“每轮返回新数组”(NModbus 的形状)与“写入调用方预分配数组”。 + +| 寄存器数 | 通道返回新数组 | 复用缓冲区 | 耗时 | +|---|---|---|---| +| 32 | 160 B | 72 B | 30–35 ns | +| 125 | 352 B | 72 B | 30–40 ns | + +**结论**:每轮省 88–280 B,耗时无可测差异。按 100 Hz、单入口估算约 9–28 KB/s, +相对一次 Modbus TCP 往返可忽略;而"复用"需要改 `IModbusRegisterChannel` 的公开签名。 +**维持现状**(决策记录见 `docs/设计决策与边界/0. 设计决策与边界.md` §五)。 + +## 6. `MetricRecordingBenchmarks` — 打点开销 + +| 场景 | Mean | Allocated | +|---|---|---| +| 无监听者(默认部署) | 3.77 ns | 0 B | +| 有 `MeterListener` | 5.68 ns | 0 B | + +**结论**:没人订阅时零分配、纳秒级,所以指标常开没有代价;订阅后每轮多 ~2 ns。 + +## 7. 内存:1000 个点和 10000 个点,有影响吗? + +要分两种"内存"看: + +| | 是什么 | 与点位数的关系 | +|---|---|---| +| **每轮分配** | 每轮采集新产生的垃圾(`[MemoryDiagnoser]` 的 `Allocated`) | **无关**:都是 0 B | +| **常驻内存** | 加载后一直活着的对象图(测点、组合子、描述符) | **线性**:点位数 × 每点约 350–400 B | + +### 7.1 每轮分配:0 B,与点位数无关 + +遍历、组合分发、指标记录的 `Allocated` 都是 0(组合分发表里的 72 B 来自基准桩)。 +10 Hz × 10k 点位也不会产生可观测的 GC 压力。 + +### 7.2 常驻内存:严格线性 + +用 `--footprint` 测量(构建对象图前后各一次 full GC,取 `GC.GetTotalMemory(true)` 差值): + +| 形态 | 1 000 点 | 10 000 点 | 50 000 点 | 每点 | +|---|---|---|---|---| +| 树形(10 个子组) | 0.42 MB | 3.80 MB | 18.66 MB | ~391–440 B | +| 组合式(1 Cbnt + N 子测点) | 0.34 MB | 3.31 MB | 16.53 MB | ~347 B | + +- 常驻内存是**一次性、线性**的:1 万点位约 **3.3–3.8 MB**,5 万点位约 **16.5–18.7 MB**(托管对象图,不含 XML 源文本与业务数据),不构成部署障碍。 +- 组合式比树形略省(少一层测点对象与 `TagUnion` 包装),密集点位优先用组合式。 +- 这是**下限**:真实项目还会持有 XML、字符串与业务侧对象。 + +> 判断口径:**看"每轮分配"决定要不要优化**(影响 GC 频率),**看"常驻内存"决定能装多少点**(一次性的堆占用)。 + +## 8. `EnsureConnectedBenchmarks` — 每轮“我还活着吗”的成本 + +`TagGrpRunner` 每轮、每个通道都会 `EnsureConnectedAsync(force:false)`。Modbus 的存活探测用 +`Socket.Poll(SelectRead)` + `Available == 0` 判定,当前实现用 **0 超时**(非阻塞); +下表同时给出带超时的版本作对照——`Poll(1000)` 在 Windows 上受计时器粒度影响(≈15.6 ms)实际阻塞 **15.8 ms**。 + +| 方法 | Mean | +|---|---| +| `EnsureConnectedAsync`(已连接,当前实现) | **2.30 µs** | +| 原始 `Socket.Poll(0, SelectRead)` | 1.42 µs | +| 原始 `Socket.Poll(1000, SelectRead)` | 15.82 ms | +| 原始 `Socket.Connected` 标志 | 0.72 ns | + +**结论**:每轮每通道的存活探测固定开销约 **2.3 µs**(≈ `Poll(0)` + `Available` 的 ioctl)。 +表中 `Poll(1000)` 那一行说明"带超时的探测"在 Windows 上受计时器粒度影响(≈15.6 ms), +因此当前实现采用 0 超时——两者判定逻辑相同,差别只是否等待。 + +## 9. 运行器判脏索引(`DirtyNodeIndex`) + +运行器在每次(重)启动时把入口子树里的 `ITag` / `ITagCbnt` 收进两个扁平数组,判脏变成两次数组扫描; +干净时它还会跳过那趟必然空转的写遍历(§2 的「0% 脏」列,10k ≈ 82 µs)。 + +| 项目(10 000 节点) | 数值 | +|---|---| +| 判脏:`entry.IsDirty()`(递归 + `TagUnion` 分发) | 50.85 µs(5.09 ns/点) | +| 判脏:扁平索引(直接读 `ITag.IsDirty`) | **23.95 µs(2.39 ns/点)** | +| 干净树上的 `WriteAsync` | 81.36 µs —— **整趟跳过** | + +- 索引只收录 `ITag` / `ITagCbnt`,它们正是写单元(`WriteAsync` 只看这两类各自的 `IsDirty`); + `ITagCbnt` 可以独立为脏(整块缓存重写),所以必须收录组合本身。 +- 正确性依据是 `ITagGrp.IsDirty()` 与 `WriteAsync` 的一致性契约(见接口注释): + **返回 false 时写不得有任何动作;只要存在待写节点就必须返回 true**。它**不是**"父脏必有脏子"。 +- 等价性由 `DirtyNodeIndexTests` 保证(空树、脏 Tag、脏 Cbnt、嵌套组、混合树反复切换)。 + +--- + +## 结论速览 + +| 关注点 | 数字 | 含义 | +|---|---|---| +| 框架遍历 | **8.8–9.2 ns/点、每轮 0 B** | 1 万点约 0.092 ms/轮,不产生垃圾 | +| 组合分发 | **2.1–3.1 ns/点、逐点零分配** | 点位多本身不是瓶颈 | +| 判脏 | **2.4 ns/点**(扁平索引) | 10k ≈ 24 µs;干净时还跳过约 82 µs 的空写遍历 | +| 写遍历 | 8 ns/点(10k ≈ 81–87 µs),**与脏比例几乎无关** | 成本在"走一遍",不在"写多少个" | +| 每轮存活探测(Modbus) | **2.3 µs/通道** | 非阻塞探测(`Poll(0)` + `Available`)的固定成本 | +| S7 通道读 | 0.60 µs/次、832 B | 仅影响DirectTag(非`TagCbnt`的兜底用法),PLC 决定实际耗时 | +| Modbus 通道数组 | 每轮 160–352 B | 不值得改公开接口复用缓冲区 | +| 指标记录 | 3.77 ns / 0 B(订阅后 5.68 ns) | 可常开 | +| 常驻内存 | **~350–400 B/点**;1k≈0.4 MB、10k≈3.5 MB、50k≈17 MB | 一次性、线性,不构成部署障碍 | + +## 维护约定 + +- 新增基准:一个类一个关注点,`[MemoryDiagnoser]` 必开;**必须**能说明“这组数字能/不能得出什么结论”, + 避免把桩实现或回环网络的结果当成端到端性能。 +- 基准结果不设门槛(机器差异会让它变成随机红);它只用来做改动前后对比。 +- 改动热路径(遍历、组合通知、驱动读写、判脏)时,请顺手更新本文件的对应表格——**数字过期比没有更糟**。 +- 改了点位的对象结构(新增字段/包装层)时,记得重跑 `--footprint`:常驻内存是**每点 ~350 B** 的线性量。 \ No newline at end of file diff --git a/benchmarks/StdUnit.Tags.Benchmarks/BenchFakes.cs b/benchmarks/StdUnit.Tags.Benchmarks/BenchFakes.cs new file mode 100644 index 00000000..eed26a39 --- /dev/null +++ b/benchmarks/StdUnit.Tags.Benchmarks/BenchFakes.cs @@ -0,0 +1,35 @@ +using System.Threading; +using System.Threading.Tasks; + +namespace StdUnit.Tags.Benchmarks; + +/// 空实现通道:只为了让测点能挂上,不做任何 IO。 +internal sealed class BenchChannel : ITagChannel +{ + public TagChannelDescriptor Descriptor { get; } = new() { Name = "bench", Driver = "Bench" }; + + public Task EnsureConnectedAsync(bool force, CancellationToken ct) => Task.CompletedTask; + + public Task DisconnectAsync(CancellationToken ct) => Task.CompletedTask; + + public void Dispose() + { + } +} + +/// 纯内存测点:Read/Write 立即完成,只留下遍历与判定的成本。 +internal sealed class BenchLeafTag : Tag +{ + public BenchLeafTag(TagDescriptor descriptor, BenchChannel channel, ITagGrp parent) + : base(descriptor, channel, TagContainer.From(parent)) + { + } + + public override Task ReadAsync(CancellationToken ct) => Task.CompletedTask; + + public override Task WriteAsync(CancellationToken ct) + { + IsDirty = false; + return Task.CompletedTask; + } +} diff --git a/benchmarks/StdUnit.Tags.Benchmarks/CbntFanOutBenchmarks.cs b/benchmarks/StdUnit.Tags.Benchmarks/CbntFanOutBenchmarks.cs new file mode 100644 index 00000000..ab3ecf71 --- /dev/null +++ b/benchmarks/StdUnit.Tags.Benchmarks/CbntFanOutBenchmarks.cs @@ -0,0 +1,78 @@ +using System; +using System.Threading; +using System.Threading.Tasks; +using BenchmarkDotNet.Attributes; +using StdUnit.Tags.ModbusTcp; + +namespace StdUnit.Tags.Benchmarks; + +/// +/// "数千点位"的真实形态:一次硬件读(组合式测点)之后,把值分发给 N 个子测点。
+/// 这与"N 个独立测点各读一次"完全不同——那是 N 次设备往返,现实中不会这么用; +/// 框架真正花时间的地方在遍历、通知与脏标记,也正是容易被写成 O(n²) 的地方。
+/// 通道返回复用缓冲区(不分配),所以测到的就是分发成本;硬件读本身由 量。 +///
+[MemoryDiagnoser] +[SimpleJob(warmupCount: 3, iterationCount: 5)] +public class CbntFanOutBenchmarks +{ + /// 组合下的子测点数(每个 Int16 占 1 个寄存器)。 + [Params(1_000, 5_000)] + public int ChildCount { get; set; } + + private ModbusRegisterTagCbnt _cbnt = null!; + + [GlobalSetup] + public void Setup() + { + var channel = new ReusingStubChannel(); + _cbnt = new ModbusRegisterTagCbnt(new TagCbntDescriptor + { + Name = "bench", + StartAddress = "40001", + }) + { + Channel = channel, + }; + _cbnt.ResizeCache(ChildCount * sizeof(ushort)); + + for (var i = 0; i < ChildCount; i++) + { + var child = new ModbusRegisterInt16Cbntor( + new TagDescriptor { TagName = $"t{i}" }, + _cbnt, + tagOffset: i * sizeof(ushort), + isReadOnly: false); + // 组合子不会自己挂进 Children,必须显式登记(与 OpcUa 等驱动的做法一致)。 + _cbnt.Children.Add(child.TagName(), child); + } + + // 构造方式写错(子节点没挂上)会让基准变成"测一个空组合",直接失败比输出假数据好。 + if (_cbnt.Children.Count != ChildCount) + { + throw new InvalidOperationException($"预期挂上 {ChildCount} 个子测点,实际 {_cbnt.Children.Count}"); + } + } + + [Benchmark] + public Task ReadAsync() => _cbnt.ReadAsync(CancellationToken.None); + + private sealed class ReusingStubChannel : IModbusRegisterChannel { + private readonly ushort[] _buffer = new ushort[5_000]; + + public TagChannelDescriptor Descriptor { get; } = new() { Name = "bench", Driver = "ModbusTcp" }; + + public Task EnsureConnectedAsync(bool force, CancellationToken ct) => Task.CompletedTask; + + public Task DisconnectAsync(CancellationToken ct) => Task.CompletedTask; + + public void Dispose() + { + } + + public Task ReadRegistersAsync(string address, int registerCount, CancellationToken ct) + => Task.FromResult(_buffer); + + public Task WriteRegistersAsync(string address, ReadOnlyMemory registers, CancellationToken ct) => Task.CompletedTask; + } +} diff --git a/benchmarks/StdUnit.Tags.Benchmarks/EnsureConnectedBenchmarks.cs b/benchmarks/StdUnit.Tags.Benchmarks/EnsureConnectedBenchmarks.cs new file mode 100644 index 00000000..d181d9a9 --- /dev/null +++ b/benchmarks/StdUnit.Tags.Benchmarks/EnsureConnectedBenchmarks.cs @@ -0,0 +1,77 @@ +using System; +using System.Net; +using System.Net.Sockets; +using System.Threading; +using System.Threading.Tasks; +using BenchmarkDotNet.Attributes; +using Microsoft.Extensions.Logging.Abstractions; +using StdUnit.Tags.ModbusTcp; + +namespace StdUnit.Tags.Benchmarks; + +/// +/// 每轮“我还活着吗”的成本: 在已连接时只做一次存活探测, +/// 而它的实现里有 Socket.Poll(1000, SelectRead)——链路空闲时会**阻塞满 1 ms** 才返回。
+/// 这组基准把这条路径与“读 `Socket.Connected` 标志”“Poll(0) 快检”放在一起对比, +/// 用来判断是否值得改探测策略。真实网络里 PLC 的响应时间与此无关,这里只量框架自己的开销。 +///
+[MemoryDiagnoser] +[SimpleJob(warmupCount: 3, iterationCount: 5)] +public class EnsureConnectedBenchmarks +{ + private TcpListener _listener = null!; + private Socket _serverSide = null!; + private Socket _rawClient = null!; + private ModbusTcpChannel _channel = null!; + + [GlobalSetup] + public void Setup() + { + _listener = new TcpListener(IPAddress.Loopback, 0); + _listener.Start(); + var port = ((IPEndPoint)_listener.LocalEndpoint).Port; + + // 一对裸 socket:用于对比 Poll(1000) 与 Connected 标志 + var accept1 = _listener.AcceptSocketAsync(); + _rawClient = new Socket(AddressFamily.InterNetwork, SocketType.Stream, ProtocolType.Tcp); + _rawClient.Connect(IPAddress.Loopback, port); + _serverSide = accept1.GetAwaiter().GetResult(); + + // 通道连到另一个监听端口(复用同一个 listener 再接受一次连接) + var accept2 = _listener.AcceptSocketAsync(); + _channel = new ModbusTcpChannel( + new ModbusTcpTagChannelDescriptor { Name = "bench", IpAddr = "127.0.0.1", Port = port }, + NullLogger.Instance); + _channel.EnsureConnectedAsync(force: false, CancellationToken.None).GetAwaiter().GetResult(); + _ = accept2.GetAwaiter().GetResult(); // 保住服务端 socket,避免被 GC 关掉 + + // 预热一次,确认 Connected 判定稳定 + _channel.EnsureConnectedAsync(force: false, CancellationToken.None).GetAwaiter().GetResult(); + } + + [GlobalCleanup] + public void Cleanup() + { + _channel.Dispose(); + _rawClient.Dispose(); + _serverSide.Dispose(); + _listener.Stop(); + } + + /// 热路径现状:每轮每通道调用一次(已连接时应为“无操作”)。 + [Benchmark(Baseline = true)] + public Task EnsureConnected_AlreadyConnected() + => _channel.EnsureConnectedAsync(force: false, CancellationToken.None); + + /// 现状里真正花时间的那一步:空闲连接上最多阻塞 1000 微秒。 + [Benchmark] + public bool Socket_Poll1000_SelectRead() => _rawClient.Poll(1000, SelectMode.SelectRead); + + /// 替代方案 A:只读标志位(不产生系统调用级等待)。 + [Benchmark] + public bool Socket_ConnectedFlag() => _rawClient.Connected; + + /// 替代方案 B:非阻塞快检(Poll 0 + 有无数据)。 + [Benchmark] + public bool Socket_Poll0_SelectRead() => _rawClient.Poll(0, SelectMode.SelectRead); +} diff --git a/benchmarks/StdUnit.Tags.Benchmarks/MemoryFootprintReport.cs b/benchmarks/StdUnit.Tags.Benchmarks/MemoryFootprintReport.cs new file mode 100644 index 00000000..7e607bbb --- /dev/null +++ b/benchmarks/StdUnit.Tags.Benchmarks/MemoryFootprintReport.cs @@ -0,0 +1,119 @@ +using System; +using StdUnit.Tags.ModbusTcp; + +namespace StdUnit.Tags.Benchmarks; + +/// +/// 常驻内存报告:点位数从 1k 增到 10k 时,对象图增长多少。
+/// 这与 `[MemoryDiagnoser]` 的 `Allocated` 是两件事:后者是"每轮产生的垃圾",前者是"进程里一直占着的东西"。 +/// BenchmarkDotNet 不测后者的差值,所以这里单独跑一遍(--footprint 模式)。
+/// 测量方式:构建对象图前后各做一次完整 GC + ,取差值。 +///
+internal static class MemoryFootprintReport +{ + private static readonly int[] TagCounts = { 1_000, 10_000, 50_000 }; + + public static void Run() + { + Console.WriteLine("常驻内存(对象图)报告 —— 构建前后各一次 full GC 后取 GC.GetTotalMemory(true) 的差值"); + Console.WriteLine(); + Console.WriteLine("| 形态 | 点位数 | 常驻增量 | 每点 |"); + Console.WriteLine("|---|---|---|---|"); + + foreach (var count in TagCounts) + { + Report("树形(10 个子组)", count, () => BuildTree(count)); + } + + foreach (var count in TagCounts) + { + Report("组合式(1 个 Cbnt + N 子测点)", count, () => BuildCbnt(count)); + } + } + + private static void Report(string shape, int count, Func build) + { + // 先 GC 一次把前面迭代的残留清掉,再取基线。 + GC.Collect(); + GC.WaitForPendingFinalizers(); + GC.Collect(); + var before = GC.GetTotalMemory(forceFullCollection: true); + + var graph = build(); + + GC.Collect(); + GC.WaitForPendingFinalizers(); + GC.Collect(); + var after = GC.GetTotalMemory(forceFullCollection: true); + + GC.KeepAlive(graph); + + var delta = after - before; + var perTag = (double)delta / count; + Console.WriteLine($"| {shape} | {count:N0} | {ToMb(delta)} | {perTag:F0} B |"); + } + + private static string ToMb(long bytes) => $"{bytes / 1024.0 / 1024.0:F2} MB"; + + private static object BuildTree(int tagCount) + { + var channel = new BenchChannel(); + var root = new TagGrp(new TagGrpDescriptor { Name = "root" }, channel); + const int groupCount = 10; + var perGroup = tagCount / groupCount; + for (var g = 0; g < groupCount; g++) + { + var group = new TagGrp(new TagGrpDescriptor { Name = $"g{g}" }, channel); + for (var i = 0; i < perGroup; i++) + { + group.AddTag(new BenchLeafTag(new TagDescriptor { TagName = $"t{i}" }, channel, group)); + } + + root.AddTag(group); + } + + return root; + } + + private static object BuildCbnt(int childCount) + { + var cbnt = new ModbusRegisterTagCbnt(new TagCbntDescriptor { Name = "bench", StartAddress = "40001" }) + { + Channel = new NullModbusChannel(), + }; + cbnt.ResizeCache(childCount * sizeof(ushort)); + + for (var i = 0; i < childCount; i++) + { + var child = new ModbusRegisterInt16Cbntor( + new TagDescriptor { TagName = $"t{i}" }, + cbnt, + tagOffset: i * sizeof(ushort), + isReadOnly: false); + cbnt.Children.Add(child.TagName(), child); + } + + return cbnt; + } + + private sealed class NullModbusChannel : IModbusRegisterChannel + { + private static readonly ushort[] Buffer = new ushort[50_000]; + + public TagChannelDescriptor Descriptor { get; } = new() { Name = "bench", Driver = "ModbusTcp" }; + + public Task EnsureConnectedAsync(bool force, System.Threading.CancellationToken ct) => System.Threading.Tasks.Task.CompletedTask; + + public Task DisconnectAsync(System.Threading.CancellationToken ct) => System.Threading.Tasks.Task.CompletedTask; + + public void Dispose() + { + } + + public Task ReadRegistersAsync(string address, int registerCount, System.Threading.CancellationToken ct) + => System.Threading.Tasks.Task.FromResult(Buffer); + + public Task WriteRegistersAsync(string address, ReadOnlyMemory registers, System.Threading.CancellationToken ct) + => System.Threading.Tasks.Task.CompletedTask; + } +} diff --git a/benchmarks/StdUnit.Tags.Benchmarks/MetricRecordingBenchmarks.cs b/benchmarks/StdUnit.Tags.Benchmarks/MetricRecordingBenchmarks.cs new file mode 100644 index 00000000..72a91e58 --- /dev/null +++ b/benchmarks/StdUnit.Tags.Benchmarks/MetricRecordingBenchmarks.cs @@ -0,0 +1,50 @@ +using System.Collections.Generic; +using System.Diagnostics.Metrics; +using BenchmarkDotNet.Attributes; + +namespace StdUnit.Tags.Benchmarks; + +/// +/// 指标记录本身的开销——验证 README 里那句"没人订阅时零分配、纳秒级"。
+/// 两个参数只差一件事:是否有人 订阅。若两者差距显著, +/// 就说明"打点"在热路径上是有代价的,设计需要重新评估。 +///
+[MemoryDiagnoser] +[SimpleJob(warmupCount: 3, iterationCount: 5)] +public class MetricRecordingBenchmarks +{ + /// true = 挂一个 MeterListener(真实采集);false = 没人订阅(默认部署形态)。 + [Params(false, true)] + public bool WithListener { get; set; } + + private KeyValuePair[] _tags = null!; + private MeterListener? _listener; + private readonly System.TimeSpan _elapsed = System.TimeSpan.FromMilliseconds(1); + + [GlobalSetup] + public void Setup() + { + _tags = new[] { new KeyValuePair(TagsMetricContract.EntryTag, "TagGrp(bench)") }; + + if (WithListener) + { + _listener = new MeterListener + { + InstrumentPublished = (instrument, l) => + { + if (instrument.Meter.Name == TagsMetricContract.MeterName) + { + l.EnableMeasurementEvents(instrument); + } + } + }; + _listener.Start(); + } + } + + [GlobalCleanup] + public void Cleanup() => _listener?.Dispose(); + + [Benchmark] + public void RecordTurn() => TagsMetric.RecordTurn(_tags, _elapsed); +} diff --git a/benchmarks/StdUnit.Tags.Benchmarks/ModbusCbntReadBenchmarks.cs b/benchmarks/StdUnit.Tags.Benchmarks/ModbusCbntReadBenchmarks.cs new file mode 100644 index 00000000..5af3ebcd --- /dev/null +++ b/benchmarks/StdUnit.Tags.Benchmarks/ModbusCbntReadBenchmarks.cs @@ -0,0 +1,79 @@ +using System; +using System.Threading; +using System.Threading.Tasks; +using BenchmarkDotNet.Attributes; +using StdUnit.Tags.ModbusTcp; + +namespace StdUnit.Tags.Benchmarks; + +/// +/// Modbus 组合式测点(TagCbnt<ushort>)每轮读的分配与耗时。
+/// 它回答 backlog 里"cache 复用值不值得改公开接口":对比"通道每轮返回新数组"(现状)与 +/// "通道写入调用方预分配数组"(需要改 )。
+/// 用桩通道而不是真 socket:网络往返的噪声与分配量无关,而结论要的正是分配量。 +///
+[MemoryDiagnoser] +[SimpleJob(warmupCount: 3, iterationCount: 5)] +public class ModbusCbntReadBenchmarks +{ + /// 每次读的寄存器数(125 是 FC03/FC04 的单帧上限)。 + [Params(32, 125)] + public int RegisterCount { get; set; } + + /// true = 模拟"通道写入调用方数组"(cache 复用后的形态)。 + [Params(false, true)] + public bool ReuseCache { get; set; } + + private ModbusRegisterTagCbnt _cbnt = null!; + + [GlobalSetup] + public void Setup() + { + var channel = new StubChannel(ReuseCache); + _cbnt = new ModbusRegisterTagCbnt(new TagCbntDescriptor + { + Name = "bench", + StartAddress = "40001", + }) + { + Channel = channel, + }; + _cbnt.ResizeCache(RegisterCount * sizeof(ushort)); + } + + [Benchmark] + public Task ReadAsync() => _cbnt.ReadAsync(CancellationToken.None); + + private sealed class StubChannel : IModbusRegisterChannel + { + private readonly bool _reuse; + private readonly ushort[] _buffer = new ushort[128]; + + public StubChannel(bool reuse) => _reuse = reuse; + + public TagChannelDescriptor Descriptor { get; } = new() { Name = "bench", Driver = "ModbusTcp" }; + + public Task EnsureConnectedAsync(bool force, CancellationToken ct) => Task.CompletedTask; + + public Task DisconnectAsync(CancellationToken ct) => Task.CompletedTask; + + public void Dispose() + { + } + + public Task ReadRegistersAsync(string address, int registerCount, CancellationToken ct) + { + // 现状:每轮一个新数组(NModbus 的 ReadHoldingRegistersAsync 就是这个形状)。 + // 复用:把值写进同一块缓冲区再返回——这正是"改接口"之后能省下的那块分配。 + if (!_reuse) + { + return Task.FromResult(new ushort[registerCount]); + } + + Array.Clear(_buffer, 0, registerCount); + return Task.FromResult(_buffer); + } + + public Task WriteRegistersAsync(string address, ReadOnlyMemory registers, CancellationToken ct) => Task.CompletedTask; + } +} diff --git a/benchmarks/StdUnit.Tags.Benchmarks/Program.cs b/benchmarks/StdUnit.Tags.Benchmarks/Program.cs new file mode 100644 index 00000000..ac1cf57f --- /dev/null +++ b/benchmarks/StdUnit.Tags.Benchmarks/Program.cs @@ -0,0 +1,24 @@ +using BenchmarkDotNet.Running; + +namespace StdUnit.Tags.Benchmarks; + +/// +/// 基准入口。
+/// 本地跑:dotnet run -c Release --project benchmarks/StdUnit.Tags.Benchmarks -- --filter *
+/// 只做冒烟(每个基准执行一次,秒级):追加 --job dry。
+/// 常驻内存报告(对象图大小,BDN 不测这个):-- --footprint。
+/// 基准不进 CI 的测试步骤:完整测量需要几分钟且依赖机器状态,只作为改动前后的对比工具。 +///
+public static class Program +{ + public static void Main(string[] args) + { + if (args.Length > 0 && args[0] == "--footprint") + { + MemoryFootprintReport.Run(); + return; + } + + BenchmarkSwitcher.FromAssembly(typeof(Program).Assembly).Run(args); + } +} diff --git a/benchmarks/StdUnit.Tags.Benchmarks/S7ChannelReadBenchmarks.cs b/benchmarks/StdUnit.Tags.Benchmarks/S7ChannelReadBenchmarks.cs new file mode 100644 index 00000000..97edebf6 --- /dev/null +++ b/benchmarks/StdUnit.Tags.Benchmarks/S7ChannelReadBenchmarks.cs @@ -0,0 +1,49 @@ +using System; +using System.Threading; +using BenchmarkDotNet.Attributes; +using Microsoft.Extensions.Logging.Abstractions; +using StdUnit.Sharp7; +using StdUnit.Tags.S7; + +namespace StdUnit.Tags.Benchmarks; + +/// +/// S7 通道层读一块 DB 的开销(20 000 字节 ≈ 现场常见的整块采集)。
+/// 用桩 (只把数据搬进缓冲区、立即返回 0),所以测到的是我们这层的 +/// 地址解析、互斥体、Span 传递与错误码检查;真实耗时里 PLC 的响应时间占绝对多数, +/// 这组数字的用途是确认"我们不是瓶颈",以及防止将来在这条路径上引入拷贝/分配。 +///
+[MemoryDiagnoser] +[SimpleJob(warmupCount: 3, iterationCount: 5)] +public class S7ChannelReadBenchmarks +{ + /// 每次读的字节数。 + [Params(1_000, 20_000)] + public int ByteCount { get; set; } + + private S7TagChannel _channel = null!; + private byte[] _buffer = null!; + + [GlobalSetup] + public void Setup() + { + _channel = new S7TagChannel( + new S7TagChannelDescriptor { Name = "bench", IpAddr = "127.0.0.1" }, + NullLogger.Instance) + { + Client = new CopyingS7Client(), + }; + _buffer = new byte[ByteCount]; + } + + [Benchmark] + public void Read() => _channel.Read("DB1.100", _buffer, CancellationToken.None); + + /// 真实 S7Client 的替代品:只做一次内存拷贝,用来隔离"我们这层"的成本。 + private sealed class CopyingS7Client : S7Client + { + public override int DBRead(int dbNumber, int start, int size, Span buffer) => 0; + + public override int MBRead(int start, int size, Span buffer) => 0; + } +} diff --git a/benchmarks/StdUnit.Tags.Benchmarks/StdUnit.Tags.Benchmarks.csproj b/benchmarks/StdUnit.Tags.Benchmarks/StdUnit.Tags.Benchmarks.csproj new file mode 100644 index 00000000..f3520834 --- /dev/null +++ b/benchmarks/StdUnit.Tags.Benchmarks/StdUnit.Tags.Benchmarks.csproj @@ -0,0 +1,25 @@ + + + + Exe + + net8.0 + + true + + $(NoWarn);CS9057 + + + + + + + + + + + \ No newline at end of file diff --git a/benchmarks/StdUnit.Tags.Benchmarks/TagTreeDirtyWriteBenchmarks.cs b/benchmarks/StdUnit.Tags.Benchmarks/TagTreeDirtyWriteBenchmarks.cs new file mode 100644 index 00000000..73e4356a --- /dev/null +++ b/benchmarks/StdUnit.Tags.Benchmarks/TagTreeDirtyWriteBenchmarks.cs @@ -0,0 +1,70 @@ +using System.Threading; +using System.Threading.Tasks; +using BenchmarkDotNet.Attributes; + +namespace StdUnit.Tags.Benchmarks; + +/// +/// 写遍历的框架成本,按"脏节点比例"分档(0% / 1% / 100%)。
+/// 叶子是纯内存假测点:WriteAsync 不做任何设备 IO,所以量的是**框架的派发开销** +/// (遍历 + 每个节点的策略判断 + 调用写方法),不含真实设备的写入耗时。
+/// 实现上不用 [IterationSetup] 重置脏标记(那会把运行策略切成 ColdStart,测出来的不是吞吐): +/// 而是让"脏"叶子用一个永远保持脏的假测点,指标循环里状态恒定。 +///
+[MemoryDiagnoser] +[SimpleJob(warmupCount: 3, iterationCount: 5)] +public class TagTreeDirtyWriteBenchmarks +{ + /// 叶子测点总数(均分到 10 个子组里)。 + [Params(1_000, 10_000)] + public int TagCount { get; set; } + + /// "已脏"的叶子比例。 + [Params(0, 1, 100)] + public int DirtyPercent { get; set; } + + private TagGrp _root = null!; + + [GlobalSetup] + public void Setup() + { + var channel = new BenchChannel(); + _root = new TagGrp(new TagGrpDescriptor { Name = "root" }, channel); + + const int groupCount = 10; + var perGroup = TagCount / groupCount; + var dirtyPerGroup = perGroup * DirtyPercent / 100; + + for (var g = 0; g < groupCount; g++) + { + var group = new TagGrp(new TagGrpDescriptor { Name = $"g{g}" }, channel); + for (var i = 0; i < perGroup; i++) + { + // 脏叶子:WriteAsync 不清脏,所以每轮都会真的被"写"一次; + // 干净叶子:初始就干净,且不会变脏。 + group.AddTag(i < dirtyPerGroup + ? new AlwaysDirtyTag(new TagDescriptor { TagName = $"d{i}" }, channel, group) + : new BenchLeafTag(new TagDescriptor { TagName = $"c{i}" }, channel, group)); + } + + _root.AddTag(group); + } + } + + [Benchmark] + public Task WriteAsync() => _root.WriteAsync(TraversalMode.IgnoreEnabled, CancellationToken.None); + + /// 永远保持脏的叶子:写方法不改变脏标记,因此每轮都会走到"写"分支。 + private sealed class AlwaysDirtyTag : Tag + { + public AlwaysDirtyTag(TagDescriptor descriptor, BenchChannel channel, ITagGrp parent) + : base(descriptor, channel, TagContainer.From(parent)) + { + IsDirty = true; + } + + public override Task ReadAsync(CancellationToken ct) => Task.CompletedTask; + + public override Task WriteAsync(CancellationToken ct) => Task.CompletedTask; + } +} \ No newline at end of file diff --git a/benchmarks/StdUnit.Tags.Benchmarks/TagTreeReadBenchmarks.cs b/benchmarks/StdUnit.Tags.Benchmarks/TagTreeReadBenchmarks.cs new file mode 100644 index 00000000..5f0e5db7 --- /dev/null +++ b/benchmarks/StdUnit.Tags.Benchmarks/TagTreeReadBenchmarks.cs @@ -0,0 +1,52 @@ +using System.Threading; +using System.Threading.Tasks; +using BenchmarkDotNet.Attributes; + +namespace StdUnit.Tags.Benchmarks; + +/// +/// "框架自身"的每轮开销:一棵 N 个测点的树,叶子全是纯内存假测点、通道也是空实现, +/// 因此测到的只有遍历、使能/脏标记判断与派发——与硬件、网络无关。
+/// 用途:给"每轮框架开销"一个数量级(例如"1 万点位的框架开销是几百 µs 还是几十 ms"), +/// 并作为回归基线;真实吞吐永远由设备与会话决定,不要用这组数字对外承诺端到端性能。 +///
+[MemoryDiagnoser] +[SimpleJob(warmupCount: 3, iterationCount: 5)] +public class TagTreeReadBenchmarks +{ + /// 叶子测点总数(均分到 10 个子组里)。 + [Params(1_000, 10_000)] + public int TagCount { get; set; } + + private TagGrp _root = null!; + + [GlobalSetup] + public void Setup() + { + var channel = new BenchChannel(); + _root = new TagGrp(new TagGrpDescriptor { Name = "root" }, channel); + + const int groupCount = 10; + var perGroup = TagCount / groupCount; + for (var g = 0; g < groupCount; g++) + { + var group = new TagGrp(new TagGrpDescriptor { Name = $"g{g}" }, channel); + for (var i = 0; i < perGroup; i++) + { + group.AddTag(new BenchLeafTag(new TagDescriptor { TagName = $"t{i}" }, channel, group)); + } + + _root.AddTag(group); + } + } + + /// + /// 基准框架的自身开销基线:返回已完成 Task,不做任何事。
+ /// `Allocated` 若与真实调用相同,说明那点分配来自"BDN 等待一个 Task 返回的测量装置",不是被测代码。 + ///
+ [Benchmark(Baseline = true)] + public Task NoOp() => Task.CompletedTask; + + [Benchmark] + public Task ReadAsync() => _root.ReadAsync(TraversalMode.IgnoreEnabled, CancellationToken.None); +} diff --git a/benchmarks/StdUnit.Tags.Benchmarks/TraversalBreakdownBenchmarks.cs b/benchmarks/StdUnit.Tags.Benchmarks/TraversalBreakdownBenchmarks.cs new file mode 100644 index 00000000..2b90ec05 --- /dev/null +++ b/benchmarks/StdUnit.Tags.Benchmarks/TraversalBreakdownBenchmarks.cs @@ -0,0 +1,156 @@ +using System.Threading; +using System.Threading.Tasks; +using BenchmarkDotNet.Attributes; + +namespace StdUnit.Tags.Benchmarks; + +/// +/// 把一个"每点位 ~38 ns"拆开:纯循环 / 访问模式查询 / 同步派发 / 全部组合 / 真实的 TagUnion 异步遍历。
+/// 目的是回答"瓶颈在哪"——不是猜,而是逐层加回成本,看每层增加多少 ns。
+/// 全部用扁平数组(10 000 个叶子),避免树形与字典开销混进来;叶子是纯内存假测点。 +///
+[MemoryDiagnoser] +[SimpleJob(warmupCount: 3, iterationCount: 5)] +public class TraversalBreakdownBenchmarks +{ + private const int NodeCount = 10_000; + + private ITag[] _tags = null!; + private TagUnion[] _unions = null!; + + [GlobalSetup] + public void Setup() + { + var channel = new BenchChannel(); + var root = new TagGrp(new TagGrpDescriptor { Name = "root" }, channel); + _tags = new ITag[NodeCount]; + _unions = new TagUnion[NodeCount]; + for (var i = 0; i < NodeCount; i++) + { + var tag = new BenchLeafTag(new TagDescriptor { TagName = $"t{i}" }, channel, root); + _tags[i] = tag; + _unions[i] = new TagUnion.TagUnit(tag); + } + } + + /// 基线:数组遍历本身(+ 一次空判断),不含任何框架调用。 + [Benchmark(Baseline = true)] + public int Loop_Only() + { + var n = 0; + foreach (var t in _tags) + { + if (t is not null) + { + n++; + } + } + + return n; + } + + /// 只加"访问模式解析"(每次读要做两次:R1W 判定 + IsWriteOnly)。 + [Benchmark] + public int SearchAccessMode_Only() + { + var n = 0; + foreach (var t in _tags) + { + n += (int)t.SearchAccessMode(); + } + + return n; + } + + /// 只加"派发 + 完成检查"(理想快路径:同步完成时不进 async 机制)。 + [Benchmark] + public int SyncDispatch_Only() + { + var n = 0; + foreach (var t in _tags) + { + if (t.ReadAsync(CancellationToken.None).IsCompletedSuccessfully) + { + n++; + } + } + + return n; + } + + /// 把上面几层按真实顺序组合起来——这就是"最优实现"能到的上界。 + [Benchmark] + public int SyncDispatch_WithPolicy() + { + var n = 0; + foreach (var t in _tags) + { + var mode = t.SearchAccessMode(); + if (mode == TagAccessMode.R1W && t.IsScanned) + { + continue; + } + + if (mode == TagAccessMode.WO) + { + continue; + } + + if (t.ReadAsync(CancellationToken.None).IsCompletedSuccessfully) + { + t.IsScanned = true; + n++; + } + } + + return n; + } + + /// 现状:走 的异步遍历(每个节点一次 async 包装 + switch)。 + [Benchmark] + public async Task UnionReadAsync() + { + foreach (var union in _unions) + { + await union.ReadAsync(TraversalMode.IgnoreEnabled, CancellationToken.None).ConfigureAwait(false); + } + } + + /// + /// 扁平索引 + 直接读 :在 runner 里预先收集所有可写节点的做法, + /// 每次判脏只需一次数组遍历 + 一次属性读,不做字典递归。 + /// + [Benchmark] + public int IsDirty_DirectArray() + { + var n = 0; + foreach (var tag in _tags) + { + if (tag.IsDirty) + { + n++; + } + } + + return n; + } + + /// + /// 每轮开头运行器还会调一次 entry.IsDirty():全树干净时要走完所有子节点。 + /// 这是"每轮固定成本"里除读之外的另一大块,所以单独量。 + /// + [Benchmark] + public int IsDirty_All() + { + var n = 0; + foreach (var union in _unions) + { + if (union.IsDirty()) + { + n++; + } + } + + return n; + } +} diff --git a/benchmarks/StdUnit.Tags.Benchmarks/paket.references b/benchmarks/StdUnit.Tags.Benchmarks/paket.references new file mode 100644 index 00000000..7fbc6e78 --- /dev/null +++ b/benchmarks/StdUnit.Tags.Benchmarks/paket.references @@ -0,0 +1,2 @@ +group Benchmarks + BenchmarkDotNet \ No newline at end of file diff --git "a/docs/\346\211\251\345\261\225\347\202\271.md" "b/docs/\346\211\251\345\261\225\347\202\271.md" index 66398dc4..d9a319f2 100644 --- "a/docs/\346\211\251\345\261\225\347\202\271.md" +++ "b/docs/\346\211\251\345\261\225\347\202\271.md" @@ -9,7 +9,7 @@ StdUnit.Tags.Core 硬件无关的核心抽象 + 项目 XML 的 schema └── StdUnit.Tags 项目 / 日志 / 插件 / DI,仍与硬件无关 ├── 驱动包:S7 / ModbusTcp / OpcUaClient / ComScanner / SimpleFiles / Hjzk / ZLan(后者基于 ModbusTcp) - ├── McpServer / BlazorLib 把项目暴露给 AI / 界面 + ├── McpServer / WebUi 把项目暴露给 AI / 界面(原 Blazor.Core 已转维护模式,新界面建议 WebUi) └── RxExtensions / R3Extensions 只依赖 Core,用于订阅测点事件 应用:只引用需要的驱动包 + 接口 + DI 扩展 ``` diff --git "a/docs/\350\256\276\350\256\241\345\206\263\347\255\226\344\270\216\350\276\271\347\225\214/0. \350\256\276\350\256\241\345\206\263\347\255\226\344\270\216\350\276\271\347\225\214.md" "b/docs/\350\256\276\350\256\241\345\206\263\347\255\226\344\270\216\350\276\271\347\225\214/0. \350\256\276\350\256\241\345\206\263\347\255\226\344\270\216\350\276\271\347\225\214.md" index 33ea3f3e..a823af37 100644 --- "a/docs/\350\256\276\350\256\241\345\206\263\347\255\226\344\270\216\350\276\271\347\225\214/0. \350\256\276\350\256\241\345\206\263\347\255\226\344\270\216\350\276\271\347\225\214.md" +++ "b/docs/\350\256\276\350\256\241\345\206\263\347\255\226\344\270\216\350\276\271\347\225\214/0. \350\256\276\350\256\241\345\206\263\347\255\226\344\270\216\350\276\271\347\225\214.md" @@ -4,7 +4,7 @@ | 文档 | 内容 | |---|---| -| **本文** | 范围边界、模型与运行期契约、性能取舍、已知限制、尚未定稿 | +| **本文** | 范围边界、模型与运行期契约、性能取舍、已知限制、尚未定稿、已评估但不做 | | [1. CI](./1.%20CI.md) | CI/OS 取舍、Linux 上跑 net472(mono)、测试的跨平台与稳定性 | | [2. 兼容与命名](./2.%20兼容与命名.md) | 破坏性变更、兼容残留(保留/移除/推迟) | | [3. 打包与发布](./3.%20打包与发布.md) | 版本通道(正式/迭代)、破坏性变更代价、发布流程、包元数据与授权、依赖版本策略 | @@ -34,6 +34,9 @@ API 细节见教程站点()。 - **一个通道实例只能属于一个入口**,由默认开启的 `EntryChannelExclusivityValidator` 强制。理由不只是"断开互相踩"(连接动作可以是空实现,如 SimpleFiles):两套扫描周期会交错读写同一底层资源,两个入口的生命周期也被耦合;而要求分离的代价几近为零——再声明一个指向同一设备的 `Channel` 即可。 - 因此**"单通道多入口并发"明确不做**:它已经不是潜在缺陷,而是"有明确报错的既定约束"。真要做,必须先放弃上面这条设计(见 `AGENTS.md` 约束 3),代价远大于收益。 - **只有最外层入口才是入口**:`ScanEntries` 遇到入口即停止下探,嵌套 `isEntry="true"` 不生效(该子树由外层入口轮询),错误配置由默认开启的 `NestedEntryValidator` 拒绝。 +- **驱动不需要自己防"连接/断开并发"**:上面两条合起来就推出了这个结论——通道与入口一一对应,入口内部每轮是一条单链 `await`(`EnsureConnectedAsync` 循环 → 处理写意图 → 写 → 读 → 逻辑 → 写),断开只发生在循环退出之后(崩溃/取消清理)或停机超时兜底,而超时兜底后的新启动会被 `OnStartingException` 拒绝。所以 `EnsureConnectedAsync` 与 `DisconnectAsync` 在模型内不会并发。 + - 推论:为"可能的并发"加的信号量、以及"`SemaphoreSlim` 没 `Dispose` 会泄漏"这两类担心都不成立(`SemaphoreSlim.Dispose()` 只有在访问过 `AvailableWaitHandle` 时才真正释放内核对象)。**再提"驱动连接要加互斥"时,先回到本节。** + - 驱动真正要守的是另一件事:**`Dispose()` 与 `DisconnectAsync()` 必须是同一条释放路径**,且**无条件释放**——不要用 `TcpClient.Connected` / `Session.Connected` 当守卫,它只是上次 I/O 的快照,半死连接上返回 `false`,恰好把最该关的句柄留了下来。 - **加载期校验器默认开启、XSD 校验默认关闭**:跨引用、驱动工厂、入口通道独占、嵌套入口这 4 个"代码校验器"在 `UseDefaults = true` 下默认生效(它们只拒绝**确定错误**的配置,且错误信息带完整路径);XSD 校验是 opt-in(`EnableXmlSchemaValidation()`),因为"配置合法但语义不对"才是主要失效模式,且它需要显式引入 schema。 ### 观测方式:事件驱动,不要跨线程读字段 @@ -94,7 +97,41 @@ API 细节见教程站点()。 - **只做"显然该做"的优化,并说清量级**。例:OpcUa 每轮都要"子测点 ↔ NodeId"映射 → 改为按子节点集合懒构建缓存(读/写共用),并做数量校验(万一加载后增删子节点就重建,而不是静默错位)。省下的是 LINQ/字符串哈希/两次 `List` 分配,**相对一次 OPC UA 往返(ms 级)可以忽略**;收益是"不再每轮做显然重复的事"与减少 GC 压力,不是吞吐瓶颈。 - **两趟遍历有意保留**(先写完整个缓存再逐点通知):与 `TagCbnt.NotifyChildrenRead()` 语义一致——处理器里读同组其它测点不该看到半更新的缓存;合并省下的开销可忽略。 -- 已知的优化空间(未做)见 `backlog.md`(Modbus cache 复用、S7 真异步与 `Span`)。 +- **遍历与通知路径必须零分配,且不要在热点路径上做委托调用**(2026-11 三轮修复,都是行为等价的): + 1. `TagUnionExtensions.ReadAsync/WriteAsync` 原先用 `TagUnion.Map` 传三个 `async` 闭包,单节点约 220 B + (闭包 + 委托 + 状态机),1 万点位**每轮 2.19 MB**;改用 `switch`。 + 2. `TagGrp.Children` / `TagCbnt.Children` 是 `IDictionary`,`foreach` 走接口会**装箱 `Dictionary.Enumerator`**, + 而它在每轮的读、写、判脏与通知路径上。改为内部存具体 `Dictionary`、公开属性仍返回 `IDictionary`(API 不变)。 + 3. `SearchAccessMode` 原来用 `TagContainer.Map` + 两个委托,且每点位要查**两次**(R1W 判定 + `IsWriteOnly`); + 改为 `TagContainer.AccessMode` 的 `switch`、只查一次,并给 `ReadAsync` 加"读同步完成就不进 async 机制"的快路径。 + 4. **`access` 的继承修正为逐级冒泡**:此前只有 `ITagGrp` 沿父链递归,`ITag`/`ITagCbnt` 只查"直接父级自己配了没", + `Grp(RO) → Cbnt(未配) → Tag` 会被判成 `RW`。这是**语义修正**,不是性能优化。 + 同时因为**访问模式是配置期属性**(加载后不再变化),解析结果缓存在 `TagUnion.CachedAccessMode` 上: + 每节点一生只解析一次,热路径只剩空值检查。**运行期修改 `Descriptor.AccessMode` 不生效,需重新加载项目。** + 结果:遍历 `1 000 → 8.7 µs / 0 B`、`10 000 → 94 µs / 0 B`(每点 8.7–9.4 ns); + 组合分发 `5 000 子测点 → 12.8 µs / 逐点零分配`。 + 规则:**热点路径不要用 `Map` + 闭包/委托做分派或取值,也不要用 `IDictionary` 接口去 `foreach`**。 +- **每轮的存活探测必须是非阻塞的**:Modbus 的 `Connected` 原先用 `Socket.Poll(1000, SelectRead)` 判断链路, + 而 Windows 的计时器粒度约 15.6 ms —— 空闲连接上这一步实测 **15.9 ms/次**,且发生在每轮、每个通道的 + `EnsureConnectedAsync` 里(100 Hz 扫描根本不可能达成)。改为 `Poll(0)`(判定逻辑不变:`Poll && Available == 0`)后 + 降到 **2.3 µs**。规则:**每轮路径上不要用带超时的 `Poll`/`select` 做探测**;要么非阻塞,要么靠"读失败 → 崩溃 → 重连"。 + 基准见 `EnsureConnectedBenchmarks`。 +- **运行器的判脏走扁平索引,且干净时不要空写**:`TagGrpRunner` 每次(重)启动时把入口子树的 + `ITag` / `ITagCbnt` 收进 `DirtyNodeIndex`(两个数组),每轮判脏从"递归走 `Children` + `TagUnion` 分发" + (5.2 ns/点)降到两次数组扫描(2.6 ns/点);干净时**不再执行那趟必然空转的 `WriteAsync`**(10k 点位约 81 µs)。 + 两条约束:① 正确性依据是 `ITagGrp.IsDirty()` 与 `WriteAsync` 的**一致性契约**—— + "`IsDirty()` 为 false 时 `WriteAsync` 不得写入任何东西;只要子树里存在待写节点 + (`ITag` 或 `ITagCbnt` 自身的 `IsDirty`)就必须为 true"(已写进接口注释)。 + 注意它**不是**"父脏必有脏子":`ITagCbnt.IsDirty` 可以独立为 true(整块缓存重写), + 而索引收录的正是 Tag 与组合本身,所以这种情形不会被漏掉。实现违反契约会让"该写的没写",且没有编译错误; + ② 树结构假定加载后不变(索引随 `CollectChannels()` 同周期重建)。 +- **S7 地址解析的正则提升为静态只读**:原先每次 `Parse` 都 `new Regex(...)`(实测约 10 KB + 5 µs/次), + 而解析发生在每轮读写上。静态化后单次读 6.2 µs/10.49 KB → **596 ns/832 B**。 + 这 832 B 只影响**直读点位**(`DirectTag`,兜底用法);正常把点位组织成 `TagCbnt` 时地址只解析一次加载, + 所以不再继续优化(去正则改 span 手写解析的收益只落在这条兜底路径上)。 +- 这组数字都可用 `benchmarks/StdUnit.Tags.Benchmarks` 复现(`TagTreeReadBenchmarks` / `TagTreeDirtyWriteBenchmarks` / `CbntFanOutBenchmarks` / + `S7ChannelReadBenchmarks`;常驻内存用 `--footprint`);基准**不**进 CI,只作改动前后的对比工具。 +- 已知的优化空间(未做)见 `backlog.md`(Modbus cache 复用)。S7 的读写已经改成了"调用方提供缓冲区 + `Span`"的零拷贝实现;但连接/断开的"真异步"已评估、决定不做,理由见第五节。 ## 四、已知限制 @@ -110,3 +147,24 @@ API 细节见教程站点()。 - 是否需要 `TagSnapshot`(值 + 时间戳的一致读取)。 - 是否需要 `System.Diagnostics.Metrics` 观测(每轮耗时、失败次数、重连次数、意图被拒次数)。 - 是否需要"写后读回校验"选项。 + +### 已评估、决定不做(2026-11) + +记在这里的理由是"别再被提出来一次";其中若有哪条被推翻,请改本节而不是只改 backlog。 + +- **热重载 `ReloadAsync(root)`**:它要解决的事其实就是 `StopAsync` 接 `StartPollAsync`,没有独立价值,不再单列 API。 +- **S7 连接/断开的"真异步"**:收益极低——PLC 的并发吞吐远小于上位机,且入口内部本来就是串行轮询; + 2026-11 起 `Thread` 包装也已删掉(连接/断开就是同步调用,有界由 Sharp7 自己的超时保证),读/写则是 + "调用方提供缓冲区 + `Span`"的零拷贝同步实现。**不要**再为它们引入异步 I/O 抽象。 +- **Modbus 读路径 cache 复用**(把 `IModbusRegisterChannel.ReadRegistersAsync` / `IModbusBitsChannel.ReadBitsAsync` + 改成"写入调用方预分配 buffer"):2026-11 用基准量过(`benchmarks/StdUnit.Tags.Benchmarks`,桩通道 + `[MemoryDiagnoser]`): + + | 每轮寄存器数 | 现状(通道返回新数组) | 复用 Cache | 耗时差 | + |---|---|---|---| + | 32 | 160 B | 72 B | 无可测差异(~31 ns vs ~31 ns) | + | 125 | 352 B | 72 B | 无可测差异(~38 ns vs ~30 ns,抖动大于差距) | + + 按 100 Hz、单入口估算,省下的是 9–28 KB/s —— 相对一次 Modbus TCP 往返(ms 级,且 NModbus 自己还有缓冲分配) + 可以忽略;代价却是**公开接口签名变更**(net472 没有默认接口方法兜底)。结论:不做。 + (基准里剩下的 72 B 是 `Task` 与通知路径的固定开销,与 cache 复用无关。) +- **公开面基线(`PublicApiAnalyzers` / 反射快照测试)**:前者因额外依赖不引入,后者因"关键保证要零反射可验证"的 AOT 取向不采用;详见 `backlog.md` 第二节。 diff --git "a/docs/\350\256\276\350\256\241\345\206\263\347\255\226\344\270\216\350\276\271\347\225\214/1. CI.md" "b/docs/\350\256\276\350\256\241\345\206\263\347\255\226\344\270\216\350\276\271\347\225\214/1. CI.md" index 983d9d00..d0205b60 100644 --- "a/docs/\350\256\276\350\256\241\345\206\263\347\255\226\344\270\216\350\276\271\347\225\214/1. CI.md" +++ "b/docs/\350\256\276\350\256\241\345\206\263\347\255\226\344\270\216\350\276\271\347\225\214/1. CI.md" @@ -9,7 +9,7 @@ CI 强制测试(`.github/workflows/dotnet.yml` 构建+测试、发版见 `rele 策略:发布新版只通过云端跑完整的在线自动化构建、测试、发版,不应该在本地强推。 -已分化完成:`release-nuget.yml`(正式版 → nuget.org,走 OIDC 临时密钥)与 `release-baget.yml`(预览/内部验证 → 私有源)。`1.0.0` 已于 2026-10-07 发布到 nuget.org。 +已分化完成:`release-nuget.yml`(正式版 → nuget.org,走 OIDC 临时密钥)与 `release-baget.yml`(常规版预览 + `dev` 开发版 → 私有源,入口是 `versionKind` 下拉)。`1.0.0` 已于 2026-10-07 发布到 nuget.org。 ### 构建(`dotnet.yml`) diff --git "a/docs/\350\256\276\350\256\241\345\206\263\347\255\226\344\270\216\350\276\271\347\225\214/2. \345\205\274\345\256\271\344\270\216\345\221\275\345\220\215.md" "b/docs/\350\256\276\350\256\241\345\206\263\347\255\226\344\270\216\350\276\271\347\225\214/2. \345\205\274\345\256\271\344\270\216\345\221\275\345\220\215.md" index c4cd863e..fb1af155 100644 --- "a/docs/\350\256\276\350\256\241\345\206\263\347\255\226\344\270\216\350\276\271\347\225\214/2. \345\205\274\345\256\271\344\270\216\345\221\275\345\220\215.md" +++ "b/docs/\350\256\276\350\256\241\345\206\263\347\255\226\344\270\216\350\276\271\347\225\214/2. \345\205\274\345\256\271\344\270\216\345\221\275\345\220\215.md" @@ -14,10 +14,14 @@ ## 二、明确保留的兼容残留 -部分早已标记废弃的代码和`typo`问题,理论上可以在`1.0`移除,但是考虑到已经在生产现场使用,所以决定**暂时先不移除**,留待在`2.0`移除: +部分早已标记废弃的代码和`typo`问题,理论上可以在`1.0`移除,但是考虑到已经在生产现场使用,所以决定**暂时先不移除**。 -- `ITagsProject.WriteIntent(string, TagGrpWriteIntent)` 的 `[Obsolete]` 2 参重载(本仓库零调用,但库外有真实调用方)。 -- ComScanner 的旧元素名 `` 的兼容解析(XSD 已把该写法标为非法,新配置请写 ``)。 +**2.0 复查结论(2026-11):这两项仍然不移除。** 移除它们换来的只是"公开面更干净",代价却是给现场再制造一次破坏性变更; +它们都没有实际维护成本,因此**不设移除时间点**,也不再为它们去凑"下一个大版本窗口"。 + +- `ITagsProject.WriteIntent(string, TagGrpWriteIntent)` 的 `[Obsolete]` 2 参重载(本仓库零调用,但库外有真实调用方): + 它只是一层转发,零维护成本。 +- ComScanner 的旧元素名 `` 的兼容解析(XSD 已把该写法标为非法,新配置请写 ``):只是一段 fallback。 ## 三、已在 1.1 里改掉的(仅 `StdUnit.Tags.ModbusTcp`) diff --git "a/docs/\350\256\276\350\256\241\345\206\263\347\255\226\344\270\216\350\276\271\347\225\214/3. \346\211\223\345\214\205\344\270\216\345\217\221\345\270\203.md" "b/docs/\350\256\276\350\256\241\345\206\263\347\255\226\344\270\216\350\276\271\347\225\214/3. \346\211\223\345\214\205\344\270\216\345\217\221\345\270\203.md" index 6b3e1978..980f52ab 100644 --- "a/docs/\350\256\276\350\256\241\345\206\263\347\255\226\344\270\216\350\276\271\347\225\214/3. \346\211\223\345\214\205\344\270\216\345\217\221\345\270\203.md" +++ "b/docs/\350\256\276\350\256\241\345\206\263\347\255\226\344\270\216\350\276\271\347\225\214/3. \346\211\223\345\214\205\344\270\216\345\217\221\345\270\203.md" @@ -9,23 +9,48 @@ | 通道 | 版本号 | 谁在用 | 承诺 | |---|---|---|---| -| **正式发布** | `2.0.0` / `2.0.0-beta2` / `1.1.0`(语义化版本) | 现场用户 | 遵守 README 里"支持/实验"的分级约定 | -| **迭代产物** | `2.0.0-dev..`(**构建号,不是语义化版本**) | 自己与公测者 | **不承诺任何兼容性**,只作"提前试" | - -分级约定仍写在 README(那里是给使用者读的):标记为"实验"的包,`` 跳变就可能包含破坏性更新; -标记为"支持"的只有 `` 跳变才可能破坏;核心包(`StdUnit.Tags`、`StdUnit.Tags.Core`)不属于驱动/扩展,按语义化版本处理。 - -迭代产物由 CI 产出,**不发布到任何包源**(`dotnet.yml` 的 `build` job,push 到 `main`/`dev` 时执行): -从该次构建页面的 Artifacts 下载 `dev-packages.zip`,解压成一个文件夹源即可: +| **正式发布** | `2.0.0` / `1.1.0`(语义化版本) | 现场用户 | 遵守 README 里"支持/实验"的分级约定 | +| **开发版(dev)** | `<下一个正式号>-dev.<构建号>`,如 `2.0.0-dev.261113.0930` | 自己、公测者、现场复现 | **不承诺任何兼容性**,只作"提前试" | + +**预发布只有 `-dev.<构建号>` 一种形态**(2.0.0 起实际采用,3.0.0 起严格如此): +不再新增 `alpha` / `beta` / `rc`——1.x 与 2.0 早先的 `beta1..beta8` 只是历史版本号,不追溯改名。 +这么定不是为了少一个标签,而是排序:`-dev.*` 天然排在"同线已有的 beta 之后、正式版之前", +收敛成一种之后就不存在"新发的预发布反而比旧版更旧"(混用 `beta` 与 `dev` 才会踩)。 + +**构建号由机器生成,人不用填**:UTC 的 `yyMMdd.HHmm`(如 `261113.0930`)。 +三个出口用同一条规则、同一个格式: + +| 出口 | 谁触发 | 落到哪 | +|---|---|---| +| 迭代产物 | CI 每次 push 到 `main`/`dev`(`date -u +%y%m%d.%H%M`) | **不推任何源**,只作为构建页面的 Artifacts(`dev-packages.zip`) | +| 内部试用 | `release-baget.yml` 的 `versionKind=dev` | 私有源 baget(现场复现 / 内部验证) | +| **公测** | `release-nuget.yml`,`versionKind=dev` | **nuget.org**(预发布位,任何人 `--prerelease` 可装) | + +> **为什么公测也走 dev 号**:alpha/beta/rc 已停用,`-dev.*` 是唯一的预发布形态。若只允许发到私有源, +> 等于没有公开的公测通道——外部用户连"提前试"的入口都没有。 +> +> **但别把日常 dev 包都推上去**:nuget.org 上的版本**不可撤销**(只能 unlist),日常 CI 每次都产包, +> 全推会让版本列表被几百个时间戳淹没、`--prerelease` 也会默认解析到最新的一个日常包。 +> 所以 `release-nuget.yml` 里选 `dev` 应当是一次**有意识的"这次要公测"**(而不是日常发布); +> 不想让它被 `--prerelease` 选中时,发布后到 nuget.org 手动 unlist(版本仍在,知道号的人可以精确安装)。 +> 私有源那一侧不受此约束,仍可随意发。 + +> 为什么不用"本月第几版"这类由人给的序号:那要人来数,而且 CI 与手工发布得各维护一套编号; +> 两套编号一旦混进同一个源,数字段比较会让它们互相压过。时间戳单调、唯一、零输入,同一个公式两边都能算。 +> 一分钟内重复发布会撞号,撞上时 `--skip-duplicate` 会**静默跳过**(流水线仍绿、包没更新),重跑一次即可。 + +解压 Artifacts 成一个文件夹源即可: ```powershell dotnet nuget add source <解压目录> -n stdunit-dev ``` -它刻意挂在"下一个计划发布的正式号"的预发布位上:排序上低于该正式号(正式版一发就自然覆盖), -又高于此前任何正式版(装了它仍能正常往前走,不会出现版本降级);每次构建号唯一, -所以既不需要人工判断"这算 minor 还是 major",也不占任何正式号位。 -**不要基于迭代产物做长期依赖**——它随时可能不再产出,也没有任何兼容性保证。 +排序上 `2.0.0-beta8` < `2.0.0-dev.261113.0930` < `2.0.0`:装了开发版的人仍能正常升到正式版, +正式版一发就自然覆盖预发布,预发布也不占任何正式号位。 +**不要基于开发版做长期依赖**——它随时可能不再产出,也没有任何兼容性保证。 + +分级约定仍写在 README(那里是给使用者读的):标记为"实验"的包,`` 跳变就可能包含破坏性更新; +标记为"支持"的只有 `` 跳变才可能破坏;核心包(`StdUnit.Tags`、`StdUnit.Tags.Core`)不属于驱动/扩展,按语义化版本处理。 ## 二、破坏性变更的代价 @@ -38,27 +63,46 @@ dotnet nuget add source <解压目录> -n stdunit-dev ## 三、发布流程 -- 版本号**不写在 csproj 里**,由 `src/publish-packages.ps1` 在打包时以 `-p:PackageVersion=…` 注入: - - **正式发布**:`release-nuget.yml` / `release-baget.yml` 的 `workflow_dispatch` 输入 `releaseVersion` - → `-packageVersion <语义化版本>`,对 13 个项目逐个 `dotnet pack -c Release -p:PackageVersion=…` + `nuget push`。 - 号由人显式给,不从文件推断(nuget.org 上的版本不可撤销,且"这次算 minor 还是 major"本身就是兼容性决策)。 - - **迭代产物(dev 通道)**:CI 只传构建号 `-DevBuildNumber "."`,基础版本读仓库根的 - `next-release-version.txt`(单行,如 `2.0.0`),拼成 `<基础版本>-dev.<构建号>`。这样"下一个计划发布的正式号" - 只有**一处**来源,workflow 里不再出现版本字面量。 +- 版本号**不写在 csproj 里**,由 `src/publish-packages.ps1` 在打包时注入**两个**属性: + `-p:PackageVersion=…`(包版本)与 `-p:InformationalVersion=…`(程序集里的版本信息)。 + 后者不注入的话会默认派生自 `$(Version)`(恒为 `1.0.0`),于是每个版本发布出去的 DLL 都自称 `1.0.0`—— + 崩溃日志、`dotnet-counters` / OTel 的 scope、任何读 `AssemblyInformationalVersion` 的地方都会拿到错值。 + **只设 `InformationalVersion`、不动 `Version`**,是为了让 `AssemblyVersion` 稳定在 `1.0.0.0`: + 程序集身份不随补丁版跳动,net472 的绑定重定向也不用跟着改。实测结果为 `<包版本>+`(SDK 仍会追加源码版本)。 + - **正式发布**:`release-nuget.yml` 的 `workflow_dispatch` 只选 `versionKind=release`,**没有版本号输入框**—— + 号取自仓库根的 `next-release-version.txt`(发版前改它并提交,这仍是"人工决定 minor/major",只是落在文件里)。 + 随后对 `src/publish-packages.ps1` 里 `$projects` 列表中的每个项目逐个 + `dotnet pack -c Release -p:PackageVersion=… -p:InformationalVersion=…` + `nuget push`。 + - **dev(开发版)**:三种触发方式,**版本规则与构建号都相同**(`-dev.`), + 只差推到哪: + * **CI**(`dotnet.yml`):push 到 `main`/`dev` 时自动产出(`2.0.0-dev.261113.0930`), + **不推任何源**,只上传 `dev-packages.zip` artifact; + * **手工发到私有源**:走 `release-baget.yml`,同样只选 `versionKind`(`release` = 当前 `next-release-version.txt`, + `dev` = `<该文件>-dev.`)——**没有需要人填的号码**; + * **公测(发到 nuget.org)**:走 `release-nuget.yml`,把 `versionKind` 选成 `dev` 即可。 + 这是**唯一**的公开公测途径(没有 alpha/beta/rc)。建议只挑里程碑投放:nuget.org 上的版本不可撤销, + 不想被 `--prerelease` 默认选中时,发布后到 nuget.org 手动 unlist。 + ⚠ 一分钟内重复发布会撞号,撞上时 `--skip-duplicate` 会**静默跳过**(流水线仍绿、包没更新),重跑一次即可。 + - **两个工作流都用同一个下拉 `versionKind`(`release` / `dev`)**,区别只是推到 nuget.org 还是 baget; + 版本串由 workflow 从 `next-release-version.txt` 拼出,两个入口都不需要手抄版本号。 + 两边都会把最终生效的版本写进运行摘要(Summary),事后核对不用翻日志。 - 本机预演: - `cd src` 后 `dotnet pwsh ./publish-packages.ps1 -DevBuildNumber "$(Get-Date -Format yyyyMMddHHmm)" -SkipPush -OutputDir ../dev-packages` + `cd src` 后 `dotnet pwsh ./publish-packages.ps1 -DevBuildNumber "$(Get-Date).ToUniversalTime().ToString('yyMMdd.HHmm')" -SkipPush -OutputDir ../dev-packages` (`-OutputDir` 把产物集中到一处,避免 `bin/Release` 里残留的旧 nupkg 混进来;该目录被 `*.nupkg` 规则忽略,不进 git)。 - - ⚠ **维护点**:正式版发布后把 `next-release-version.txt` 改成下一个计划号(如 `2.0.1`),否则迭代产物的版本 - 会低于已发布的正式版,装上它反而是降级。 - - **`release-nuget.yml`(`name: Release (nuget.org)`)**:发正式版到 nuget.org。走 **OIDC → 临时 API key**(`NuGet/login@v1` + `id-token: write`),不存长期密钥。 - - **`release-baget.yml`(`name: Release (baget.stdunit.com)`)**:发到私有测试源(预览版/内部验证),沿用 `NUGET_SOURCE` / `NUGET_KEY` 两个 secret。 + - ⚠ **维护点**:正式版发布后把 `next-release-version.txt` 改成下一个计划号(如 `2.0.1`)。 + 它现在同时是"下一次正式发布的号"和"dev 包的基线",忘了改会导致要么重发同一个正式号(被 `--skip-duplicate` 静默跳过), + 要么 dev 包的版本低于已发布的正式版(装上反而是降级)。 + - **`release-nuget.yml`(`name: Release (nuget.org)`)**:用 `versionKind` 选正式版或公测版(`-dev.*`),发到 nuget.org。 + 走 **OIDC → 临时 API key**(`NuGet/login@v1` + `id-token: write`),不存长期密钥。 + - **`release-baget.yml`(`name: Release (baget.stdunit.com)`)**:发到私有测试源,同样是 `versionKind` 一个下拉 + (`release` = 当前 `next-release-version.txt`,`dev` = `<该文件>-dev.`);沿用 `NUGET_SOURCE` / `NUGET_KEY` 两个 secret。 - 两个工作流都是 `windows-latest` + **`-c Release` 构建与测试**(让"验的"和发的"是同一份产物),测试覆盖 net8.0 + net472(这是 net472 **运行**测试的权威结果),**不在本地强推**。 - `src/publish-packages.ps1` 会: - 先校验版本号格式(`..[-]`),不合法立即失败——nuget.org 上的版本不可撤销,手误代价大; - `-SkipPush` 可只打包不推送(发版前验证产物),此时不再要求 source/key; - `nuget push` 带 `--skip-duplicate`:发布中途失败后重跑,不会因为"包已存在"再挂一次。 - 新增会被发布的包时:把项目名加进 `src/publish-packages.ps1` 列表,并在自己 csproj 里写一行 ``。 -- `StdUnit.Tags.BlazorLib` **有意不在列表内**:它只是实验场(各驱动的编辑器/设计器实现),暂不对外发布,详见 README 的备注。 +- `StdUnit.Tags.BlazorLib` 已在 2.0 移除(实验场,各驱动的编辑器/设计器实现,从未对外发布);它的能力由 `StdUnit.Tags.WebUi` 的设计器承接。`BlazorLib.Core` 仍在列表内,但进入**维护模式**(只修 bug,不加新功能)。 ## 四、包元数据 diff --git a/paket.dependencies b/paket.dependencies index d0cffb83..77d68a9d 100644 --- a/paket.dependencies +++ b/paket.dependencies @@ -90,3 +90,16 @@ group SchemaGenerator # 用独立 group 隔离,避免主 group 的 Microsoft.CodeAnalysis.CSharp.Scripting >= 5.0(ComScanner 用)拉高版本。 nuget Microsoft.CodeAnalysis.CSharp >= 4.8 lowest_matching: true +group Benchmarks + # 只给 benchmarks/ 用:BenchmarkDotNet 是开发期工具,绝不应出现在任何发布包的依赖里。 + source https://api.nuget.org/v3/index.json + source https://baget.stdunit.com/v3/index.json + + cache ./nuget-package-caches + storage: none + # strategy: min 与 Main 组一致:否则传递依赖会解析到最新的 Azure.Core / Microsoft.Extensions 11.x, + # 在 net8.0 基准工程里刷出一堆"不支持当前 TFM"的警告。 + strategy: min + framework: net8.0 + + nuget BenchmarkDotNet >= 0.15.8 lowest_matching: true \ No newline at end of file diff --git a/paket.lock b/paket.lock index 3df05269..e36dcb70 100644 --- a/paket.lock +++ b/paket.lock @@ -5,9 +5,9 @@ NUGET remote: https://api.nuget.org/v3/index.json BouncyCastle.Cryptography (2.4) Castle.Core (5.2.1) - System.Diagnostics.EventLog (>= 4.7) - restriction: || (&& (== net472) (< net462)) (&& (== net472) (>= netstandard2.1)) (&& (== net8.0) (< net6.0)) (&& (== net8.0) (< netstandard2.1)) (&& (== net8.0-windows7.0) (< net6.0)) (&& (== net8.0-windows7.0) (< netstandard2.1)) (== netstandard2.0) + System.Diagnostics.EventLog (>= 4.7) - restriction: || (&& (== net472) (== net8.0)) (&& (== net472) (== net8.0-windows7.0)) (&& (== net472) (< net462)) (&& (== net472) (>= netstandard2.1)) (&& (== net8.0) (< net6.0)) (&& (== net8.0) (< netstandard2.1)) (&& (== net8.0-windows7.0) (< net6.0)) (&& (== net8.0-windows7.0) (< netstandard2.1)) (== netstandard2.0) System.Diagnostics.EventLog (>= 6.0) - restriction: || (&& (== net472) (>= net6.0)) (== net8.0) (== net8.0-windows7.0) (&& (== netstandard2.0) (>= net6.0)) - System.Reflection.Emit (>= 4.7) - restriction: || (&& (== net472) (< net462)) (&& (== net8.0) (< netstandard2.1)) (&& (== net8.0-windows7.0) (< netstandard2.1)) (== netstandard2.0) + System.Reflection.Emit (>= 4.7) - restriction: || (&& (== net472) (== net8.0)) (&& (== net472) (== net8.0-windows7.0)) (&& (== net472) (< net462)) (&& (== net8.0) (< netstandard2.1)) (&& (== net8.0-windows7.0) (< netstandard2.1)) (== netstandard2.0) coverlet.collector (6.0) FSharp.Core (8.0.100) IsExternalInit (1.0.3) - restriction: == net472 @@ -115,7 +115,7 @@ NUGET Microsoft.Extensions.Options (8.0.2) Microsoft.Extensions.DependencyInjection.Abstractions (>= 8.0) Microsoft.Extensions.Primitives (>= 8.0) - System.ComponentModel.Annotations (>= 5.0) - restriction: || (&& (== net472) (< net462)) (&& (== net472) (>= netstandard2.1)) (&& (== net8.0) (< net6.0)) (&& (== net8.0) (< netstandard2.1)) (&& (== net8.0-windows7.0) (< net6.0)) (&& (== net8.0-windows7.0) (< netstandard2.1)) (== netstandard2.0) + System.ComponentModel.Annotations (>= 5.0) - restriction: || (&& (== net472) (== net8.0)) (&& (== net472) (== net8.0-windows7.0)) (&& (== net472) (< net462)) (&& (== net472) (>= netstandard2.1)) (&& (== net8.0) (< net6.0)) (&& (== net8.0) (< netstandard2.1)) (&& (== net8.0-windows7.0) (< net6.0)) (&& (== net8.0-windows7.0) (< netstandard2.1)) (== netstandard2.0) System.ValueTuple (>= 4.5) - restriction: || (== net472) (&& (== net8.0) (>= net462)) (&& (== net8.0-windows7.0) (>= net462)) (&& (== netstandard2.0) (>= net462)) Microsoft.Extensions.Primitives (8.0) Microsoft.JSInterop (8.0.12) - restriction: || (&& (== net472) (>= net8.0)) (== net8.0) (== net8.0-windows7.0) (&& (== netstandard2.0) (>= net8.0)) @@ -206,8 +206,8 @@ NUGET OPCFoundation.NetStandard.Opc.Ua.Core (>= 1.5.374.126) OPCFoundation.NetStandard.Opc.Ua.Core (1.5.374.126) Microsoft.Bcl.HashCode (>= 1.1.1) - restriction: || (== net472) (&& (== net8.0) (>= net472)) (&& (== net8.0) (< netstandard2.1)) (&& (== net8.0-windows7.0) (>= net472)) (&& (== net8.0-windows7.0) (< netstandard2.1)) (== netstandard2.0) - Microsoft.Extensions.Logging.Abstractions (>= 3.1.32) - restriction: || (&& (== net472) (>= netstandard2.1)) (&& (== net8.0) (< net6.0)) (&& (== net8.0) (< netstandard2.1)) (&& (== net8.0-windows7.0) (< net6.0)) (&& (== net8.0-windows7.0) (< netstandard2.1)) (== netstandard2.0) - Microsoft.Extensions.Logging.Abstractions (>= 6.0.4) - restriction: || (== net472) (&& (== net8.0) (>= net472)) (&& (== net8.0-windows7.0) (>= net472)) (&& (== net8.0-windows7.0) (< net8.0)) (&& (== netstandard2.0) (>= net472)) (&& (== netstandard2.0) (>= net6.0)) + Microsoft.Extensions.Logging.Abstractions (>= 3.1.32) - restriction: || (&& (== net472) (== net8.0)) (&& (== net472) (== net8.0-windows7.0)) (&& (== net472) (>= netstandard2.1)) (&& (== net8.0) (< net6.0)) (&& (== net8.0) (< netstandard2.1)) (&& (== net8.0-windows7.0) (< net6.0)) (&& (== net8.0-windows7.0) (< netstandard2.1)) (== netstandard2.0) + Microsoft.Extensions.Logging.Abstractions (>= 6.0.4) - restriction: || (== net472) (&& (== net8.0) (== netstandard2.0)) (&& (== net8.0) (>= net472)) (&& (== net8.0-windows7.0) (== netstandard2.0)) (&& (== net8.0-windows7.0) (>= net472)) (&& (== net8.0-windows7.0) (< net8.0)) (&& (== netstandard2.0) (>= net472)) (&& (== netstandard2.0) (>= net6.0)) Microsoft.Extensions.Logging.Abstractions (>= 8.0.1) - restriction: || (&& (== net472) (>= net8.0)) (== net8.0) (== net8.0-windows7.0) (&& (== netstandard2.0) (>= net8.0)) Newtonsoft.Json (>= 13.0.3) OPCFoundation.NetStandard.Opc.Ua.Security.Certificates (>= 1.5.374.126) @@ -477,7 +477,7 @@ NUGET System.Reflection.Primitives (>= 4.3) - restriction: || (&& (== net472) (< net45)) (== net8.0) (== net8.0-windows7.0) (== netstandard2.0) System.Runtime (>= 4.3) - restriction: || (&& (== net472) (< net45)) (== net8.0) (== net8.0-windows7.0) (== netstandard2.0) System.Reflection.Emit (4.7) - restriction: || (&& (== net472) (< net45)) (&& (== net472) (< net462)) (== net8.0) (== net8.0-windows7.0) (== netstandard2.0) - System.Reflection.Emit.ILGeneration (>= 4.7) - restriction: || (&& (== net472) (< net45)) (&& (== net472) (< netstandard1.1)) (&& (== net472) (< netstandard2.0) (>= wpa81)) (&& (== net472) (>= uap10.1)) (&& (== net8.0) (< netcoreapp2.0) (< netstandard2.1)) (&& (== net8.0) (< netstandard1.1)) (&& (== net8.0) (< netstandard2.0)) (&& (== net8.0) (>= uap10.1)) (&& (== net8.0-windows7.0) (< netcoreapp2.0) (< netstandard2.1)) (&& (== net8.0-windows7.0) (< netstandard1.1)) (&& (== net8.0-windows7.0) (< netstandard2.0)) (&& (== net8.0-windows7.0) (>= uap10.1)) (== netstandard2.0) + System.Reflection.Emit.ILGeneration (>= 4.7) - restriction: || (&& (== net472) (== net8.0)) (&& (== net472) (== net8.0-windows7.0)) (&& (== net472) (< net45)) (&& (== net472) (< netstandard1.1)) (&& (== net472) (< netstandard2.0) (>= wpa81)) (&& (== net472) (>= uap10.1)) (&& (== net8.0) (< netcoreapp2.0) (< netstandard2.1)) (&& (== net8.0) (< netstandard1.1)) (&& (== net8.0) (< netstandard2.0)) (&& (== net8.0) (>= uap10.1)) (&& (== net8.0-windows7.0) (< netcoreapp2.0) (< netstandard2.1)) (&& (== net8.0-windows7.0) (< netstandard1.1)) (&& (== net8.0-windows7.0) (< netstandard2.0)) (&& (== net8.0-windows7.0) (>= uap10.1)) (== netstandard2.0) System.Reflection.Emit.ILGeneration (4.7) - restriction: || (&& (== net472) (< net45)) (&& (== net472) (< netstandard1.1)) (&& (== net472) (< netstandard2.0) (>= wpa81)) (&& (== net472) (>= uap10.1)) (== net8.0) (== net8.0-windows7.0) (== netstandard2.0) System.Reflection.Emit.Lightweight (4.3) - restriction: || (&& (== net472) (< net45)) (== net8.0) (== net8.0-windows7.0) (== netstandard2.0) System.Reflection (>= 4.3) - restriction: || (&& (== net472) (< net45)) (== net8.0) (== net8.0-windows7.0) (== netstandard2.0) @@ -665,12 +665,12 @@ NUGET System.Threading.Tasks.Extensions (>= 4.5.4) - restriction: || (== net472) (&& (== net8.0) (>= net462)) (&& (== net8.0) (< net6.0)) (&& (== net8.0-windows7.0) (>= net462)) (&& (== net8.0-windows7.0) (< net6.0)) (== netstandard2.0) System.ValueTuple (>= 4.5) - restriction: || (== net472) (&& (== net8.0) (>= net462)) (&& (== net8.0-windows7.0) (>= net462)) (&& (== netstandard2.0) (>= net462)) System.Text.RegularExpressions (4.3) - restriction: || (&& (== net472) (< net452)) (== net8.0) (== net8.0-windows7.0) (== netstandard2.0) - System.Collections (>= 4.3) - restriction: || (&& (== net472) (< net45)) (&& (== net8.0) (< netcoreapp1.1)) (&& (== net8.0-windows7.0) (< netcoreapp1.1)) (== netstandard2.0) - System.Globalization (>= 4.3) - restriction: || (&& (== net472) (< net45)) (&& (== net8.0) (< netcoreapp1.1)) (&& (== net8.0-windows7.0) (< netcoreapp1.1)) (== netstandard2.0) - System.Resources.ResourceManager (>= 4.3) - restriction: || (&& (== net472) (< net45)) (&& (== net8.0) (< netcoreapp1.1)) (&& (== net8.0-windows7.0) (< netcoreapp1.1)) (== netstandard2.0) + System.Collections (>= 4.3) - restriction: || (&& (== net472) (== net8.0)) (&& (== net472) (== net8.0-windows7.0)) (&& (== net472) (< net45)) (&& (== net8.0) (< netcoreapp1.1)) (&& (== net8.0-windows7.0) (< netcoreapp1.1)) (== netstandard2.0) + System.Globalization (>= 4.3) - restriction: || (&& (== net472) (== net8.0)) (&& (== net472) (== net8.0-windows7.0)) (&& (== net472) (< net45)) (&& (== net8.0) (< netcoreapp1.1)) (&& (== net8.0-windows7.0) (< netcoreapp1.1)) (== netstandard2.0) + System.Resources.ResourceManager (>= 4.3) - restriction: || (&& (== net472) (== net8.0)) (&& (== net472) (== net8.0-windows7.0)) (&& (== net472) (< net45)) (&& (== net8.0) (< netcoreapp1.1)) (&& (== net8.0-windows7.0) (< netcoreapp1.1)) (== netstandard2.0) System.Runtime (>= 4.3) - restriction: || (&& (== net472) (< net45)) (&& (== net472) (>= netcoreapp1.1)) (== net8.0) (== net8.0-windows7.0) (== netstandard2.0) - System.Runtime.Extensions (>= 4.3) - restriction: || (&& (== net472) (< net45)) (&& (== net8.0) (< netcoreapp1.1)) (&& (== net8.0-windows7.0) (< netcoreapp1.1)) (== netstandard2.0) - System.Threading (>= 4.3) - restriction: || (&& (== net472) (< net45)) (&& (== net8.0) (< netcoreapp1.1)) (&& (== net8.0-windows7.0) (< netcoreapp1.1)) (== netstandard2.0) + System.Runtime.Extensions (>= 4.3) - restriction: || (&& (== net472) (== net8.0)) (&& (== net472) (== net8.0-windows7.0)) (&& (== net472) (< net45)) (&& (== net8.0) (< netcoreapp1.1)) (&& (== net8.0-windows7.0) (< netcoreapp1.1)) (== netstandard2.0) + System.Threading (>= 4.3) - restriction: || (&& (== net472) (== net8.0)) (&& (== net472) (== net8.0-windows7.0)) (&& (== net472) (< net45)) (&& (== net8.0) (< netcoreapp1.1)) (&& (== net8.0-windows7.0) (< netcoreapp1.1)) (== netstandard2.0) System.Threading (4.3) - restriction: || (&& (== net472) (< net45)) (&& (== net472) (< net452)) (== net8.0) (== net8.0-windows7.0) (== netstandard2.0) System.Runtime (>= 4.3) - restriction: || (&& (== net472) (< net45)) (== net8.0) (== net8.0-windows7.0) (== netstandard2.0) System.Threading.Tasks (>= 4.3) - restriction: || (&& (== net472) (< net45)) (== net8.0) (== net8.0-windows7.0) (== netstandard2.0) @@ -737,6 +737,181 @@ NUGET xunit.runner.visualstudio (2.5.3) Microsoft.TestPlatform.ObjectModel (>= 17.7.2) - restriction: || (== net472) (&& (== net8.0) (>= net462)) (&& (== net8.0-windows7.0) (>= net462)) (&& (== netstandard2.0) (>= net462)) +GROUP Benchmarks +STORAGE: NONE +STRATEGY: MIN +RESTRICTION: == net8.0 +NUGET + remote: https://api.nuget.org/v3/index.json + Azure.Core (1.65) + Microsoft.Bcl.AsyncInterfaces (>= 10.0.10) + Microsoft.Extensions.Configuration.Abstractions (>= 10.0.10) + Microsoft.Extensions.Hosting.Abstractions (>= 10.0.10) + Microsoft.Identity.Client (>= 4.92) + Microsoft.Identity.Client.Extensions.Msal (>= 4.92) + System.ClientModel (>= 1.17) + System.Diagnostics.DiagnosticSource (>= 10.0.10) + System.Memory.Data (>= 10.0.10) + System.Text.Encodings.Web (>= 10.0.10) + System.Text.Json (>= 10.0.10) + Azure.Identity (1.21) + Azure.Core (>= 1.53) + BenchmarkDotNet (0.15.8) + BenchmarkDotNet.Annotations (>= 0.15.8) + CommandLineParser (>= 2.9.1) + Gee.External.Capstone (>= 2.3) + Iced (>= 1.21) + Microsoft.CodeAnalysis.CSharp (>= 4.14) + Microsoft.Diagnostics.Runtime (>= 3.1.512801) + Microsoft.Diagnostics.Tracing.TraceEvent (>= 3.1.21) + Microsoft.DotNet.PlatformAbstractions (>= 3.1.6) + Perfolizer (0.6.1) + System.Management (>= 9.0.5) + BenchmarkDotNet.Annotations (0.15.8) + CommandLineParser (2.9.1) + Gee.External.Capstone (2.3) + Iced (1.22) + Microsoft.Bcl.AsyncInterfaces (11.0) + Microsoft.CodeAnalysis.Analyzers (5.9) + Microsoft.CodeAnalysis.Common (5.9) + Microsoft.CodeAnalysis.Analyzers (>= 5.9.0-1.26328.17) + System.Buffers (>= 4.6.1) + System.Collections.Immutable (>= 10.0.1) + System.Memory (>= 4.6.3) + System.Numerics.Vectors (>= 4.6.1) + System.Reflection.Metadata (>= 10.0.1) + System.Runtime.CompilerServices.Unsafe (>= 6.1.2) + System.Text.Encoding.CodePages (>= 8.0) + System.Threading.Tasks.Extensions (>= 4.6.3) + Microsoft.CodeAnalysis.CSharp (5.9) + Microsoft.CodeAnalysis.Analyzers (>= 5.9.0-1.26328.17) + Microsoft.CodeAnalysis.Common (5.9) + System.Buffers (>= 4.6.1) + System.Collections.Immutable (>= 10.0.1) + System.Memory (>= 4.6.3) + System.Numerics.Vectors (>= 4.6.1) + System.Reflection.Metadata (>= 10.0.1) + System.Runtime.CompilerServices.Unsafe (>= 6.1.2) + System.Text.Encoding.CodePages (>= 8.0) + System.Threading.Tasks.Extensions (>= 4.6.3) + Microsoft.Diagnostics.NETCore.Client (0.2.750501) + Microsoft.Extensions.Logging.Abstractions (>= 8.0.3) + Microsoft.Diagnostics.Runtime (4.2.751201) + Azure.Identity (>= 1.21) + Microsoft.Diagnostics.NETCore.Client (>= 0.2.661903) + Microsoft.Security.AntiSSRF (>= 1.0) + System.Collections.Immutable (>= 10.0.7) + System.Runtime.CompilerServices.Unsafe (>= 6.1.2) + Microsoft.Diagnostics.Tracing.TraceEvent (4.0) + Microsoft.Diagnostics.NETCore.Client (>= 0.2.661903) + Microsoft.Win32.Registry (>= 5.0) + System.Collections.Immutable (>= 10.0.7) + System.Reflection.Metadata (>= 9.0.8) + System.Reflection.TypeExtensions (>= 4.7) + System.Runtime.CompilerServices.Unsafe (>= 6.1.2) + System.Text.Json (>= 10.0.3) + Microsoft.DotNet.PlatformAbstractions (3.1.6) + Microsoft.Extensions.Configuration.Abstractions (11.0) + Microsoft.Extensions.Primitives (>= 11.0) + Microsoft.Extensions.DependencyInjection.Abstractions (11.0) + Microsoft.Extensions.Diagnostics.Abstractions (11.0) + Microsoft.Extensions.DependencyInjection.Abstractions (>= 11.0) + Microsoft.Extensions.Options (>= 11.0) + System.Buffers (>= 4.6.1) + System.Diagnostics.DiagnosticSource (>= 11.0) + System.Memory (>= 4.6.3) + Microsoft.Extensions.FileProviders.Abstractions (11.0) + Microsoft.Extensions.Primitives (>= 11.0) + Microsoft.Extensions.Hosting.Abstractions (11.0) + Microsoft.Extensions.Configuration.Abstractions (>= 11.0) + Microsoft.Extensions.DependencyInjection.Abstractions (>= 11.0) + Microsoft.Extensions.Diagnostics.Abstractions (>= 11.0) + Microsoft.Extensions.FileProviders.Abstractions (>= 11.0) + Microsoft.Extensions.Logging.Abstractions (>= 11.0) + Microsoft.Extensions.Logging.Abstractions (11.0) + Microsoft.Extensions.DependencyInjection.Abstractions (>= 11.0) + System.Buffers (>= 4.6.1) + System.Diagnostics.DiagnosticSource (>= 11.0) + System.Memory (>= 4.6.3) + Microsoft.Extensions.Options (11.0) + Microsoft.Extensions.DependencyInjection.Abstractions (>= 11.0) + Microsoft.Extensions.Primitives (>= 11.0) + System.ComponentModel.Annotations (>= 5.0) + Microsoft.Extensions.Primitives (11.0) + System.Memory (>= 4.6.3) + System.Runtime.CompilerServices.Unsafe (>= 6.1.2) + Microsoft.Identity.Client (4.92) + Microsoft.IdentityModel.Abstractions (>= 8.14) + System.Diagnostics.DiagnosticSource (>= 6.0.1) + Microsoft.Identity.Client.Extensions.Msal (4.92) + Microsoft.Identity.Client (>= 4.92) + System.Security.Cryptography.ProtectedData (>= 4.5) + Microsoft.IdentityModel.Abstractions (8.23) + Microsoft.Security.AntiSSRF (1.0.1) + Microsoft.Win32.Registry (5.0) + System.Security.AccessControl (>= 5.0) + System.Security.Principal.Windows (>= 5.0) + Perfolizer (0.6.1) + Pragmastat (>= 3.2.4) + Pragmastat (3.2.4) + System.Buffers (4.6.1) + System.ClientModel (1.17) + Microsoft.Extensions.Configuration.Abstractions (>= 10.0.10) + Microsoft.Extensions.Hosting.Abstractions (>= 10.0.10) + Microsoft.Extensions.Logging.Abstractions (>= 10.0.10) + System.Diagnostics.DiagnosticSource (>= 10.0.10) + System.Memory.Data (>= 10.0.10) + System.Net.ServerSentEvents (>= 10.0.10) + System.Text.Json (>= 10.0.10) + System.CodeDom (11.0) + System.Memory (>= 4.6.3) + System.Collections.Immutable (11.0) + System.Memory (>= 4.6.3) + System.Runtime.CompilerServices.Unsafe (>= 6.1.2) + System.ComponentModel.Annotations (5.0) + System.Diagnostics.DiagnosticSource (11.0) + System.Memory (>= 4.6.3) + System.Runtime.CompilerServices.Unsafe (>= 6.1.2) + System.IO.Pipelines (11.0) + System.Buffers (>= 4.6.1) + System.Memory (>= 4.6.3) + System.Threading.Tasks.Extensions (>= 4.6.3) + System.Management (11.0) + System.CodeDom (>= 11.0) + System.Memory (4.6.3) + System.Memory.Data (11.0) + System.Memory (>= 4.6.3) + System.Text.Json (>= 11.0) + System.Net.ServerSentEvents (11.0) + Microsoft.Bcl.AsyncInterfaces (>= 11.0) + System.Memory (>= 4.6.3) + System.Threading.Tasks.Extensions (>= 4.6.3) + System.Numerics.Vectors (4.6.1) + System.Reflection.Metadata (11.0) + System.Collections.Immutable (>= 11.0) + System.Reflection.TypeExtensions (4.7) + System.Runtime.CompilerServices.Unsafe (6.1.2) + System.Security.AccessControl (6.0.1) + System.Security.Cryptography.ProtectedData (11.0) + System.Memory (>= 4.6.3) + System.Security.Principal.Windows (5.0) + System.Text.Encoding.CodePages (11.0) + System.Memory (>= 4.6.3) + System.Runtime.CompilerServices.Unsafe (>= 6.1.2) + System.Text.Encodings.Web (11.0) + System.Buffers (>= 4.6.1) + System.Memory (>= 4.6.3) + System.Runtime.CompilerServices.Unsafe (>= 6.1.2) + System.Text.Json (11.0) + Microsoft.Bcl.AsyncInterfaces (>= 11.0) + System.Buffers (>= 4.6.1) + System.IO.Pipelines (>= 11.0) + System.Memory (>= 4.6.3) + System.Runtime.CompilerServices.Unsafe (>= 6.1.2) + System.Text.Encodings.Web (>= 11.0) + System.Threading.Tasks.Extensions (>= 4.6.3) + System.Threading.Tasks.Extensions (4.6.3) + GROUP Mcp STORAGE: NONE STRATEGY: MIN diff --git a/samples/StdUnit.Tags.Web/Program.cs b/samples/StdUnit.Tags.Web/Program.cs index 4b4a184b..0a2d1c09 100644 --- a/samples/StdUnit.Tags.Web/Program.cs +++ b/samples/StdUnit.Tags.Web/Program.cs @@ -18,7 +18,7 @@ builder.Services.AddTags(); builder.Services.AddMudServices(); -builder.Services.AddTagsBlazorLib(); +builder.Services.AddTagsBlazorLibCore(); diff --git a/samples/StdUnit.Tags.Web/StdUnit.Tags.Web.csproj b/samples/StdUnit.Tags.Web/StdUnit.Tags.Web.csproj index 8e5ea56c..9b185724 100644 --- a/samples/StdUnit.Tags.Web/StdUnit.Tags.Web.csproj +++ b/samples/StdUnit.Tags.Web/StdUnit.Tags.Web.csproj @@ -21,7 +21,7 @@ - + diff --git a/src/Directory.Build.props b/src/Directory.Build.props index 95af0050..9ba7435b 100644 --- a/src/Directory.Build.props +++ b/src/Directory.Build.props @@ -15,6 +15,15 @@ enable enable true + + false + + true diff --git a/src/StdUnit.Tags.BlazorLib/Alias.cs b/src/StdUnit.Tags.BlazorLib/Alias.cs deleted file mode 100644 index e8457d48..00000000 --- a/src/StdUnit.Tags.BlazorLib/Alias.cs +++ /dev/null @@ -1 +0,0 @@ -global using TagKinds = System.String; \ No newline at end of file diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Com/ComChannelDescriptorEditor.cs b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Com/ComChannelDescriptorEditor.cs deleted file mode 100644 index 1e332dee..00000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Com/ComChannelDescriptorEditor.cs +++ /dev/null @@ -1,28 +0,0 @@ -using StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.Editing; -using StdUnit.Tags.ComScanner; -using StdUnit.Tags.ComScanner.Channels; -using Microsoft.AspNetCore.Components; - -namespace StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.Com; - -sealed class ComChannelDescriptorEditor : ITagChannelDescriptorEditor -{ - public int Priority => 100; - public bool CanEdit(TagChannelDescriptor descriptor) => descriptor.Driver == ComDriverNames.DriverName; - - public RenderFragment Edit(TagChannelDescriptor descriptor, Action descriptorChanged) - { - var d = descriptor.ToComChannelDescriptor(); - if (!ReferenceEquals(d, descriptor)) - { - descriptorChanged(d); - } - - return builder => - { - builder.OpenComponent(0); - builder.AddAttribute(1, nameof(ComChannelDescriptorEditorView.Descriptor), d); - builder.CloseComponent(); - }; - } -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Com/ComChannelDescriptorEditorView.razor b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Com/ComChannelDescriptorEditorView.razor deleted file mode 100644 index be2683bb..00000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Com/ComChannelDescriptorEditorView.razor +++ /dev/null @@ -1,100 +0,0 @@ -@using System.IO.Ports -@using StdUnit.Tags.BlazorLib -@using StdUnit.Tags.BlazorLib.Components -@using StdUnit.Tags.ComScanner.Channels - - - - - - - - - - - - - - - - - @foreach (var v in Enum.GetValues()) - { - @v - } - - - - - - - - - - @foreach (var v in Enum.GetValues()) - { - @v - } - - - - - - - - - - - - - - - - - - - -@code { - [Parameter, EditorRequired] public ComChannelDescriptor Descriptor { get; set; } = default!; - - private string? _newline; - - protected override void OnParametersSet() - { - _newline = Escape(Descriptor.Option.NewLine); - } - - private Task OnNewLineChanged(string? raw) - { - _newline = raw; - Descriptor.Option.NewLine = Unescape(raw); - return Task.CompletedTask; - } - - private static string? Escape(string? s) - { - if (s is null) return null; - return s.Replace("\r", "\\r").Replace("\n", "\\n").Replace("\t", "\\t"); - } - - private static string? Unescape(string? s) - { - if (string.IsNullOrEmpty(s)) - return null; - try - { - return System.Text.RegularExpressions.Regex.Unescape(s); - } - catch - { - return "\\r\\n"; // ignore invalid escape sequences - } - } -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Com/ComChannelDescriptorViewer.cs b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Com/ComChannelDescriptorViewer.cs deleted file mode 100644 index b44d5dba..00000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Com/ComChannelDescriptorViewer.cs +++ /dev/null @@ -1,23 +0,0 @@ -using StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.Editing; -using StdUnit.Tags.ComScanner; -using StdUnit.Tags.ComScanner.Channels; -using Microsoft.AspNetCore.Components; - -namespace StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.Com; - -sealed class ComChannelDescriptorViewer : ITagChannelDescriptorViewer -{ - public int Priority => 100; - public bool CanView(TagChannelDescriptor descriptor) => descriptor.Driver == ComDriverNames.DriverName; - - public RenderFragment View(TagChannelDescriptor descriptor) - { - var d = descriptor.ToComChannelDescriptor(); - return builder => - { - builder.OpenComponent(0); - builder.AddAttribute(1, nameof(ComChannelDescriptorViewerView.Descriptor), d); - builder.CloseComponent(); - }; - } -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Com/ComChannelDescriptorViewerView.razor b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Com/ComChannelDescriptorViewerView.razor deleted file mode 100644 index 2372509d..00000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Com/ComChannelDescriptorViewerView.razor +++ /dev/null @@ -1,49 +0,0 @@ -@using System.IO.Ports -@using StdUnit.Tags.BlazorLib -@using StdUnit.Tags.BlazorLib.Components -@using StdUnit.Tags.ComScanner.Channels - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@code { - [Parameter, EditorRequired] public ComChannelDescriptor Descriptor { get; set; } = default!; - - private static string? Escape(string? s) - { - if (s is null) return null; - return s.Replace("\r", "\\r") - .Replace("\n", "\\n") - .Replace("\t", "\\t"); - } -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Com/_Extensions.cs b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Com/_Extensions.cs deleted file mode 100644 index b0483399..00000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Com/_Extensions.cs +++ /dev/null @@ -1,18 +0,0 @@ -using System; -using System.Collections.Generic; -using System.Linq; -using System.Text; -using System.Threading.Tasks; -using Microsoft.Extensions.DependencyInjection; - -namespace StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.Com; - -internal static class ServiceCollectionExtensions -{ - public static TagsBlazorBuilder AddComScannerChannelDescriptorViewerAndEditor(this TagsBlazorBuilder builder) - { - builder.AddTagChannelDescriptorViewer() - .AddTagChannelDescriptorEditor(); - return builder; - } -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Hjzk/HjzkTagChannelDescriptorEditor.cs b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Hjzk/HjzkTagChannelDescriptorEditor.cs deleted file mode 100644 index 46c45013..00000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Hjzk/HjzkTagChannelDescriptorEditor.cs +++ /dev/null @@ -1,27 +0,0 @@ -using StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.Editing; -using StdUnit.Tags.Hjzk; -using Microsoft.AspNetCore.Components; - -namespace StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.Hjzk; - -sealed class HjzkTagChannelDescriptorEditor : ITagChannelDescriptorEditor -{ - public int Priority => 110; - public bool CanEdit(TagChannelDescriptor descriptor) => descriptor.Driver == HjzkNames.DriverName; - - public RenderFragment Edit(TagChannelDescriptor descriptor, Action descriptorChanged) - { - var d = descriptor.ToHjzkTagChannelDescriptor(); - if (!ReferenceEquals(d, descriptor)) - { - descriptorChanged(d); - } - - return builder => - { - builder.OpenComponent(0); - builder.AddAttribute(1, nameof(HjzkTagChannelDescriptorEditorView.Descriptor), d); - builder.CloseComponent(); - }; - } -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Hjzk/HjzkTagChannelDescriptorEditorView.razor b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Hjzk/HjzkTagChannelDescriptorEditorView.razor deleted file mode 100644 index 85ea80e5..00000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Hjzk/HjzkTagChannelDescriptorEditorView.razor +++ /dev/null @@ -1,23 +0,0 @@ -@using StdUnit.Tags.BlazorLib -@using StdUnit.Tags.BlazorLib.Components -@using StdUnit.Tags.Hjzk - - - HjzkIoBox 基于 ModbusTcp。 - - - - - - - - - - - - - - -@code { - [Parameter, EditorRequired] public HjzkTagChannelDescriptor Descriptor { get; set; } = default!; -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Hjzk/HjzkTagChannelDescriptorViewer.cs b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Hjzk/HjzkTagChannelDescriptorViewer.cs deleted file mode 100644 index b2f7ae11..00000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Hjzk/HjzkTagChannelDescriptorViewer.cs +++ /dev/null @@ -1,22 +0,0 @@ -using StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.Editing; -using StdUnit.Tags.Hjzk; -using Microsoft.AspNetCore.Components; - -namespace StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.Hjzk; - -sealed class HjzkTagChannelDescriptorViewer : ITagChannelDescriptorViewer -{ - public int Priority => 110; - public bool CanView(TagChannelDescriptor descriptor) => descriptor.Driver == HjzkNames.DriverName; - - public RenderFragment View(TagChannelDescriptor descriptor) - { - var d = descriptor.ToHjzkTagChannelDescriptor(); - return builder => - { - builder.OpenComponent(0); - builder.AddAttribute(1, nameof(HjzkTagChannelDescriptorViewerView.Descriptor), d); - builder.CloseComponent(); - }; - } -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Hjzk/HjzkTagChannelDescriptorViewerView.razor b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Hjzk/HjzkTagChannelDescriptorViewerView.razor deleted file mode 100644 index 3c2d037d..00000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Hjzk/HjzkTagChannelDescriptorViewerView.razor +++ /dev/null @@ -1,19 +0,0 @@ -@using StdUnit.Tags.BlazorLib -@using StdUnit.Tags.BlazorLib.Components -@using StdUnit.Tags.Hjzk - - - - - - - - - - - - - -@code { - [Parameter, EditorRequired] public HjzkTagChannelDescriptor Descriptor { get; set; } = default!; -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Hjzk/_Extensions.cs b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Hjzk/_Extensions.cs deleted file mode 100644 index c42c3091..00000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/Hjzk/_Extensions.cs +++ /dev/null @@ -1,18 +0,0 @@ -using System; -using System.Collections.Generic; -using System.Linq; -using System.Text; -using System.Threading.Tasks; -using Microsoft.Extensions.DependencyInjection; - -namespace StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.Hjzk; - -internal static class ServiceCollectionExtensions -{ - public static TagsBlazorBuilder AddHjzkChannelDescriptorViewerAndEditor(this TagsBlazorBuilder builder) - { - builder.AddTagChannelDescriptorViewer() - .AddTagChannelDescriptorEditor(); - return builder; - } -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ModbusTcp/ModbusTcpTagChannelDescriptorEditor.cs b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ModbusTcp/ModbusTcpTagChannelDescriptorEditor.cs deleted file mode 100644 index 35d16cd4..00000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ModbusTcp/ModbusTcpTagChannelDescriptorEditor.cs +++ /dev/null @@ -1,27 +0,0 @@ -using StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.Editing; -using StdUnit.Tags.ModbusTcp; -using Microsoft.AspNetCore.Components; - -namespace StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.ModbusTcp; - -sealed class ModbusTcpTagChannelDescriptorEditor : ITagChannelDescriptorEditor -{ - public int Priority => 100; - public bool CanEdit(TagChannelDescriptor descriptor) => descriptor.Driver == ModbusTcpNames.DriverName; - - public RenderFragment Edit(TagChannelDescriptor descriptor, Action descriptorChanged) - { - var d = descriptor.ToModbusTcpTagChannelDescriptor(); - if (!ReferenceEquals(d, descriptor)) - { - descriptorChanged(d); - } - - return builder => - { - builder.OpenComponent(0); - builder.AddAttribute(1, nameof(ModbusTcpTagChannelDescriptorEditorView.Descriptor), d); - builder.CloseComponent(); - }; - } -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ModbusTcp/ModbusTcpTagChannelDescriptorEditorView.razor b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ModbusTcp/ModbusTcpTagChannelDescriptorEditorView.razor deleted file mode 100644 index 2cc835f4..00000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ModbusTcp/ModbusTcpTagChannelDescriptorEditorView.razor +++ /dev/null @@ -1,19 +0,0 @@ -@using StdUnit.Tags.BlazorLib -@using StdUnit.Tags.BlazorLib.Components -@using StdUnit.Tags.ModbusTcp - - - - - - - - - - - - - -@code { - [Parameter, EditorRequired] public ModbusTcpTagChannelDescriptor Descriptor { get; set; } = default!; -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ModbusTcp/ModbusTcpTagChannelDescriptorViewer.cs b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ModbusTcp/ModbusTcpTagChannelDescriptorViewer.cs deleted file mode 100644 index 48724b00..00000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ModbusTcp/ModbusTcpTagChannelDescriptorViewer.cs +++ /dev/null @@ -1,22 +0,0 @@ -using StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.Editing; -using StdUnit.Tags.ModbusTcp; -using Microsoft.AspNetCore.Components; - -namespace StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.ModbusTcp; - -sealed class ModbusTcpTagChannelDescriptorViewer : ITagChannelDescriptorViewer -{ - public int Priority => 100; - public bool CanView(TagChannelDescriptor descriptor) => descriptor.Driver == ModbusTcpNames.DriverName; - - public RenderFragment View(TagChannelDescriptor descriptor) - { - var d = descriptor.ToModbusTcpTagChannelDescriptor(); - return builder => - { - builder.OpenComponent(0); - builder.AddAttribute(1, nameof(ModbusTcpTagChannelDescriptorViewerView.Descriptor), d); - builder.CloseComponent(); - }; - } -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ModbusTcp/ModbusTcpTagChannelDescriptorViewerView.razor b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ModbusTcp/ModbusTcpTagChannelDescriptorViewerView.razor deleted file mode 100644 index 4deecb8a..00000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ModbusTcp/ModbusTcpTagChannelDescriptorViewerView.razor +++ /dev/null @@ -1,19 +0,0 @@ -@using StdUnit.Tags.BlazorLib -@using StdUnit.Tags.BlazorLib.Components -@using StdUnit.Tags.ModbusTcp - - - - - - - - - - - - - -@code { - [Parameter, EditorRequired] public ModbusTcpTagChannelDescriptor Descriptor { get; set; } = default!; -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ModbusTcp/_Extensions.cs b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ModbusTcp/_Extensions.cs deleted file mode 100644 index 9cab9f32..00000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ModbusTcp/_Extensions.cs +++ /dev/null @@ -1,19 +0,0 @@ -using StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.ModbusTcp; -using Microsoft.Extensions.DependencyInjection; -using System; -using System.Collections.Generic; -using System.Linq; -using System.Text; -using System.Threading.Tasks; - -namespace StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.ModbusTcp; - -internal static class ServiceCollectionExtensions -{ - public static TagsBlazorBuilder AddModbusTcpChannelDescriptorViewerAndEditor(this TagsBlazorBuilder builder) - { - builder.AddTagChannelDescriptorViewer() - .AddTagChannelDescriptorEditor(); - return builder; - } -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/OpcUa/OpcUaClientTagChannelDescriptorEditor.cs b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/OpcUa/OpcUaClientTagChannelDescriptorEditor.cs deleted file mode 100644 index ba264a8b..00000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/OpcUa/OpcUaClientTagChannelDescriptorEditor.cs +++ /dev/null @@ -1,28 +0,0 @@ -using StdUnit.Tags; -using StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.Editing; -using StdUnit.Tags.OpcUaClient; -using Microsoft.AspNetCore.Components; - -namespace StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.OpcUa; - -public sealed class OpcUaClientTagChannelDescriptorEditor : ITagChannelDescriptorEditor -{ - public int Priority => 100; - public bool CanEdit(TagChannelDescriptor descriptor) => descriptor.Driver == OpcUaClientNames.DriverName; - - public RenderFragment Edit(TagChannelDescriptor descriptor, Action descriptorChanged) - { - var d = descriptor.ToOpcUaClientTagChannelDescriptor(); - if (!ReferenceEquals(d, descriptor)) - { - descriptorChanged(d); - } - - return builder => - { - builder.OpenComponent(0); - builder.AddAttribute(1, nameof(OpcUaClientTagChannelDescriptorEditorView.Descriptor), d); - builder.CloseComponent(); - }; - } -} \ No newline at end of file diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/OpcUa/OpcUaClientTagChannelDescriptorEditorView.razor b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/OpcUa/OpcUaClientTagChannelDescriptorEditorView.razor deleted file mode 100644 index 3e594df8..00000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/OpcUa/OpcUaClientTagChannelDescriptorEditorView.razor +++ /dev/null @@ -1,34 +0,0 @@ -@using StdUnit.Tags.BlazorLib -@using StdUnit.Tags.BlazorLib.Components -@using StdUnit.Tags.OpcUaClient - - - - - - - - - - - - - - - - - - @if (Descriptor.OpcUaTagChannelOpt.ServerOpt.UsePassword) - { - - - - - - - } - - -@code { - [Parameter, EditorRequired] public OpcUaClientTagChannelDescriptor Descriptor { get; set; } = default!; -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/OpcUa/OpcUaClientTagChannelDescriptorViewer.cs b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/OpcUa/OpcUaClientTagChannelDescriptorViewer.cs deleted file mode 100644 index 0fc22f55..00000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/OpcUa/OpcUaClientTagChannelDescriptorViewer.cs +++ /dev/null @@ -1,23 +0,0 @@ -using StdUnit.Tags; -using StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.Editing; -using StdUnit.Tags.OpcUaClient; -using Microsoft.AspNetCore.Components; - -namespace StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.OpcUa; - -public sealed class OpcUaClientTagChannelDescriptorViewer : ITagChannelDescriptorViewer -{ - public int Priority => 100; - public bool CanView(TagChannelDescriptor descriptor) => descriptor.Driver == OpcUaClientNames.DriverName; - - public RenderFragment View(TagChannelDescriptor descriptor) - { - var d = descriptor.ToOpcUaClientTagChannelDescriptor(); - return builder => - { - builder.OpenComponent(0); - builder.AddAttribute(1, nameof(OpcUaClientTagChannelDescriptorViewerView.Descriptor), d); - builder.CloseComponent(); - }; - } -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/OpcUa/OpcUaClientTagChannelDescriptorViewerView.razor b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/OpcUa/OpcUaClientTagChannelDescriptorViewerView.razor deleted file mode 100644 index 977be5d2..00000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/OpcUa/OpcUaClientTagChannelDescriptorViewerView.razor +++ /dev/null @@ -1,25 +0,0 @@ -@using StdUnit.Tags.BlazorLib -@using StdUnit.Tags.BlazorLib.Components -@using StdUnit.Tags.OpcUaClient - - - - - - - - - - - - - - - - - - - -@code { - [Parameter, EditorRequired] public OpcUaClientTagChannelDescriptor Descriptor { get; set; } = default!; -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/OpcUa/_Extensions.cs b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/OpcUa/_Extensions.cs deleted file mode 100644 index e1da3e80..00000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/OpcUa/_Extensions.cs +++ /dev/null @@ -1,18 +0,0 @@ -using System; -using System.Collections.Generic; -using System.Linq; -using System.Text; -using System.Threading.Tasks; -using Microsoft.Extensions.DependencyInjection; - -namespace StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.OpcUa; - -internal static class ServiceCollectionExtensions -{ - public static TagsBlazorBuilder AddOpcUaChannelDescriptorViewerAndEditor(this TagsBlazorBuilder builder) - { - builder.AddTagChannelDescriptorViewer() - .AddTagChannelDescriptorEditor(); - return builder; - } -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/S7/S7TagChannelDescriptorEditor.cs b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/S7/S7TagChannelDescriptorEditor.cs deleted file mode 100644 index d1fb2ad2..00000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/S7/S7TagChannelDescriptorEditor.cs +++ /dev/null @@ -1,27 +0,0 @@ -using StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.Editing; -using StdUnit.Tags.S7; -using Microsoft.AspNetCore.Components; - -namespace StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.S7; - -sealed class S7TagChannelDescriptorEditor : ITagChannelDescriptorEditor -{ - public int Priority => 100; - public bool CanEdit(TagChannelDescriptor descriptor) => descriptor.Driver == S7Names.DriverName; - - public RenderFragment Edit(TagChannelDescriptor descriptor, Action descriptorChanged) - { - var d = descriptor.ToS7TagChannelDescriptor(); - if (!ReferenceEquals(d, descriptor)) - { - descriptorChanged(d); - } - - return builder => - { - builder.OpenComponent(0); - builder.AddAttribute(1, nameof(S7TagChannelDescriptorEditorView.Descriptor), d); - builder.CloseComponent(); - }; - } -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/S7/S7TagChannelDescriptorEditorView.razor b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/S7/S7TagChannelDescriptorEditorView.razor deleted file mode 100644 index 5e94c785..00000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/S7/S7TagChannelDescriptorEditorView.razor +++ /dev/null @@ -1,22 +0,0 @@ -@using StdUnit.Tags.BlazorLib -@using StdUnit.Tags.BlazorLib.Components -@using StdUnit.Tags.S7 - - - - - - - - - - - - - - - - -@code { - [Parameter, EditorRequired] public S7TagChannelDescriptor Descriptor { get; set; } = default!; -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/S7/S7TagChannelDescriptorViewer.cs b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/S7/S7TagChannelDescriptorViewer.cs deleted file mode 100644 index d8d67021..00000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/S7/S7TagChannelDescriptorViewer.cs +++ /dev/null @@ -1,22 +0,0 @@ -using StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.Editing; -using StdUnit.Tags.S7; -using Microsoft.AspNetCore.Components; - -namespace StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.S7; - -sealed class S7TagChannelDescriptorViewer : ITagChannelDescriptorViewer -{ - public int Priority => 100; - public bool CanView(TagChannelDescriptor descriptor) => descriptor.Driver == S7Names.DriverName; - - public RenderFragment View(TagChannelDescriptor descriptor) - { - var d = descriptor.ToS7TagChannelDescriptor(); - return builder => - { - builder.OpenComponent(0); - builder.AddAttribute(1, nameof(S7TagChannelDescriptorViewerView.Descriptor), d); - builder.CloseComponent(); - }; - } -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/S7/S7TagChannelDescriptorViewerView.razor b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/S7/S7TagChannelDescriptorViewerView.razor deleted file mode 100644 index 2cb76aed..00000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/S7/S7TagChannelDescriptorViewerView.razor +++ /dev/null @@ -1,22 +0,0 @@ -@using StdUnit.Tags.BlazorLib -@using StdUnit.Tags.BlazorLib.Components -@using StdUnit.Tags.S7 - - - - - - - - - - - - - - - - -@code { - [Parameter, EditorRequired] public S7TagChannelDescriptor Descriptor { get; set; } = default!; -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/S7/_Extensions.cs b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/S7/_Extensions.cs deleted file mode 100644 index f5652eea..00000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/S7/_Extensions.cs +++ /dev/null @@ -1,18 +0,0 @@ -using System; -using System.Collections.Generic; -using System.Linq; -using System.Text; -using System.Threading.Tasks; -using Microsoft.Extensions.DependencyInjection; - -namespace StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.S7; - -internal static class ServiceCollectionExtensions -{ - public static TagsBlazorBuilder AddS7ChannelDescriptorViewerAndEditor(this TagsBlazorBuilder builder) - { - builder.AddTagChannelDescriptorViewer() - .AddTagChannelDescriptorEditor(); - return builder; - } -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ZLan/ZLanTcpTagChannelDescriptorEditor.cs b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ZLan/ZLanTcpTagChannelDescriptorEditor.cs deleted file mode 100644 index 12e4bd1a..00000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ZLan/ZLanTcpTagChannelDescriptorEditor.cs +++ /dev/null @@ -1,28 +0,0 @@ -using StdUnit.Tags; -using StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.Editing; -using StdUnit.Tags.ZLan; -using Microsoft.AspNetCore.Components; - -namespace StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.ZLan; - -public sealed class ZLanTcpTagChannelDescriptorEditor : ITagChannelDescriptorEditor -{ - public int Priority => 105; - public bool CanEdit(TagChannelDescriptor descriptor) => descriptor.Driver == ZLanTcpNames.DriverName; - - public RenderFragment Edit(TagChannelDescriptor descriptor, Action descriptorChanged) - { - var d = descriptor.ToZLanTcpTagChannelDescriptor(); - if (!ReferenceEquals(d, descriptor)) - { - descriptorChanged(d); - } - - return builder => - { - builder.OpenComponent(0); - builder.AddAttribute(1, nameof(ZLanTcpTagChannelDescriptorEditorView.Descriptor), d); - builder.CloseComponent(); - }; - } -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ZLan/ZLanTcpTagChannelDescriptorEditorView.razor b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ZLan/ZLanTcpTagChannelDescriptorEditorView.razor deleted file mode 100644 index 0a4ab1fa..00000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ZLan/ZLanTcpTagChannelDescriptorEditorView.razor +++ /dev/null @@ -1,19 +0,0 @@ -@using StdUnit.Tags.BlazorLib -@using StdUnit.Tags.BlazorLib.Components -@using StdUnit.Tags.ZLan - - - - - - - - - - - - - -@code { - [Parameter, EditorRequired] public ZLanTcpTagChannelDescriptor Descriptor { get; set; } = default!; -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ZLan/ZLanTcpTagChannelDescriptorViewer.cs b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ZLan/ZLanTcpTagChannelDescriptorViewer.cs deleted file mode 100644 index c1b4ea07..00000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ZLan/ZLanTcpTagChannelDescriptorViewer.cs +++ /dev/null @@ -1,23 +0,0 @@ -using StdUnit.Tags; -using StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.Editing; -using StdUnit.Tags.ZLan; -using Microsoft.AspNetCore.Components; - -namespace StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.ZLan; - -public sealed class ZLanTcpTagChannelDescriptorViewer : ITagChannelDescriptorViewer -{ - public int Priority => 105; - public bool CanView(TagChannelDescriptor descriptor) => descriptor.Driver == ZLanTcpNames.DriverName; - - public RenderFragment View(TagChannelDescriptor descriptor) - { - var d = descriptor.ToZLanTcpTagChannelDescriptor(); - return builder => - { - builder.OpenComponent(0); - builder.AddAttribute(1, nameof(ZLanTcpTagChannelDescriptorViewerView.Descriptor), d); - builder.CloseComponent(); - }; - } -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ZLan/ZLanTcpTagChannelDescriptorViewerView.razor b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ZLan/ZLanTcpTagChannelDescriptorViewerView.razor deleted file mode 100644 index 4da81812..00000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ZLan/ZLanTcpTagChannelDescriptorViewerView.razor +++ /dev/null @@ -1,19 +0,0 @@ -@using StdUnit.Tags.BlazorLib -@using StdUnit.Tags.BlazorLib.Components -@using StdUnit.Tags.ZLan - - - - - - - - - - - - - -@code { - [Parameter, EditorRequired] public ZLanTcpTagChannelDescriptor Descriptor { get; set; } = default!; -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ZLan/_Extensions.cs b/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ZLan/_Extensions.cs deleted file mode 100644 index d86ae0c5..00000000 --- a/src/StdUnit.Tags.BlazorLib/Components/ChannelDescriptors/ZLan/_Extensions.cs +++ /dev/null @@ -1,18 +0,0 @@ -using System; -using System.Collections.Generic; -using System.Linq; -using System.Text; -using System.Threading.Tasks; -using Microsoft.Extensions.DependencyInjection; - -namespace StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.ZLan; - -internal static class ServiceCollectionExtensions -{ - public static TagsBlazorBuilder AddZLanChannelDescriptorViewerAndEditor(this TagsBlazorBuilder builder) - { - builder.AddTagChannelDescriptorViewer() - .AddTagChannelDescriptorEditor(); - return builder; - } -} diff --git a/src/StdUnit.Tags.BlazorLib/Components/_Imports.razor b/src/StdUnit.Tags.BlazorLib/Components/_Imports.razor deleted file mode 100644 index 432c0b29..00000000 --- a/src/StdUnit.Tags.BlazorLib/Components/_Imports.razor +++ /dev/null @@ -1,11 +0,0 @@ -@using System.Net.Http -@using System.Net.Http.Json -@using Microsoft.AspNetCore.Components.Forms -@using Microsoft.AspNetCore.Components.Routing -@using Microsoft.AspNetCore.Components.Web -@using Microsoft.AspNetCore.Components.Web.Virtualization -@using Microsoft.JSInterop -@using MudBlazor -@using StdUnit.Tags.BlazorLib -@using StdUnit.Tags.BlazorLib.Components -@using static Microsoft.AspNetCore.Components.Web.RenderMode diff --git a/src/StdUnit.Tags.BlazorLib/LICENSE b/src/StdUnit.Tags.BlazorLib/LICENSE deleted file mode 100644 index 81ec1673..00000000 --- a/src/StdUnit.Tags.BlazorLib/LICENSE +++ /dev/null @@ -1,21 +0,0 @@ -MIT License - -Copyright (c) 2026 StdUnit.Tags - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. diff --git a/src/StdUnit.Tags.BlazorLib/ServiceCollectionExtensions.cs b/src/StdUnit.Tags.BlazorLib/ServiceCollectionExtensions.cs deleted file mode 100644 index a8395878..00000000 --- a/src/StdUnit.Tags.BlazorLib/ServiceCollectionExtensions.cs +++ /dev/null @@ -1,41 +0,0 @@ -using Microsoft.Extensions.DependencyInjection; -using StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.OpcUa; -using StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.ZLan; -using StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.Hjzk; -using StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.ModbusTcp; -using StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.S7; -using StdUnit.Tags.BlazorLib.Components.ChannelDescriptors.Com; - -namespace StdUnit.Tags.BlazorLib; - -/// -/// extensions for DependencyInjection -/// -public static class ServiceCollectionExtensions -{ - /// - /// 增加TagsBlazorLib服务 - /// - /// - /// - /// - public static IServiceCollection AddTagsBlazorLib(this IServiceCollection services, Action? config = null) - { - services.AddTagsBlazorLibCore(builder => - { - // Default channel descriptor viewers/editors - builder.AddS7ChannelDescriptorViewerAndEditor() - .AddModbusTcpChannelDescriptorViewerAndEditor() - .AddHjzkChannelDescriptorViewerAndEditor() - .AddComScannerChannelDescriptorViewerAndEditor() - .AddZLanChannelDescriptorViewerAndEditor() - .AddOpcUaChannelDescriptorViewerAndEditor(); - - config?.Invoke(builder); - }); - return services; - } - - - -} diff --git a/src/StdUnit.Tags.BlazorLib/StdUnit.Tags.BlazorLib.csproj b/src/StdUnit.Tags.BlazorLib/StdUnit.Tags.BlazorLib.csproj deleted file mode 100644 index 66567c28..00000000 --- a/src/StdUnit.Tags.BlazorLib/StdUnit.Tags.BlazorLib.csproj +++ /dev/null @@ -1,23 +0,0 @@ - - - - Blazor 组件库:各驱动的通道描述符查看器与编辑器 - net8.0 - Library - - false - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/src/StdUnit.Tags.BlazorLib/paket.references b/src/StdUnit.Tags.BlazorLib/paket.references deleted file mode 100644 index ae3d4c24..00000000 --- a/src/StdUnit.Tags.BlazorLib/paket.references +++ /dev/null @@ -1,2 +0,0 @@ -MudBlazor -Microsoft.AspNetCore.Components.Web \ No newline at end of file diff --git a/src/StdUnit.Tags.BlazorLib/wwwroot/background.png b/src/StdUnit.Tags.BlazorLib/wwwroot/background.png deleted file mode 100644 index e15a3bde..00000000 Binary files a/src/StdUnit.Tags.BlazorLib/wwwroot/background.png and /dev/null differ diff --git a/src/StdUnit.Tags.BlazorLib/wwwroot/tags.JsInterop.js b/src/StdUnit.Tags.BlazorLib/wwwroot/tags.JsInterop.js deleted file mode 100644 index 7311c640..00000000 --- a/src/StdUnit.Tags.BlazorLib/wwwroot/tags.JsInterop.js +++ /dev/null @@ -1,20 +0,0 @@ -// This is a JavaScript module that is loaded on demand. It can export any number of -// functions, and may import other JavaScript modules if required. - -export function showPrompt(message) { - return prompt(message, 'Type anything here'); -} - -export function downloadTextFile(fileName, text) { - const blob = new Blob([text], { type: 'text/xml;charset=utf-8;' }); - const link = document.createElement('a'); - const url = URL.createObjectURL(blob); - link.href = url; - link.download = fileName; - document.body.appendChild(link); - link.click(); - setTimeout(function () { - document.body.removeChild(link); - window.URL.revokeObjectURL(url); - }, 0); -} \ No newline at end of file diff --git a/src/StdUnit.Tags.Core/Channels/ITagChannel.cs b/src/StdUnit.Tags.Core/Channels/ITagChannel.cs index 58ef0b18..ff37c48d 100644 --- a/src/StdUnit.Tags.Core/Channels/ITagChannel.cs +++ b/src/StdUnit.Tags.Core/Channels/ITagChannel.cs @@ -17,7 +17,9 @@ public interface ITagChannel : IDisposable Task EnsureConnectedAsync(bool force, CancellationToken ct); /// - /// 关闭 + /// 关闭连接。
+ /// 约定:失败时抛出——调用方是运行器的清理路径,会按通道名记 Warning,也不会阻断其它通道的清理; + /// 而 不抛。即"显式方法报告失败,释放方法只做尽力清理并留痕"。 ///
/// Task DisconnectAsync(CancellationToken ct); diff --git a/src/StdUnit.Tags.Core/Projects/TagsProjectCtrlAttachmentExtensions.cs b/src/StdUnit.Tags.Core/Projects/TagsProjectCtrlAttachmentExtensions.cs index ce058d27..635c2a53 100644 --- a/src/StdUnit.Tags.Core/Projects/TagsProjectCtrlAttachmentExtensions.cs +++ b/src/StdUnit.Tags.Core/Projects/TagsProjectCtrlAttachmentExtensions.cs @@ -1,41 +1,30 @@ -using System; +using System; namespace StdUnit.Tags; /// -/// "给正在运行的项目挂一段观测"的通用封装。 +/// 把一段观测挂到当前正在运行的 (tagsproj)上。 /// public static class TagsProjectCtrlAttachmentExtensions { /// - /// 把一段观测挂到"当前正在运行的项目"上,并在项目停止、换运行、或返回的句柄被 Dispose 时自动摘掉。
+ /// 把一段观测挂到当前正在运行的 (tagsproj)上。
///
- /// 调用方只需要提供 ,其余样板由本方法负责: - /// - /// 晚挂补偿:先订阅 ,再立刻补查一次 - /// ()——观察者比项目晚启动时,"已启动"那次热事件已经过去了。 - /// 去重:补查与事件可能描述同一次运行,按 RunId 判定, 每次运行最多调用一次。 - /// 配对摘除:收到"已停止"、或发现 RunId 变了,先 Dispose 上一次 返回的句柄,再挂新的。 - /// 串行化:内部加锁,"事件线程"与"调用方线程"同时触发也不会重复挂载。 - /// + /// 的每一次挂载都只对应一个正在运行中的 tagsproj: + /// 项目停止或换运行时,先自动释放其上一次挂载,再自动挂载到新运行的 tagsproj 上。
///
- /// 异常: 抛出的异常在构造时原样抛出(同时会撤掉事件订阅,不留悬挂); - /// 若是在"已启动"事件里触发,则由 的派发器接住并记日志, - /// 项目启停不受影响;该次运行不会被标记为已挂载,下一次通知会重试。
- ///
- /// 回调线程: / 上一次返回的 Dispose 运行在 - /// StartPollAsync / StopAsync 的执行上下文(不是轮询线程),应当尽快返回。 + /// 注意:本方法对 projctrl.StartedOrStopped 事件不会自动退订:StartedOrStopped 是感知"下一次运行开始了"的唯一途径, + /// 因此只有调用 Dispose() 本方法返回的句柄才会退订它。 + /// 不释放,则可以一直自动 attach 到新的项目运行;而一旦释放,则立刻退订 并摘掉当前挂载(幂等)。 ///
- /// 项目控制器 + /// 项目控制器(projctrl) /// - /// 挂载回调:参数是正在运行的项目及其运行标识(与 同源)。 - /// 返回的句柄会在解挂时被 Dispose;可以返回一个把多个订阅打包起来的复合句柄。 + /// 对某一次运行的 tagsproj 的挂载:参数是本次运行的 tagsproj 与运行标识(与 同源)。 + /// attach 返回的句柄在相应的 tagsproj 运行结束时,会被自动释放;可以把多个订阅打包成一个复合句柄返回。 /// - /// 解挂句柄:Dispose 即退订事件并摘掉当前挂载(幂等) + /// 对 projctrl 的 StartedOrStopped 事件的退订句柄。释放时会退订事件并摘掉当前挂载。 /// 或 为 null - public static IDisposable AttachRunningProject( - this ITagsProjectCtrl ctrl, - Func attach) + public static IDisposable AttachRunningProject(this ITagsProjectCtrl ctrl, Func attach) { if (ctrl is null) { @@ -50,42 +39,48 @@ public static IDisposable AttachRunningProject( return new Attachment(ctrl, attach); } - /// 一次"挂到运行中项目"的会话。 + /// + /// 一次"挂到某个 tagsproj"的会话;持有 projctrl 的启停事件订阅直到 。 + /// private sealed class Attachment : IDisposable { private readonly object _gate = new(); - private readonly ITagsProjectCtrl _ctrl; + private readonly ITagsProjectCtrl _projctrl; private readonly Func _attach; - private IDisposable? _subscription; + private IDisposable? _projSubscription; /// 已挂载的运行标识;-1 表示当前没有挂载(RunId 从 1 开始)。 private long _attachedRunId = -1; private bool _disposed; - internal Attachment(ITagsProjectCtrl ctrl, Func attach) + internal Attachment(ITagsProjectCtrl projctrl, Func attach) { - this._ctrl = ctrl; + this._projctrl = projctrl; this._attach = attach; - // 顺序不能反:先订阅再补查,才覆盖"订阅之前已经发生的变化"。 - ctrl.StartedOrStopped += this.OnStartedOrStopped; + // 晚挂补偿:先订阅再补查。顺序不能反——观察者比项目晚启动时,"已启动"那次热事件已经过去了, + // 只有订阅之后紧接着 TryGetRunning 才能补上。 + projctrl.StartedOrStopped += this.OnStartedOrStopped; try { this.Sync(); } catch { - // 构造失败不能让事件订阅留在外面(否则 _ctrl 会一直引用一个半死的对象)。 - ctrl.StartedOrStopped -= this.OnStartedOrStopped; + // 构造失败不能把事件订阅留在外面(否则 projctrl 会一直引用一个半死的对象)。 + projctrl.StartedOrStopped -= this.OnStartedOrStopped; throw; } } private void OnStartedOrStopped(ITagsProjectCtrl sender, TagsProjectEventArgs args) => this.Sync(); - /// 让"当前挂载"与"当前运行"对齐:该挂的挂、该摘的摘、已挂过的跳过。 + /// + /// 让"当前挂载"与"当前这次运行"对齐:该挂的挂、该摘的摘、已挂过的跳过。 + /// 加锁串行化"事件线程"与"调用方线程";按 RunId 去重,补查与事件描述同一次运行时不重复挂载。 + /// private void Sync() { lock (this._gate) @@ -95,10 +90,10 @@ private void Sync() return; } - // TryGetRunning 是单次读取:项目与 RunId 必定来自同一次运行。 - if (!this._ctrl.TryGetRunning(out var project, out var runId)) + // 单次读取:tagsproj 与 RunId 必定来自同一次运行。 + if (!this._projctrl.TryGetRunning(out var project, out var runId)) { - this.Detach(); // 已停止 + this.DetachProj(); // 已停止 return; } @@ -107,19 +102,24 @@ private void Sync() return; // 同一次运行:补查与事件都走到过这里 } - this.Detach(); // 换运行了:先摘旧的 + this.DetachProj(); // 换运行了:先摘旧的 var subscription = this._attach(project, runId); - this._subscription = subscription; + this._projSubscription = subscription; this._attachedRunId = runId; // 即便回调返回 null,也算处理过这次运行 } } - /// 摘掉当前挂载(幂等)。 - private void Detach() + /// + /// 摘掉当前这次运行的挂载(幂等)。
+ /// 有意不在这里退订 projctrl 的 :本方法在"停止"与"换运行"时都会被调用, + /// 而"下一次运行开始了"只能靠那条订阅感知——在这里 -= 会让句柄从此失活,再也跟不上重启。 + /// 退订只发生在 。 + ///
+ private void DetachProj() { - var subscription = this._subscription; - this._subscription = null; + var subscription = this._projSubscription; + this._projSubscription = null; this._attachedRunId = -1; subscription?.Dispose(); @@ -134,9 +134,10 @@ public void Dispose() return; } + // 先退订(Sync 开头的 _disposed 判定保证之后到达的通知不会复活挂载),再摘掉当前这次运行的挂载。 this._disposed = true; - this._ctrl.StartedOrStopped -= this.OnStartedOrStopped; - this.Detach(); + this._projctrl.StartedOrStopped -= this.OnStartedOrStopped; + this.DetachProj(); } } } diff --git a/src/StdUnit.Tags.Core/TagCbnts/ITagCbntExtensions.cs b/src/StdUnit.Tags.Core/TagCbnts/ITagCbntExtensions.cs index d6e8cd8a..9154204c 100644 --- a/src/StdUnit.Tags.Core/TagCbnts/ITagCbntExtensions.cs +++ b/src/StdUnit.Tags.Core/TagCbnts/ITagCbntExtensions.cs @@ -34,13 +34,13 @@ public static class ITagCbntExtensions public static ITagChannel SearchRequiredChannel(this ITagCbnt tagcbnt) => tagcbnt.SearchChannel() ?? throw new InvalidOperationException($"Channel is not configured : TagCbnt({tagcbnt.TagName()})"); /// - /// 获取解析后的访问模式。
- /// 如果自身和父级均未配置,则默认返回 。 + /// 获取解析后的访问模式(逐级冒泡:自身 → 父级 Cbnt → 各级 Grp)。
+ /// 如果自身和所有祖先均未配置,则默认返回 。 ///
/// /// public static TagAccessMode SearchAccessMode(this ITagCbnt tagcbnt) - => tagcbnt.Descriptor.AccessMode ?? tagcbnt.Parent?.Descriptor.AccessMode ?? TagAccessMode.RW; + => tagcbnt.Descriptor.AccessMode ?? tagcbnt.Parent?.SearchAccessMode() ?? TagAccessMode.RW; /// /// 只读? diff --git a/src/StdUnit.Tags.Core/TagContainers/TagContainer.cs b/src/StdUnit.Tags.Core/TagContainers/TagContainer.cs index d9cb3876..5f7591d9 100644 --- a/src/StdUnit.Tags.Core/TagContainers/TagContainer.cs +++ b/src/StdUnit.Tags.Core/TagContainers/TagContainer.cs @@ -11,9 +11,11 @@ public abstract record TagContainer /// private TagContainer() { } - private sealed record TagCbnt(ITagCbnt Value) : TagContainer(); + // 子类型对同程序集可见(而不是 private):让 TagContainerExtensions.SearchAccessMode 能用 switch 匹配, + // 从而避免 Map + 委托。外部仍然无法扩展——构造函数是私有的。 + internal sealed record TagCbnt(ITagCbnt Value) : TagContainer(); - private sealed record TagGrp(ITagGrp Value) : TagContainer(); + internal sealed record TagGrp(ITagGrp Value) : TagContainer(); /// /// 工厂函数 diff --git a/src/StdUnit.Tags.Core/TagContainers/TagContainerExtensions.cs b/src/StdUnit.Tags.Core/TagContainers/TagContainerExtensions.cs index 66c42501..34beeea6 100644 --- a/src/StdUnit.Tags.Core/TagContainers/TagContainerExtensions.cs +++ b/src/StdUnit.Tags.Core/TagContainers/TagContainerExtensions.cs @@ -5,6 +5,19 @@ /// public static class TagContainerExtensions { + /// + /// (冒泡式)获取访问模式(逐级冒泡:容器自身 → 各级祖先 → 默认 )。
+ /// 与 同族:由容器节点继续向上追溯,而不是只看直接父级。 + ///
+ /// + /// + public static TagAccessMode SearchAccessMode(this TagContainer tagContainer) => tagContainer switch + { + TagContainer.TagCbnt cbnt => cbnt.Value.SearchAccessMode(), + TagContainer.TagGrp grp => grp.Value.SearchAccessMode(), + _ => throw new NotImplementedException($"未预料到的{nameof(TagContainer)}子类型: {tagContainer.GetType()}") + }; + /// /// (冒泡式)获取 。
/// 如果没有找到,返回 null。
diff --git a/src/StdUnit.Tags.Core/TagGrps/ITagGrp.cs b/src/StdUnit.Tags.Core/TagGrps/ITagGrp.cs index dbb8c10c..68e621ac 100644 --- a/src/StdUnit.Tags.Core/TagGrps/ITagGrp.cs +++ b/src/StdUnit.Tags.Core/TagGrps/ITagGrp.cs @@ -98,7 +98,12 @@ public interface ITagGrp /// - /// 是否有脏数据 + /// 是否有脏数据。
+ /// 契约(与 WriteAsync 的一致性):返回 false 时,WriteAsync 不得写入任何东西; + /// 只要子树里存在待写节点( 或 自身的 IsDirty 为 true),就必须返回 true。
+ /// 注意它不是"父脏必有脏子": 可以独立为 true(整块缓存重写), + /// 此时子测点可以全是干净的。运行器据此用扁平索引判脏(收录的正是 Tag 与组合本身), + /// 违反本契约会导致"该写的没写",且不会有任何编译错误。 ///
/// bool IsDirty(); diff --git a/src/StdUnit.Tags.Core/TagGrps/ITagGrpExtensions.cs b/src/StdUnit.Tags.Core/TagGrps/ITagGrpExtensions.cs index 394defc3..55d26605 100644 --- a/src/StdUnit.Tags.Core/TagGrps/ITagGrpExtensions.cs +++ b/src/StdUnit.Tags.Core/TagGrps/ITagGrpExtensions.cs @@ -264,12 +264,13 @@ public static TagAccessMode SearchAccessMode(this ITagGrp tagGrp) #endregion /// - /// 生成测点组的定位路径(TagGrp(a)/TagGrp(b)),用于加载期错误消息。
+ /// 生成测点组的定位路径(TagGrp(a)/TagGrp(b))。
/// 分隔符与 的路径语法一致(都是 /),便于对照与复制。
- /// 承载项目根的内部节点 __main__ 会被省略,因此顶层组的路径就是它自己。 + /// 承载项目根的内部节点 __main__ 会被省略,因此顶层组的路径就是它自己。
+ /// 加载期错误消息与运行期指标(stdunit.tags.* 的 entry 维度)都用它,格式因此是对外契约。 ///
/// 起始组(含自身),可为 null - internal static string GetLocationPath(this ITagGrp? tagGrp) + public static string GetLocationPath(this ITagGrp? tagGrp) { var parts = new List(); for (var cur = tagGrp; cur is not null; cur = cur.Parent) diff --git a/src/StdUnit.Tags.Core/TagGrps/TagGrp.cs b/src/StdUnit.Tags.Core/TagGrps/TagGrp.cs index dae22151..07ae5533 100644 --- a/src/StdUnit.Tags.Core/TagGrps/TagGrp.cs +++ b/src/StdUnit.Tags.Core/TagGrps/TagGrp.cs @@ -32,7 +32,11 @@ public TagGrp(TagGrpDescriptor descriptor, ITagChannel? channel) #region 子节点 /// - public IDictionary Children { get; } = new Dictionary(); + public IDictionary Children => _children; + + // 存具体类型:公开属性是 IDictionary(API 不变),但遍历时走具体类型的结构体枚举器。 + // 走接口 foreach 会装箱 Dictionary.Enumerator(每次遍历一个分配),而这发生在每一轮的读/写/判脏路径上。 + private readonly Dictionary _children = new(); /// /// 指定的子测点名不存在 @@ -131,7 +135,7 @@ public async Task ReadAsync(TraversalMode mode, CancellationToken ct) return; } - foreach (var kvp in Children) + foreach (var kvp in _children) { var tagunion = kvp.Value; await tagunion.ReadAsync(mode, ct); @@ -147,7 +151,7 @@ public async Task WriteAsync(TraversalMode mode, CancellationToken ct) return; } - foreach (var kvp in Children) + foreach (var kvp in _children) { var tagunion = kvp.Value; await tagunion.WriteAsync(mode, ct); @@ -157,7 +161,7 @@ public async Task WriteAsync(TraversalMode mode, CancellationToken ct) /// public bool IsDirty() { - foreach (var kvp in Children) + foreach (var kvp in _children) { var child = kvp.Value; if (child.IsDirty()) diff --git a/src/StdUnit.Tags.Core/TagUnions/TagUnion.cs b/src/StdUnit.Tags.Core/TagUnions/TagUnion.cs index 793ca91e..2d66a832 100644 --- a/src/StdUnit.Tags.Core/TagUnions/TagUnion.cs +++ b/src/StdUnit.Tags.Core/TagUnions/TagUnion.cs @@ -7,6 +7,13 @@ ///
public abstract record TagUnion { + /// + /// 运行期缓存:解析后的访问模式()。
+ /// 访问模式是配置期属性——加载完成后再改 Descriptor.AccessMode 不会反映到这里, + /// 需要重新加载项目。正因为它是配置期的,缓存才是安全的;命中时省掉逐级冒泡的接口跳转。 + ///
+ internal TagAccessMode? CachedAccessMode; + /// /// 接收一个访问者 /// diff --git a/src/StdUnit.Tags.Core/TagUnions/TagUnionExtensions.cs b/src/StdUnit.Tags.Core/TagUnions/TagUnionExtensions.cs index 0f851fab..b2801f0c 100644 --- a/src/StdUnit.Tags.Core/TagUnions/TagUnionExtensions.cs +++ b/src/StdUnit.Tags.Core/TagUnions/TagUnionExtensions.cs @@ -1,4 +1,4 @@ -namespace StdUnit.Tags; +namespace StdUnit.Tags; /// /// extensions for @@ -24,45 +24,80 @@ public static Task ReadAsync(this TagUnion tagunion, CancellationToken ct) => /// 遍历模式 /// /// - public static async Task ReadAsync(this TagUnion tagunion, TraversalMode mode, CancellationToken ct) + public static Task ReadAsync(this TagUnion tagunion, TraversalMode mode, CancellationToken ct) { - await tagunion.Map( - async tag => + // 不要改回 TagUnion.Map:每个分支都会构造闭包 + 委托 + 异步状态机(分配)。 + // 另外这里**不是** async 方法:常见路径(读同步完成)直接返回已完成 Task; + // 只有真正异步(设备 I/O)时才走下面的两个辅助方法。 + switch (tagunion) + { + case TagUnion.TagUnit unit: { - if (tag.SearchAccessMode() == TagAccessMode.R1W && tag.IsScanned) + var tag = unit.Value; + var access = tagunion.CachedAccessMode ??= tag.SearchAccessMode(); + if (access == TagAccessMode.R1W && tag.IsScanned) { - return; + return Task.CompletedTask; } - if (tag.IsWriteOnly()) + if (access == TagAccessMode.WO) { - return; + return Task.CompletedTask; } - await tag.ReadAsync(ct); - tag.IsScanned = true; - }, - async cbnt => + + var task = tag.ReadAsync(ct); + if (task.Status == TaskStatus.RanToCompletion) + { + tag.IsScanned = true; + return Task.CompletedTask; + } + + return MarkScannedAfterReadAsync(tag, task); + } + case TagUnion.TagCbnt cbntUnion: { + var cbnt = cbntUnion.Value; // 是否短路? if (mode == TraversalMode.RespectEnabled && !cbnt.IsEnabled) { - return; + return Task.CompletedTask; } - if (cbnt.SearchAccessMode() == TagAccessMode.R1W && cbnt.IsScanned) + + var access = tagunion.CachedAccessMode ??= cbnt.SearchAccessMode(); + if (access == TagAccessMode.R1W && cbnt.IsScanned) { - return; + return Task.CompletedTask; } - if (cbnt.IsWriteOnly()) + if (access == TagAccessMode.WO) { - return; + return Task.CompletedTask; } - await cbnt.ReadAsync(ct); - cbnt.IsScanned = true; - }, - async grp => - { - await grp.ReadAsync(mode, ct); + + var task = cbnt.ReadAsync(ct); + if (task.Status == TaskStatus.RanToCompletion) + { + cbnt.IsScanned = true; + return Task.CompletedTask; + } + + return MarkScannedAfterReadAsync(cbnt, task); } - ); + case TagUnion.TagGrp grpUnion: + return grpUnion.Value.ReadAsync(mode, ct); + default: + return Task.FromException(new NotImplementedException($"unknown types: {tagunion.GetType()}")); + } + } + + private static async Task MarkScannedAfterReadAsync(ITag tag, Task readTask) + { + await readTask.ConfigureAwait(false); + tag.IsScanned = true; + } + + private static async Task MarkScannedAfterReadAsync(ITagCbnt cbnt, Task readTask) + { + await readTask.ConfigureAwait(false); + cbnt.IsScanned = true; } /// @@ -82,42 +117,45 @@ await tagunion.Map( /// 遍历模式 /// /// - public static async Task WriteAsync(this TagUnion tagunion, TraversalMode mode, CancellationToken ct) + public static Task WriteAsync(this TagUnion tagunion, TraversalMode mode, CancellationToken ct) { - await tagunion.Map( - async tag => + // 同 ReadAsync:用 switch 而非 Map,避免逐节点构造闭包/委托/状态机; + // 且本方法无需"读后再标记",所以完全不需要 async——直接把子任务的 Task 返回即可。 + switch (tagunion) + { + case TagUnion.TagUnit unit: { - if (tag.IsReadOnly()) + var tag = unit.Value; + var access = tagunion.CachedAccessMode ??= tag.SearchAccessMode(); + if (access == TagAccessMode.RO || !tag.IsDirty) { - return; + return Task.CompletedTask; } - if (tag.IsDirty) - { - await tag.WriteAsync(ct); - } - }, - async cbnt => + + return tag.WriteAsync(ct); + } + case TagUnion.TagCbnt cbntUnion: { + var cbnt = cbntUnion.Value; // 使能门控:未使能的组合整块跳过(含其下的所有测点),其脏标记会被保留到重新使能后再刷写 if (mode == TraversalMode.RespectEnabled && !cbnt.IsEnabled) { - return; - } - if (cbnt.IsReadOnly()) - { - return; + return Task.CompletedTask; } - if (cbnt.IsDirty) + var access = tagunion.CachedAccessMode ??= cbnt.SearchAccessMode(); + if (access == TagAccessMode.RO || !cbnt.IsDirty) { - await cbnt.WriteAsync(ct); + return Task.CompletedTask; } - }, - async grp => - { - await grp.WriteAsync(mode, ct); + + return cbnt.WriteAsync(ct); } - ); + case TagUnion.TagGrp grpUnion: + return grpUnion.Value.WriteAsync(mode, ct); + default: + return Task.FromException(new NotImplementedException($"unknown types: {tagunion.GetType()}")); + } } /// @@ -125,14 +163,13 @@ await tagunion.Map( /// /// /// - public static bool IsDirty(this TagUnion tagunion) + public static bool IsDirty(this TagUnion tagunion) => tagunion switch { - return tagunion.Map( - tag => tag.IsDirty, - cbnt => cbnt.IsDirty, - grp => grp.IsDirty() - ); - } + TagUnion.TagUnit unit => unit.Value.IsDirty, + TagUnion.TagCbnt cbnt => cbnt.Value.IsDirty, + TagUnion.TagGrp grp => grp.Value.IsDirty(), + _ => throw new NotImplementedException($"unknown types: {tagunion.GetType()}") + }; #endregion diff --git a/src/StdUnit.Tags.Core/Tags/ITagExtensions.cs b/src/StdUnit.Tags.Core/Tags/ITagExtensions.cs index 3b616834..ea29142e 100644 --- a/src/StdUnit.Tags.Core/Tags/ITagExtensions.cs +++ b/src/StdUnit.Tags.Core/Tags/ITagExtensions.cs @@ -61,18 +61,13 @@ public static class ITagExtensions /// public static TagAccessMode SearchAccessMode(this ITag tag) { - if (tag.TagDescriptor.AccessMode.HasValue) - return tag.TagDescriptor.AccessMode.Value; - - if (tag.Parent is not null) + if (tag.TagDescriptor.AccessMode is { } configured) { - return tag.Parent.Map( - cbnt => cbnt.Descriptor.AccessMode, - grp => grp.Descriptor.AccessMode - ) ?? TagAccessMode.RW; + return configured; } - return TagAccessMode.RW; + // 父容器解析(本身即逐级冒泡) + return tag.Parent?.SearchAccessMode() ?? TagAccessMode.RW; } /// diff --git a/src/StdUnit.Tags.Core/attribs.cs b/src/StdUnit.Tags.Core/attribs.cs index 7a7e07b9..1014314f 100644 --- a/src/StdUnit.Tags.Core/attribs.cs +++ b/src/StdUnit.Tags.Core/attribs.cs @@ -1,3 +1,4 @@ - + using System.Runtime.CompilerServices; [assembly: InternalsVisibleTo("StdUnit.Tags.Tests")] +[assembly: InternalsVisibleTo("StdUnit.Tags.Benchmarks")] diff --git a/src/StdUnit.Tags.ModbusTcp/Channels/ModbusTcpChannel.cs b/src/StdUnit.Tags.ModbusTcp/Channels/ModbusTcpChannel.cs index 8e37a026..a2728826 100644 --- a/src/StdUnit.Tags.ModbusTcp/Channels/ModbusTcpChannel.cs +++ b/src/StdUnit.Tags.ModbusTcp/Channels/ModbusTcpChannel.cs @@ -152,8 +152,11 @@ protected virtual bool Connected { return false; } - // see https://stackoverflow.com/a/2661876/10091607 - bool part1 = s.Poll(1000, SelectMode.SelectRead); + // 非阻塞快检:Poll(0) 立即返回,`part1 && part2` 的判定逻辑与等待版本完全一致。 + // 绝不能带超时(原先写的是 Poll(1000)):Windows 的计时器粒度约 15.6 ms, + // 空闲连接上这一步实测要 **15.9 ms**,而它发生在每轮、每个通道的 EnsureConnected 里。 + // 基准:benchmarks/StdUnit.Tags.Benchmarks 的 EnsureConnectedBenchmarks。 + bool part1 = s.Poll(0, SelectMode.SelectRead); bool part2 = s.Available == 0; if (part1 && part2) return false; @@ -179,34 +182,16 @@ public async Task EnsureConnectedAsync(bool force, CancellationToken ct) } /// - /// 断开连接 + /// 断开连接。
+ /// 不阻塞,所以这里不再用 把同步调用伪装成异步; + /// 只为接口一致,不参与等待(清理路径本来就该用 )。
+ /// 关闭失败时以故障 Task 返回(与 S7 / OpcUa / ComScanner 一致,见 ), + /// 而 只记日志、不抛。 ///
- /// - /// public Task DisconnectAsync(CancellationToken ct) { - if (_tcpClient == null) - return Task.CompletedTask; - - var tcs = new TaskCompletionSource(); - var th = new Thread(() => - { - try - { - _tcpClient.Close(); - _tcpClient = null; - tcs.SetResult(null); - } - catch (Exception ex) - { - _logger.LogWarning(ex, "通道{ChannelName}断开连接失败", this.ChannelName()); - _tcpClient = null; - tcs.SetException(ex); - } - }); - th.IsBackground = true; - th.Start(); - return tcs.Task; + var error = this.TryCloseConnection(); + return error is null ? Task.CompletedTask : Task.FromException(error); } #endregion @@ -365,23 +350,40 @@ private static ushort[] GetArray(ReadOnlyMemory memory) /// public void Dispose() { - var channelName = this.ChannelName(); - if (_tcpClient != null && _tcpClient.Connected) + var error = this.TryCloseConnection(); + if (error is not null) { - try - { - _logger.LogInformation("通道={ChannelName} 正在断开连接...", channelName); - _tcpClient.Close(); - _logger.LogInformation("通道={ChannelName} 断开连接完成!", channelName); - } - catch (Exception e) - { - _logger.LogWarning(e, "通道={ChannelName} 释放异常", channelName); - } - finally - { + // Dispose 只留痕、不外抛(.NET 的释放惯例)。 + _logger.LogWarning(error, "通道={ChannelName} 释放异常", this.ChannelName()); + } + } - } + /// + /// 关闭并清空底层连接——唯一的释放路径, 与 都走它。
+ /// 有意不用 当守卫:它只是上次 I/O 的快照,半死连接上返回 false, + /// 恰好会把最该关的 socket 留下来。
+ /// 失败时把异常返回而不是吞掉或抛出:由调用方决定是记日志(Dispose)还是外抛(DisconnectAsync)。 + ///
+ private Exception? TryCloseConnection() + { + var client = Interlocked.Exchange(ref _tcpClient, null); + this.ModbusMaster = null; + if (client is null) + { + return null; + } + + var channelName = this.ChannelName(); + try + { + _logger.LogInformation("通道={ChannelName} 正在断开连接...", channelName); + client.Close(); + _logger.LogInformation("通道={ChannelName} 断开连接完成!", channelName); + return null; + } + catch (Exception e) + { + return e; } } } \ No newline at end of file diff --git a/src/StdUnit.Tags.ModbusTcp/attribs.cs b/src/StdUnit.Tags.ModbusTcp/attribs.cs index f557330a..50d12dc7 100644 --- a/src/StdUnit.Tags.ModbusTcp/attribs.cs +++ b/src/StdUnit.Tags.ModbusTcp/attribs.cs @@ -1,6 +1,7 @@ - + using System.Runtime.CompilerServices; [assembly: InternalsVisibleTo("StdUnit.Tags.Tests")] +[assembly: InternalsVisibleTo("StdUnit.Tags.Benchmarks")] [assembly: InternalsVisibleTo("StdUnit.Tags.Hjzk")] [assembly: InternalsVisibleTo("StdUnit.Tags.ZLan")] diff --git a/src/StdUnit.Tags.OpcUaClient/Channels/OpcUaClientTagChannel.cs b/src/StdUnit.Tags.OpcUaClient/Channels/OpcUaClientTagChannel.cs index 1deafdc1..1e29cc26 100644 --- a/src/StdUnit.Tags.OpcUaClient/Channels/OpcUaClientTagChannel.cs +++ b/src/StdUnit.Tags.OpcUaClient/Channels/OpcUaClientTagChannel.cs @@ -208,22 +208,23 @@ public async Task EnsureConnectedAsync(bool force, CancellationToken ct) /// /// 断开连接 /// - /// - /// public async Task DisconnectAsync(CancellationToken ct) { + var session = this.OpcSession; + this.OpcSession = null; + if (session is null) + { + return; + } + try { - if (this.OpcSession != null) - { - await OpcSession.CloseAsync(ct); - } + await session.CloseAsync(ct); } finally { - this.OpcSession = null; + this.ReleaseSession(session); } - } #endregion @@ -376,23 +377,49 @@ public virtual async Task WriteValueAsync(NodeId nodeId, DataValue value, Cancel /// public void Dispose() { - if (OpcSession != null && OpcSession.Connected) + var session = this.OpcSession; + this.OpcSession = null; + if (session is null) { - var channelName = this.ChannelName(); - try + return; + } + + var channelName = this.ChannelName(); + try + { + // 已断开的会话不必再 Close(Stack 侧会因此抛错),但**必须** Dispose—— + // 这与 ModbusTcpChannel 的"无条件 Close"不同:那边 Connected==false 意味着句柄还活着。 + if (session.Connected) { _logger.LogInformation("通道={ChannelName} 正在断开连接...", channelName); - OpcSession.Close(); + session.Close(); _logger.LogInformation("通道={ChannelName} 断开连接完成!", channelName); } - catch (Exception e) - { - _logger.LogWarning(e, "通道={ChannelName} 释放异常", channelName); - } - finally - { + } + catch (Exception e) + { + _logger.LogWarning(e, "通道={ChannelName} 释放异常", channelName); + } + finally + { + this.ReleaseSession(session); + } + } - } + /// + /// 释放 身上由 负责的那部分资源(订阅、传输句柄等)。 + /// Close/CloseAsync 只负责"关闭会话",不释放它们;漏掉这一下,反复启停会攒下没人认领的对象。
+ /// 这里只记日志、不抛:它是 finally 里的收尾,抛出来会盖掉真正的原因(关闭失败)。 + ///
+ private void ReleaseSession(ISession session) + { + try + { + session.Dispose(); + } + catch (Exception e) + { + _logger.LogWarning(e, "通道={ChannelName} 释放会话异常", this.ChannelName()); } } } diff --git a/src/StdUnit.Tags.S7/Channels/S7TagChannel.cs b/src/StdUnit.Tags.S7/Channels/S7TagChannel.cs index 9c8907bd..ef97cfcb 100644 --- a/src/StdUnit.Tags.S7/Channels/S7TagChannel.cs +++ b/src/StdUnit.Tags.S7/Channels/S7TagChannel.cs @@ -1,7 +1,5 @@ -using Microsoft.Extensions.Logging; +using Microsoft.Extensions.Logging; using StdUnit.Sharp7; -using Microsoft.FSharp.Core; - namespace StdUnit.Tags.S7; @@ -32,7 +30,7 @@ public S7TagChannel(S7TagChannelDescriptor descriptor, ILogger log /// /// S7Client 工厂。 - /// 如果不为 null,则在 被调用; + /// 如果不为 null,则在 里被调用; /// 如果返回null,则会直接使用默认的构造 /// public Func? ClientFactory { get; set; } @@ -52,112 +50,63 @@ public S7TagChannel(S7TagChannelDescriptor descriptor, ILogger log /// public virtual async Task DisconnectAsync(CancellationToken ct) { - await this.ExecuteOneByOneAsync( - async ct => - { - if (this.Client == null) - return; - - var tcs = new TaskCompletionSource(); - var th = new Thread(() => - { - try - { - this.Client?.Disconnect(); - this.Client = null; - tcs.SetResult(null); - } - catch (Exception ex) - { - this._logger.LogWarning(ex, "通道{ChannelName}断开连接失败", this.ChannelName()); - this.Client = null; - tcs.SetException(ex); - } - }); - th.IsBackground = true; - th.Start(); - await tcs.Task; - }, - ct - ); + await this.RunExclusiveAsync(() => + { + // 先摘引用再断开:断开失败也不留下状态未知的 Client;异常原样抛出,堆栈天然完整。 + var client = this.DetachClient(); + client?.Disconnect(); + }, ct); } /// public virtual async Task EnsureConnectedAsync(bool force, CancellationToken ct) { - await this.ExecuteOneByOneAsync( - async ct => + await this.RunExclusiveAsync(() => + { + //当前client存在并且连接有效 + if (!force && this.Client != null && !this.Client.IsDead()) { - //当前client存在并且连接有效 - if (!force && Client != null && !Client.IsDead()) - { - return; - } - var channelName = this.ChannelName(); + return; + } - // 如果要强制连接,先清理当前的连接 - if (force && Client != null) + var channelName = this.ChannelName(); + + // 如果要强制连接,先清理当前的连接 + if (force && this.Client != null) + { + this._logger.LogInformation("通道={ChannelName} 强制断开连接中...", channelName); + try { - try - { - this._logger.LogInformation("通道={ChannelName} 强制断开连接中...", channelName); - this.Client.Disconnect(); - } - catch (Exception ex) - { - this._logger.LogError(ex, "通道={ChannelName} 强制断开异常", channelName); - } - finally - { - this.Client = null; - } + this.DetachClient()?.Disconnect(); } - - var result = await this.CreateClientAndConnectAsync(ct); - if (result.IsError) + catch (Exception ex) { - var err = result.ErrorValue; - throw new InvalidOperationException($"通道({channelName}) 连接PLC失败:{this.PlcItem.IpAddr} Rack={this.PlcItem.Rack} Slot={this.PlcItem.Slot};{err.Text}({err.Error})"); + this._logger.LogError(ex, "通道={ChannelName} 强制断开异常", channelName); } - this.Client = result.ResultValue; - }, - ct - ); + } + + this.Client = this.CreateClientAndConnect(channelName); + }, ct); } /// - /// 创建客户端并连接PLC + /// 创建客户端并连接PLC。失败时抛 (消息带 Sharp7 的 ApiError 文案与错误码)。 /// - /// - /// - protected virtual Task> CreateClientAndConnectAsync(CancellationToken ct) + /// 通道名,仅用于错误消息 + protected virtual S7Client CreateClientAndConnect(string channelName) { - var tcs = new TaskCompletionSource>(); - var th = new Thread(() => + var client = this.ClientFactory?.Invoke(this.PlcItem) ?? new S7Client(); + client.SetConnectionType(this.PlcItem.ConnectionType); + + var code = client.ConnectTo(this.PlcItem.IpAddr, this.PlcItem.Rack, this.PlcItem.Slot); + if (code != 0) { - var client = ClientFactory?.Invoke(this.PlcItem) ?? new S7Client(); - client.SetConnectionType(this.PlcItem.ConnectionType); - try - { - var code = client.ConnectTo(this.PlcItem.IpAddr, this.PlcItem.Rack, this.PlcItem.Slot); - if (code == 0) - { - tcs.SetResult(FSharpResult.NewOk(client)); - } - else - { - tcs.SetResult(FSharpResult.NewError(S7ErrorCodeHelper.GenerateApiError(this.ChannelName(), code))); - } - } - catch (Exception ex) - { - tcs.SetException(ex); - } - }); - th.IsBackground = true; - th.Start(); - return tcs.Task; + var err = S7ErrorCodeHelper.GenerateApiError(channelName, code); + throw new InvalidOperationException($"通道({channelName}) 连接PLC失败:{this.PlcItem.IpAddr} Rack={this.PlcItem.Rack} Slot={this.PlcItem.Slot};{err.Text}({err.Error})"); + } + + return client; } @@ -246,36 +195,57 @@ public virtual void Write(string address, Span buffer, CancellationToken c /// public virtual void Dispose() { - var client = this.Client; - if (client != null && client.Connected) + try { - var channelName = this.ChannelName(); - try + this.RunExclusive(() => { - this._logger.LogInformation("通道={ChannelName} 正在释放: 断开连接中...", channelName); + var client = this.DetachClient(); + if (client is null) + { + return; + } - this.ExecuteOneByOne(() => + var channelName = this.ChannelName(); + try { client.Disconnect(); - this._logger.LogInformation("通道={ChannelName} 正在释放: 断开连接完成!", channelName); - }); - } - catch (Exception e) - { - this._logger.LogWarning("通道={ChannelName} 释放异常:{exception}", channelName, e.Message); - } + this._logger.LogInformation("通道={ChannelName} 释放完成(已断开连接)", channelName); + } + catch (Exception e) + { + // Dispose 只留痕、不外抛(.NET 的释放惯例)。 + this._logger.LogWarning(e, "通道={ChannelName} 释放异常", channelName); + } + }); + } + finally + { + this._rw.Dispose(); } - this.Client = null; - this._rw.Dispose(); } + /// + /// 把当前连接摘下来并清空 。不做断开动作——由调用方决定怎么处理: + /// 让它抛(显式方法报告失败), 与强制重连只记日志。
+ /// 有意不判 :它是底层 Socket 的快照,半死连接上返回 false, + /// 恰好会把最该关的 socket 留下来。 + ///
+ private S7Client? DetachClient() + { + var client = this.Client; + this.Client = null; + return client; + } - private async Task ExecuteOneByOneAsync(Func action, CancellationToken ct) + /// + /// 独占 I/O 互斥体执行一段同步工作(读/写直接用 ,因为 不能进闭包)。 + /// + private void RunExclusive(Action action, CancellationToken ct = default) { - await this._rw.WaitAsync(ct); + this._rw.Wait(ct); try { - await action(ct); + action(); } finally { @@ -283,9 +253,12 @@ private async Task ExecuteOneByOneAsync(Func action, Ca } } - private void ExecuteOneByOne(Action action) + /// + /// 同 ,差别只在"等待互斥体时可取消"——连接/断开这类可能长时间持锁的操作走这个。 + /// + private async Task RunExclusiveAsync(Action action, CancellationToken ct) { - this._rw.Wait(); + await this._rw.WaitAsync(ct); try { action(); diff --git a/src/StdUnit.Tags.S7/S7Address.cs b/src/StdUnit.Tags.S7/S7Address.cs index 9f406be1..a357aec0 100644 --- a/src/StdUnit.Tags.S7/S7Address.cs +++ b/src/StdUnit.Tags.S7/S7Address.cs @@ -114,6 +114,11 @@ public string Format() ///
public static class S7AddressParser { + // 正则构造有可观开销,而解析发生在每一轮读写路径上,所以提升为静态只读(不可变、线程安全)。 + // 不可变、线程安全,提升为静态只读;匹配语义与逐次构造完全一致。 + private static readonly Regex DbWithNthBitPattern = new(@"DB(?[0-9]+)\.(?[0-9]+)\.(?[0-9]+)$"); + private static readonly Regex DbWithoutNthBitPattern = new(@"DB(?[0-9]+)\.(?[0-9]+)$"); + /// /// 把地址字符串解析成 /// @@ -159,8 +164,7 @@ public static S7Address Parse(string addr) private static FSharpResult ParseDBAddressWithNthBit(string addr) { - var regex = new Regex(@"DB(?[0-9]+)\.(?[0-9]+)\.(?[0-9]+)$"); - var match = regex.Match(addr); + var match = DbWithNthBitPattern.Match(addr); if (!match.Success) { return $"未能匹配模式 DB..的模式".ToErrResult(); @@ -200,8 +204,7 @@ private static FSharpResult ParseDBAddressWithNthBit(string a private static FSharpResult ParseDBAddressWithoutNthBit(string addr) { - var regex = new Regex(@"DB(?[0-9]+)\.(?[0-9]+)$"); - var match = regex.Match(addr); + var match = DbWithoutNthBitPattern.Match(addr); if (!match.Success) { return $"未能匹配模式 DB.的模式".ToErrResult(); diff --git a/src/StdUnit.Tags.S7/attribs.cs b/src/StdUnit.Tags.S7/attribs.cs index 6cc778dc..6ce6caec 100644 --- a/src/StdUnit.Tags.S7/attribs.cs +++ b/src/StdUnit.Tags.S7/attribs.cs @@ -1,4 +1,5 @@ - + using System.Runtime.CompilerServices; [assembly: InternalsVisibleTo("StdUnit.Tags.Tests")] +[assembly: InternalsVisibleTo("StdUnit.Tags.Benchmarks")] diff --git a/src/StdUnit.Tags/TagCbnt.cs b/src/StdUnit.Tags/TagCbnt.cs index 03e6823c..856cee82 100644 --- a/src/StdUnit.Tags/TagCbnt.cs +++ b/src/StdUnit.Tags/TagCbnt.cs @@ -68,7 +68,11 @@ public void ResizeCache(int cacheSize) #region 子节点 /// - public IDictionary Children { get; } = new Dictionary(); + public IDictionary Children => _children; + + // 同 TagGrp:公开属性保持 IDictionary(API 不变),但遍历走具体类型的结构体枚举器, + // 避免每次 NotifyChildrenRead/Write 都装箱一个 Dictionary.Enumerator。 + private readonly Dictionary _children = new(); /// public ITagCbntor this[string tagName] => this.Children.TryGetValue(tagName, out var tag) ? @@ -93,7 +97,7 @@ public void ResizeCache(int cacheSize) ///
protected void NotifyChildrenRead() { - foreach (var kv in this.Children) + foreach (var kv in _children) { kv.Value.NotifyTagRead(); } @@ -104,7 +108,7 @@ protected void NotifyChildrenRead() ///
protected void NotifyChildrenWritten() { - foreach (var kv in this.Children) + foreach (var kv in _children) { kv.Value.NotifyTagWritten(); kv.Value.IsDirty = false; diff --git a/src/StdUnit.Tags/TagGrpRunners/DefaultTagGrpRunnerDisconnectStrategy.cs b/src/StdUnit.Tags/TagGrpRunners/DefaultTagGrpRunnerDisconnectStrategy.cs index 6a65ee8a..43c1095e 100644 --- a/src/StdUnit.Tags/TagGrpRunners/DefaultTagGrpRunnerDisconnectStrategy.cs +++ b/src/StdUnit.Tags/TagGrpRunners/DefaultTagGrpRunnerDisconnectStrategy.cs @@ -23,5 +23,12 @@ public async Task WaitDisconnectAsync(ITagChannel? channel, Task? disconnect) // 超时定时器不用 CancellationToken——断开本身是 CancellationToken.None 发起的, // 超时定时器若被取消会立即抛 OCE,退化成"不等待"。 await Task.WhenAny(disconnect, Task.Delay(Timeout)); + + // 超时未完成就放弃等待(后台仍会继续清理);但"已经失败"必须让调用方看见—— + // 否则故障任务永远没人 await(UnobservedTaskException),谁也不知道连接没断干净。 + if (disconnect.IsCompleted) + { + await disconnect; + } } } diff --git a/src/StdUnit.Tags/TagGrpRunners/DirtyNodeIndex.cs b/src/StdUnit.Tags/TagGrpRunners/DirtyNodeIndex.cs new file mode 100644 index 00000000..eb186ad8 --- /dev/null +++ b/src/StdUnit.Tags/TagGrpRunners/DirtyNodeIndex.cs @@ -0,0 +1,79 @@ +using System.Collections.Generic; + +namespace StdUnit.Tags; + +/// +/// 入口子树的"可写节点"扁平索引,把每轮判脏从"递归走 Children + TagUnion 分发"降为"扫两个数组"。
+/// 只收录 与 ——这两类正是写单元:WriteAsync 只看它们各自的 +/// IsDirty 决定是否写;组合本身可以独立为脏(整块缓存重写),所以必须收录。
+/// 树结构假定加载后不变;索引在运行器每次(重)启动时重建。 +///
+internal sealed class DirtyNodeIndex +{ + private readonly ITag[] _tags; + private readonly ITagCbnt[] _cbnts; + + private DirtyNodeIndex(ITag[] tags, ITagCbnt[] cbnts) + { + this._tags = tags; + this._cbnts = cbnts; + } + + /// + /// 收集入口子树中的全部 Tag / Cbnt(不区分是否使能——IsDirty() 本来也不看使能)。
+ /// 索引的正确性建立在 与 WriteAsync 的一致性契约上: + /// "返回 false 时写不得有任何动作;只要存在待写节点就必须返回 true"。 + /// 注意它不是"父脏必有脏子"——组合自身的脏也在收录范围内,因此不会漏。 + ///
+ public static DirtyNodeIndex Build(ITagGrp entry) + { + var tags = new List(); + var cbnts = new List(); + Collect(entry, tags, cbnts); + return new DirtyNodeIndex(tags.ToArray(), cbnts.ToArray()); + } + + /// + /// 是否有任一节点已脏。分两个数组扫描是为了避免对 做类型分发 + /// (实测 10k 节点:直接读 ITag.IsDirty 约 2.6 ns/点,经 TagUnion 约 5.2 ns/点)。 + /// + public bool AnyDirty() + { + foreach (var tag in this._tags) + { + if (tag.IsDirty) + { + return true; + } + } + + foreach (var cbnt in this._cbnts) + { + if (cbnt.IsDirty) + { + return true; + } + } + + return false; + } + + private static void Collect(ITagGrp grp, List tags, List cbnts) + { + foreach (var child in grp.Children.Values) + { + switch (child) + { + case TagUnion.TagUnit unit: + tags.Add(unit.Value); + break; + case TagUnion.TagCbnt cbnt: + cbnts.Add(cbnt.Value); + break; + case TagUnion.TagGrp nested: + Collect(nested.Value, tags, cbnts); + break; + } + } + } +} diff --git a/src/StdUnit.Tags/TagGrpRunners/TagGrpRunner.cs b/src/StdUnit.Tags/TagGrpRunners/TagGrpRunner.cs index 03e06a36..a15a474c 100644 --- a/src/StdUnit.Tags/TagGrpRunners/TagGrpRunner.cs +++ b/src/StdUnit.Tags/TagGrpRunners/TagGrpRunner.cs @@ -1,4 +1,4 @@ -using Microsoft.Extensions.Logging; +using Microsoft.Extensions.Logging; using System.Diagnostics; namespace StdUnit.Tags; @@ -48,6 +48,11 @@ public TagGrpRunner( /// public virtual async Task StartAsync(ITagGrp entry, CancellationToken ct) { + // 指标维度只随入口变化,建一次、每轮复用(每轮新建 tag 数组会让"指标零分配"失效)。 + var metricTags = TagsMetric.TagsFor(entry); + // 上一轮是否以崩溃收场?用于把"崩溃后的重新建连"记成一次 reconnect。 + var recovering = false; + while (!ct.IsCancellationRequested) { // 入口主通道。各回调中的 channel 参数恒为它。 @@ -68,6 +73,8 @@ public virtual async Task StartAsync(ITagGrp entry, CancellationToken ct) channel = entry.SearchChannel(); channels = entry.CollectChannels(); + // 判脏索引:与 CollectChannels 同生命周期(每次外层重启用重建),把每轮判脏变成两次数组扫描。 + var dirtyIndex = DirtyNodeIndex.Build(entry); // 单槽回调:先取本地再判空,避免两次读取之间被改成 null。 var onStarted = this.RunnerStarted; if (onStarted is not null) @@ -90,8 +97,14 @@ public virtual async Task StartAsync(ITagGrp entry, CancellationToken ct) await ch.EnsureConnectedAsync(force: false, ct); } + if (recovering) + { + recovering = false; + TagsMetric.RecordReconnect(metricTags); + } + await this.DrainWriteIntentsAsync(entry, ct); - if (entry.IsDirty()) + if (dirtyIndex.AnyDirty()) { await entry.WriteAsync(TraversalMode.RespectEnabled, ct); } @@ -101,9 +114,15 @@ public virtual async Task StartAsync(ITagGrp entry, CancellationToken ct) { await onTurn(entry, channel, ct); } - await entry.WriteAsync(TraversalMode.RespectEnabled, ct); + + // 逻辑处理之后再判一次:干净时整趟跳过(WriteAsync 对干净节点本来也是空操作)。 + if (dirtyIndex.AnyDirty()) + { + await entry.WriteAsync(TraversalMode.RespectEnabled, ct); + } sw.Stop(); + TagsMetric.RecordTurn(metricTags, sw.Elapsed); var span = TimeSpan.FromMilliseconds(entry.SearchScanInterval() ?? 0); var delay = this._pollDelayStrategy.GetDelay(span, sw.Elapsed); if (delay > TimeSpan.Zero) @@ -128,6 +147,8 @@ public virtual async Task StartAsync(ITagGrp entry, CancellationToken ct) { aborted = true; _consecutiveFailures++; + recovering = true; + TagsMetric.RecordFailure(metricTags); var onCrashed = this.RunnerCrashed; if (onCrashed is not null) diff --git a/src/StdUnit.Tags/TagGrpRunners/TagsMetric.cs b/src/StdUnit.Tags/TagGrpRunners/TagsMetric.cs new file mode 100644 index 00000000..67387c2c --- /dev/null +++ b/src/StdUnit.Tags/TagGrpRunners/TagsMetric.cs @@ -0,0 +1,76 @@ +using System.Diagnostics.Metrics; + +namespace StdUnit.Tags; + +/// +/// 指标的实现:创建 、持有各 instrument、提供给运行器调用的记录方法。
+/// 名称 / 单位 / tag 键的契约常量统一在公开的 里,这里只引用、不重复定义。
+/// 无监听者时 Counter.Add / Histogram.Record 是零分配、纳秒级,所以没有"是否启用"的开关。 +///
+internal static class TagsMetric +{ + private static readonly Meter Meter = CreateMeter(); + + /// + /// 有意不传 version:AOT/裁剪下用反射读程序集自定义特性不可靠(元数据可能被裁掉,结果静默退化成 0.0.0)。
+ /// 打包脚本现在会注入 InformationalVersion,但零反射的读取方式(构建期生成常量)还没做, + /// 所以这里先不报版本,而不是用反射凑一个可能错误的值。 + ///
+ private static Meter CreateMeter() => new(TagsMetricContract.MeterName); + + /// + /// 入口维度:位置路径——唯一且基数有界。
+ /// 有意不带测点名/地址(无界基数);也不带 driver——失败可能来自入口下的辅通道, + /// 拿主通道去标注会把责任算错,宁可少一个维度也不要错误的数据。
+ /// 为什么返回数组而不是单个键值对:Counter.Add / Histogram.Record 的入参就是 + /// KeyValuePair<string, object?>[](或它的 span),而 TagList 是 ref struct, + /// 不能存进字段。数组是唯一“建一次、每轮复用、零额外分配”的形状;将来加维度也只改这里。 + ///
+ public static KeyValuePair[] TagsFor(ITagGrp entry) => + new[] { + new KeyValuePair(TagsMetricContract.EntryTag, entry.GetLocationPath()) + }; + + private static readonly Counter Turns = + Meter.CreateCounter( + TagsMetricContract.Turns, + TagsMetricContract.TurnsUnit, + "入口完整走完的轮次数(读入 → 逻辑 → 刷写)" + ); + + private static readonly Histogram TurnDuration = + Meter.CreateHistogram( + TagsMetricContract.TurnDuration, + TagsMetricContract.TurnDurationUnit, + "每轮耗时:从 EnsureConnected 到刷写输出(不含轮间等待)" + ); + + private static readonly Counter Failures = + Meter.CreateCounter( + TagsMetricContract.Failures, + TagsMetricContract.FailuresUnit, + "入口轮次崩溃次数(停机引起的取消不计)" + ); + + private static readonly Counter Reconnects = + Meter.CreateCounter( + TagsMetricContract.Reconnects, + TagsMetricContract.ReconnectsUnit, + "入口崩溃后重新建连并成功走完建连阶段的次数" + ); + + /// + /// 记录一轮完成。调用方必须传入复用的 tag 数组(每轮新建会抵消"指标本身零分配"的意义)。 + /// + public static void RecordTurn(KeyValuePair[] tags, TimeSpan elapsed) + { + Turns.Add(1, tags); + TurnDuration.Record(elapsed.TotalSeconds, tags); + } + + /// 记录一次崩溃。 + public static void RecordFailure(KeyValuePair[] tags) => Failures.Add(1, tags); + + /// 记录一次崩溃后的恢复(重新走完建连阶段)。 + public static void RecordReconnect(KeyValuePair[] tags) => Reconnects.Add(1, tags); +} \ No newline at end of file diff --git a/src/StdUnit.Tags/TagsMetricContract.cs b/src/StdUnit.Tags/TagsMetricContract.cs new file mode 100644 index 00000000..298decb8 --- /dev/null +++ b/src/StdUnit.Tags/TagsMetricContract.cs @@ -0,0 +1,45 @@ +namespace StdUnit.Tags; + +/// +/// 本库运行期指标的**契约**:Meter 名、指标名、单位与 tag 键。
+/// 使用方按这些字面量订阅与查询,因此它们不会改名——改名等于让对方的 dashboard 静默变空, +/// 把单位从 s 改成 ms 会让曲线错 1000 倍,而两边都不会有编译错误。只会新增,不会重命名。
+/// 改动流程:先改 CHANGELOG(按破坏性变更写)+ README 的指标表,再改这里,最后同步 +/// MetricsContractTests 里的"字面量钉子"——那条测试故意与字面量比对,就是为了拦住"顺手改名"。 +///
+public static class TagsMetricContract +{ + /// Meter 名,使用方按它订阅:AddMeter(TagsMetricContract.MeterName)。 + /// + /// 固定为全家族共用的名字,不要按运行器/子系统拆 Meter:使用方订阅一次即可覆盖将来新增的所有指标, + /// 而 dotnet-counters --counters StdUnit.Tags 是精确匹配,拆细之后就看不到了。 + /// + public const string MeterName = "StdUnit.Tags"; + + /// 指标名:入口完整走完的轮次数(读入 → 逻辑 → 刷写)。 + public const string Turns = "stdunit.tags.turns"; + + /// 指标单位:轮次。 + public const string TurnsUnit = "{turn}"; + + /// 指标名:每轮耗时(从 EnsureConnected 到刷写输出,不含轮间等待)。 + public const string TurnDuration = "stdunit.tags.turn.duration"; + + /// 指标单位:秒。不要改成 ms——OTel 约定与既有 dashboard 都按秒。 + public const string TurnDurationUnit = "s"; + + /// 指标名:入口轮次崩溃次数(停机引起的取消不计)。 + public const string Failures = "stdunit.tags.failures"; + + /// 指标单位:次(失败)。 + public const string FailuresUnit = "{failure}"; + + /// 指标名:入口崩溃后重新建连并成功走完建连阶段的次数。 + public const string Reconnects = "stdunit.tags.reconnects"; + + /// 指标单位:次(重连)。 + public const string ReconnectsUnit = "{reconnect}"; + + /// 唯一的 tag 键:入口的定位路径 + public const string EntryTag = "entry"; +} \ No newline at end of file diff --git a/src/StdUnit.Tags/TagsProject/TagsProjectCtrl.cs b/src/StdUnit.Tags/TagsProject/TagsProjectCtrl.cs index f836b768..3c6cdbac 100644 --- a/src/StdUnit.Tags/TagsProject/TagsProjectCtrl.cs +++ b/src/StdUnit.Tags/TagsProject/TagsProjectCtrl.cs @@ -24,22 +24,23 @@ public TagsProjectCtrl(IServiceScopeFactory ssf, ILogger logger } /// - public ITagsProject? Project => this._project; + public ITagsProject? Project => this.Read().Project; /// - public TagsProjectState State => (TagsProjectState)Volatile.Read(ref this._state); + public TagsProjectState State => this.Read().State; /// - public long RunId => Volatile.Read(ref this._runId); + public long RunId => this.Read().RunId; /// public bool TryGetRunning(out ITagsProject project, out long runId) { - // 单次 volatile 读:Project 与 RunId 来自同一个不可变快照,绝不会拼出"旧项目 + 新 RunId"。 - if (this._running is { } snapshot) + // 一次读快照:状态、项目、运行号必然来自同一次运行。 + var current = this.Read(); + if (current.State == TagsProjectState.Running && current.Project is { } running) { - project = snapshot.Project; - runId = snapshot.RunId; + project = running; + runId = current.RunId; return true; } @@ -48,71 +49,107 @@ public bool TryGetRunning(out ITagsProject project, out long runId) return false; } - /// - /// "正在运行的项目 + 它的运行标识"的不可变快照。只在 期间非 null, - /// 用于让 能用一次读取取到配对的一对值。 - /// - private sealed class RunSnapshot + #region 状态快照 + // 控制器的全部可变状态集中在一个不可变快照里,只有这一个字段。 + // 任何迁移 = 构造一个新快照 + CAS 替换,因此: + // * 读者一次读取就拿到"状态 + 项目 + 运行标识 + 运行手柄"的一致组合,不会撕裂; + // * "只做一次"的副作用(派发事件、断开通道)靠 CAS 认领,只有一个赢家; + // * 不再需要 volatile 关键字,也不再需要单独的"门"字段(Handles 非 null 即表示有运行在飞)。 + + /// 一次运行的两个手柄:取消源 + "轮询已退出"信号。 + private sealed class RunHandle { - internal RunSnapshot(ITagsProject project, long runId) + internal RunHandle(CancellationTokenSource cts, TaskCompletionSource exitSource) { - this.Project = project; - this.RunId = runId; + this.Cts = cts; + this.ExitSource = exitSource; } - internal ITagsProject Project { get; } + internal CancellationTokenSource Cts { get; } - internal long RunId { get; } + /// 轮询循环已退出的信号:由 的 finally 置位。 + internal TaskCompletionSource ExitSource { get; } } - private volatile RunSnapshot? _running; - - private volatile ITagsProject? _project; - /// - /// 的底层存储(用 读写,保证 可跨线程查询)。 + /// 控制器状态的一次快照(不可变)。所有字段一起发布、一起替换。 /// - private int _state = (int)TagsProjectState.Stopped; + private sealed record Snapshot + { + /// 当前状态。 + internal TagsProjectState State { get; init; } = TagsProjectState.Stopped; - CancellationTokenSource? _cts; + /// 当前(或最近一次)运行的标识;每次启动递增。 + internal long RunId { get; init; } - private int _lock = 0; + /// 当前项目: / 期间非 null。 + internal ITagsProject? Project { get; init; } - #region 单次运行的会话状态 - // 下面这些字段都由 _lock 串行化:同一时刻最多只有一次运行,所以进入 StartPollAsync 后重置即可。 - // 但清理路径可能由 StartPollAsync 的 finally 或 StopAsync 之一执行,故用 Interlocked 保证"只做一次"。 + /// 当前运行的手柄;非 null 即表示"有运行在飞",也就是旧实现里的那道门。 + internal RunHandle? Handles { get; init; } - /// 运行标识,每次启动递增;"已启动"/"已停止"携带同一个值,便于配对。 - private long _runId; + /// 导致本次运行结束的异常;正常停机为 null。 + internal Exception? Failure { get; init; } - /// 本次运行是否已对外派发过"已启动"(只有派发过才需要补"已停止")。 - private int _startedNotified; + /// 本次运行是否已对外派发过"已启动"。 + internal bool StartedRaised { get; init; } - /// 本次运行是否已派发过"已停止"(保证最多一次)。 - private int _stopNotified; + /// 本次运行是否已派发过"已停止"。 + internal bool StoppedRaised { get; init; } - /// 通道是否已断开(保证最多一次)。 - private int _channelsDisconnected; + /// 本次运行的通道是否已断开。 + internal bool ChannelsDisconnected { get; init; } - /// 是否已由 接管收尾(此时 的 finally 不再重复断开通道/派发事件)。 - private int _stopping; + /// 收尾是否已由 接管( 的 finally 据此跳过重复收尾)。 + internal bool StopOwnsCleanup { get; init; } + } - /// 导致本次运行结束的异常;正常停机为 null。会随"已停止"事件一起派发。 - private volatile Exception? _failure; - #endregion + private Snapshot _snapshot = new(); + + private Snapshot Read() => Volatile.Read(ref this._snapshot); /// - /// 离开 时清空快照:此后 立刻返回 false, - /// 不会在停机过程中继续交出项目。 + /// 读取当前状态 curr,计算 mutate(curr) 得到新的状态 next,然后以CAS的手法更新快照。
+ ///
+ /// 函数 返回 null 表示"条件不成立、什么也不做"; 返回非null表述需要把它的结果 CAS 进去。
+ /// 如果 CAS 失败,就基于最新快照重试。
+ ///
+ /// 约定: 必须是纯函数(只看快照、不产生副作用), + /// 因为它可能被反复重试。 ///
- private void ClearRunning() => this._running = null; + private bool TryUpdate(Func mutate) + { + while (true) + { + var current = this.Read(); + var next = mutate(current); + if (next is null) + { + return false; + } + + if (this.TryOptimSwap(current, next)) + { + return true; + } - private void SetState(TagsProjectState state) => Volatile.Write(ref this._state, (int)state); + // 运行至此,说明有人抢先改了快照,重试 + } + } /// - /// "轮询循环已退出"的信号:由 的 finally 置位, 等它。 + /// 乐观锁实现:仅当快照仍是 时,才替换为 。 /// - private TaskCompletionSource? _pollExitSource; + /// 期望当前版本 + /// 要替换的新快照 + /// 如果替换成功返回 true,否则返回 false + private bool TryOptimSwap(Snapshot expected, Snapshot next) + { + var original = Interlocked.CompareExchange(ref this._snapshot, next, expected); + // 对于record,必须用 object.ReferenceEquals(a, b),不能用 == + return ReferenceEquals(original, expected); + } + #endregion /// /// 等待轮询循环退出的上限。
@@ -125,9 +162,26 @@ internal RunSnapshot(ITagsProject project, long runId) /// public async Task StartPollAsync(string? dir, XElement? root, Func hook) { - // 防止重复启动 - if (Interlocked.CompareExchange(ref _lock, 1, 0) != 0) + // 抢门 + var cts = new CancellationTokenSource(); + var exitSource = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously); + if (!this.TryUpdate(current => current.Handles is null ? + current with { + State = TagsProjectState.Starting, + RunId = current.RunId + 1, + Handles = new RunHandle(cts, exitSource), + Project = null, + Failure = null, + StartedRaised = false, + StoppedRaised = false, + ChannelsDisconnected = false, + StopOwnsCleanup = false, + } + : null) + ) { + // 失败 + cts.Dispose(); // 取一次快照再用:属性可能在启动过程中被替换 var onStartingException = this.OnStartingException; if (onStartingException != null) @@ -142,41 +196,25 @@ public async Task StartPollAsync(string? dir, XElement? root, Func(TaskCreationOptions.RunContinuationsAsynchronously); - this._pollExitSource = exitSource; - - // 这两个声明在 try 之外: - // - ct 供 catch 的 when 过滤条件使用(try 块内声明的局部变量在 catch 里不在作用域内); - // - scope 交给 finally 释放(项目里的对象可能引用作用域内的服务,所以必须先放项目、再放作用域)。 - CancellationToken ct = default; IServiceScope? scope = null; - try { scope = this._ssf.CreateScope(); var sp = scope.ServiceProvider; - var cts = new CancellationTokenSource(); - this._cts = cts; - ct = cts.Token; var project = sp.MakeProject(dir, root); - this._project = project; + this.TryUpdate(current => current with { Project = project }); await hook(project, sp, ct); - // hook 已执行完、轮询即将开始:这是唯一的"已就绪"时刻 - this.SetState(TagsProjectState.Running); - this._running = new RunSnapshot(project, runId); - Volatile.Write(ref this._startedNotified, 1); + // hook 已执行完、轮询即将开始:这是唯一的"已就绪"时刻。 + // 一次迁移同时完成"进入 Running"与"已宣告启动"标记——只有本次运行的所有者会执行到这里,且只执行一次。 + this.TryUpdate(current => current with { State = TagsProjectState.Running, StartedRaised = true }); this.RaiseStartedOrStopped(new TagsProjectEventArgs(TagsProjectState.Running, project, runId, null)); await project.RunAsync(ct); @@ -188,7 +226,7 @@ public async Task StartPollAsync(string? dir, XElement? root, Func current with { Failure = ex }); this._logger.LogError(ex, "TagsProjectCtrl.StartPollAsync error"); // 取一次快照再用:属性可能在启动过程中被替换 @@ -210,7 +248,9 @@ public async Task StartPollAsync(string? dir, XElement? root, Func s with { Project = null }); } } - this._cts = null; - // 正常停机由 StopAsync 接管收尾(它要在断开通道之后才派发"已停止")。 // 其余路径(启动失败、RunAsync 自行结束)没有 StopAsync,必须由这里补上收尾—— // 否则"已启动"永远等不到"已停止",观察者的状态会永远停在 Running,通道也不会断开。 - if (Volatile.Read(ref this._stopping) == 0) + if (!current.StopOwnsCleanup) { - this.SetState(TagsProjectState.Stopping); - this.ClearRunning(); + this.TryUpdate(s => s with { State = TagsProjectState.Stopping }); await this.DisconnectChannelsAsync(project); this.RaiseStoppedOnce(); - this.SetState(TagsProjectState.Stopped); } - Interlocked.Exchange(ref this._lock, 0); - - // 最后才置位:保证等到它的 StopAsync 看到的是"项目已释放、锁已释放"的完整状态 - exitSource.TrySetResult(true); - if (ReferenceEquals(this._pollExitSource, exitSource)) + // 结束这次运行:清手柄(= 释放门)、状态归位。门只在这里释放,StopAsync 绝不碰。 + this.TryUpdate(s => s with { - this._pollExitSource = null; - } + State = TagsProjectState.Stopped, + Handles = null, + Project = null, + }); + + // 最后才置位:保证等到它的 StopAsync 看到的是"项目已释放、门已释放"的完整状态 + handles.ExitSource.TrySetResult(true); // DI 作用域放在最后释放:通道实例可能来自作用域内的服务,必须先让它们断开(上面那步)、 // 再放作用域。这也保持了原来 `using var scope` 的"方法结束才释放"的时序。 @@ -272,26 +310,24 @@ public async Task StartPollAsync(string? dir, XElement? root, Func public async Task StopAsync() { - // 如果测点项目尚未运行,直接返回:重复调用也不应该重复派发"已停止"事件——观察者不该看到一次没人宣布过的停止。 - if (Volatile.Read(ref this._lock) == 0) + // 一次读快照就拿到"有没有运行 + 手柄 + 项目",不会读到半成品。 + var current = this.Read(); + var handles = current.Handles; + if (handles is null) { + // 未运行(或刚结束):空操作,不派生"已停止"——观察者不该看到一次没人宣布过的停止。 return; } // 声明"收尾由我负责":StartPollAsync 的 finally 会据此跳过断开通道/派发事件, // 保证"已停止"发生在通道断开之后(调用方拿它当"可以复用通道/目录"的信号)。 - Interlocked.Exchange(ref this._stopping, 1); - this.SetState(TagsProjectState.Stopping); - this.ClearRunning(); + // 同时进入 Stopping:TryGetRunning 立刻返回 false,不再交出正在拆的项目。 + this.TryUpdate(s => s with { State = TagsProjectState.Stopping, StopOwnsCleanup = true }); - var project = this._project; - var exitSource = this._pollExitSource; + var project = current.Project; try { - if (this._cts != null) - { - this._cts.Cancel(); - } + handles.Cts.Cancel(); } catch (Exception ex) { @@ -303,14 +339,14 @@ public async Task StopAsync() // 取消是协作式的:先等轮询循环真正退出。不等它就直接释放/断开,会与循环里的读/写/重连并发—— // "已停止"之后仍有通道活动,而调用方往往正是拿这个事件当"可以复用通道/目录/换配置"的信号。 - if (exitSource is not null && !await this.WaitPollExitAsync(exitSource)) + if (!await this.WaitPollExitAsync(handles.ExitSource)) { // 超时兜底:循环没能退出 ⇒ StartPollAsync 的 finally 还没机会释放项目,这里代为释放。 // 正常路径下项目已由 StartPollAsync 的 finally 释放并清空,不需要(也不能)重复释放。 - var timedOutProject = this._project; + var timedOutProject = this.Read().Project; if (timedOutProject is not null) { - this._project = null; + this.TryUpdate(s => s with { Project = null }); try { timedOutProject.Dispose(); @@ -325,9 +361,12 @@ public async Task StopAsync() await this.DisconnectChannelsAsync(project); this.RaiseStoppedOnce(); - this.SetState(TagsProjectState.Stopped); + this.TryUpdate(s => s with { State = TagsProjectState.Stopped }); - Interlocked.Exchange(ref _lock, 0); + // 有意不碰 Handles:那是 StartPollAsync 的独占门,只有它的 finally 能释放。 + // 这里若顺手清掉,会开出两个真实的洞: + // ① 启动窗口里进来时(手柄刚发布、hook 还没跑)→ 替一次"还没开始"的运行开了门,新的启动就能挤进来并发跑; + // ② 正常停机时这里若在 StartPollAsync 之后才执行 → 把"刚启动的另一次运行"的门关回去。 } /// @@ -364,21 +403,17 @@ private void RaiseStartedOrStopped(TagsProjectEventArgs args) /// private void RaiseStoppedOnce() { - if (Interlocked.Exchange(ref this._stopNotified, 1) != 0) - { - return; - } - - if (Volatile.Read(ref this._startedNotified) == 0) + if (!this.TryUpdate(s => s.StoppedRaised || !s.StartedRaised ? null : s with { StoppedRaised = true })) { return; } + var current = this.Read(); var args = new TagsProjectEventArgs( TagsProjectState.Stopped, project: null, - Volatile.Read(ref this._runId), - this._failure); + current.RunId, + current.Failure); this.RaiseStartedOrStopped(args); } @@ -394,12 +429,8 @@ private async Task DisconnectChannelsAsync(ITagsProject? project) return; } - if (Interlocked.Exchange(ref this._channelsDisconnected, 1) != 0) - { - return; - } - - if (Volatile.Read(ref this._startedNotified) == 0) + // 认领"由我来断":CAS 失败说明已经断过(或本次从未宣告过启动,通道根本没连过)。 + if (!this.TryUpdate(s => s.ChannelsDisconnected || !s.StartedRaised ? null : s with { ChannelsDisconnected = true })) { return; } diff --git a/src/StdUnit.Tags/attribs.cs b/src/StdUnit.Tags/attribs.cs index 682232ac..520fbc59 100644 --- a/src/StdUnit.Tags/attribs.cs +++ b/src/StdUnit.Tags/attribs.cs @@ -1,7 +1,8 @@ - + using System.Runtime.CompilerServices; [assembly: InternalsVisibleTo("StdUnit.Tags.S7")] [assembly: InternalsVisibleTo("StdUnit.Tags.ModbusTcp")] [assembly: InternalsVisibleTo("StdUnit.Tags.Tests")] +[assembly: InternalsVisibleTo("StdUnit.Tags.Benchmarks")] diff --git a/src/StdUnit.Tags/paket.references b/src/StdUnit.Tags/paket.references index 6bd6c8cc..d56ca223 100644 --- a/src/StdUnit.Tags/paket.references +++ b/src/StdUnit.Tags/paket.references @@ -6,4 +6,5 @@ FSharp.Core # net8.0 相关框架由共享框架提供;net472 需要包引用, System.Threading.Channels framework: net472 -IsExternalInit framework: net472 \ No newline at end of file +IsExternalInit framework: net472 +System.Diagnostics.DiagnosticSource framework: net472 \ No newline at end of file diff --git a/src/publish-packages.ps1 b/src/publish-packages.ps1 index 417e3158..2e77bee1 100644 --- a/src/publish-packages.ps1 +++ b/src/publish-packages.ps1 @@ -12,7 +12,7 @@ param ( [string]$nugetSource = $Env:NugetSource, [string]$nugetKey = $Env:NugetApiKey, - # 只打包、不推送:首次发版前用它验证产物(13 个包能不能 pack 出来),或排障时不污染包源; + # 只打包、不推送:首次发版前用它验证产物(脚本末尾 $projects 列表里的每个包都能 pack 出来),或排障时不污染包源; # CI 的 dev-packages 通道也用它——只产出"迭代产物"(配 -DevBuildNumber 传构建号),不推任何源。 [switch]$SkipPush, # 产物输出目录(为空则沿用 dotnet pack 默认:各项目自己的 bin/Release)。 @@ -45,7 +45,7 @@ if ($PSCmdlet.ParameterSetName -eq 'Dev') if ($packageVersion -notmatch $versionPattern) { $origin = if ($PSCmdlet.ParameterSetName -eq 'Dev') { "next-release-version.txt 与 -DevBuildNumber 拼出的版本" } else { "-packageVersion" } - throw "$origin 必须是 ..[-] 形式(如 1.0.0 或 1.0.0-rc.1),当前为:$packageVersion"; + throw "$origin 必须是 ..[-] 形式(如 1.0.0 或 2.0.0-dev.261113.0930),当前为:$packageVersion"; } if (-not $SkipPush) @@ -109,8 +109,16 @@ $projects | ForEach-Object -Process{ try{ Write-Host "[-] current location: $distPath" - # 用数组 splat,避免 -OutputDir 带空格时被拆成多个参数 - $packArgs = @("-c", "Release", "-p:PackageVersion=$($packageVersion)") + # 用数组 splat,避免 -OutputDir 带空格时被拆成多个参数。 + # 同时注入 InformationalVersion:它默认派生自 $(Version)(恒为 1.0.0),不注入的话每个版本发布出去的 + # 程序集都自称 1.0.0——崩溃日志、dotnet-counters / OTel 的 scope 版本、以及任何读 AssemblyInformationalVersion + # 的地方都会拿到错值。只设 InformationalVersion、不动 Version,是为了让 AssemblyVersion 稳定在 1.0.0.0 + # (程序集身份不随补丁版跳动,net472 的绑定重定向也不用跟着改)。 + $packArgs = @( + "-c", "Release", + "-p:PackageVersion=$($packageVersion)", + "-p:InformationalVersion=$($packageVersion)" + ) if (-not [String]::IsNullOrEmpty($OutputDir)) { $packArgs += @("-o", $OutputDir) diff --git a/tests/StdUnit.Tags.Tests/Core/AccessModeInheritanceTests.cs b/tests/StdUnit.Tags.Tests/Core/AccessModeInheritanceTests.cs new file mode 100644 index 00000000..f0497503 --- /dev/null +++ b/tests/StdUnit.Tags.Tests/Core/AccessModeInheritanceTests.cs @@ -0,0 +1,117 @@ +using System.Threading; +using System.Threading.Tasks; +using StdUnit.Tags.Tests.Fakes; +using Xunit; + +namespace StdUnit.Tags.Tests.Core; + +/// +/// 访问模式(access)的继承语义:**逐级冒泡**——自身 → 父级 Cbnt → 各级 Grp → 默认 RW。
+/// 历史上 / 只查"直接父级自己配了没", +/// 于是 `Grp(RO) → Cbnt(未配) → Tag` 会被误判成 RW(而 `Grp(RO) → Tag` 却是 RO)。2.0 统一为逐级冒泡。 +///
+public class AccessModeInheritanceTests +{ + private static TagGrp NewGroup(string name, TagAccessMode? access = null) + => new(new TagGrpDescriptor { Name = name, AccessMode = access }, new FakedChannel(new TagChannelDescriptor { Name = "ch" })); + + private static FakedTagCbnt NewCbnt(string name, TagAccessMode? access = null) + => new(new TagCbntDescriptor { Name = name, AccessMode = access }); + + private static FakedTag NewTag(string name, ITagGrp parent, TagAccessMode? access = null) + => new(new TagDescriptor { TagName = name, AccessMode = access }, new FakedChannel(new TagChannelDescriptor { Name = "ch" }), parent); + + [Fact] + public void Tag_WithNothingConfigured_DefaultsToRW() + { + var grp = NewGroup("g"); + var tag = NewTag("t", grp); + grp.AddTag(tag); + + Assert.Equal(TagAccessMode.RW, tag.SearchAccessMode()); + } + + [Fact] + public void Tag_InheritsFromDirectParentGroup() + { + var grp = NewGroup("g", TagAccessMode.RO); + var tag = NewTag("t", grp); + grp.AddTag(tag); + + Assert.Equal(TagAccessMode.RO, tag.SearchAccessMode()); + } + + /// 核心回归:隔一层未配置的 Cbnt,也必须继承到祖先 Grp 的配置。 + [Fact] + public void Tag_InheritsThroughUnconfiguredCbntFromGrandparentGroup() + { + var grp = NewGroup("g", TagAccessMode.RO); + var cbnt = NewCbnt("c"); // 未配置 access + grp.AddTag(cbnt); + + var tag = NewTag("t", grp); + tag.Parent = TagContainer.From(cbnt); // 父容器是 Cbnt + + Assert.Equal(TagAccessMode.RO, cbnt.SearchAccessMode()); + Assert.Equal(TagAccessMode.RO, tag.SearchAccessMode()); + } + + [Fact] + public void Cbnt_OverridesAncestor() + { + var grp = NewGroup("g", TagAccessMode.RO); + var cbnt = NewCbnt("c", TagAccessMode.WO); + grp.AddTag(cbnt); + + var tag = NewTag("t", grp); + tag.Parent = TagContainer.From(cbnt); + + Assert.Equal(TagAccessMode.WO, cbnt.SearchAccessMode()); + Assert.Equal(TagAccessMode.WO, tag.SearchAccessMode()); + } + + [Fact] + public void Tag_OverridesAllAncestors() + { + var grp = NewGroup("g", TagAccessMode.RO); + var cbnt = NewCbnt("c", TagAccessMode.WO); + grp.AddTag(cbnt); + + var tag = NewTag("t", grp, TagAccessMode.R1W); + tag.Parent = TagContainer.From(cbnt); + + Assert.Equal(TagAccessMode.R1W, tag.SearchAccessMode()); + } + + [Fact] + public void Tag_InheritsThroughNestedGroups() + { + var outer = NewGroup("outer", TagAccessMode.RO); + var inner = NewGroup("inner"); // 未配置 + outer.AddTag(inner); + + var tag = NewTag("t", inner); + inner.AddTag(tag); + + Assert.Equal(TagAccessMode.RO, inner.SearchAccessMode()); + Assert.Equal(TagAccessMode.RO, tag.SearchAccessMode()); + } + + /// + /// 运行期缓存:同一 反复读取时,解析结果被缓存且值保持正确。 + /// ("访问模式是配置期属性"是缓存成立的前提,见 。) + /// + [Fact] + public async Task ReadAsync_CachesInheritedAccessMode() + { + var grp = NewGroup("g", TagAccessMode.RO); + var tag = NewTag("t", grp); + grp.AddTag(tag); + var union = grp["t"]; + + await union.ReadAsync(TraversalMode.IgnoreEnabled, CancellationToken.None); + await union.ReadAsync(TraversalMode.IgnoreEnabled, CancellationToken.None); + + Assert.Equal(TagAccessMode.RO, union.CachedAccessMode); + } +} \ No newline at end of file diff --git a/tests/StdUnit.Tags.Tests/Core/TagGrpRunners/DefaultTagGrpRunnerDisconnectStrategyTests.cs b/tests/StdUnit.Tags.Tests/Core/TagGrpRunners/DefaultTagGrpRunnerDisconnectStrategyTests.cs new file mode 100644 index 00000000..735e9654 --- /dev/null +++ b/tests/StdUnit.Tags.Tests/Core/TagGrpRunners/DefaultTagGrpRunnerDisconnectStrategyTests.cs @@ -0,0 +1,59 @@ +using System; +using System.Threading.Tasks; +using Xunit; + +namespace StdUnit.Tags.Tests.Core.TagGrpRunners; + +/// +/// :有限超时等待,且"已经失败的断开"必须让调用方看见。 +/// +public class DefaultTagGrpRunnerDisconnectStrategyTests +{ + private static DefaultTagGrpRunnerDisconnectStrategy NewStrategy(TimeSpan? timeout = null) => new() + { + Timeout = timeout ?? TimeSpan.FromSeconds(5) + }; + + /// 无需断开时立即返回 + [Fact] + public async Task WaitDisconnectAsync_WhenDisconnectIsNull_Completes() + { + var strategy = NewStrategy(); + + await strategy.WaitDisconnectAsync(null, null); + } + + /// 断开正常完成时透传完成状态 + [Fact] + public async Task WaitDisconnectAsync_WhenDisconnectSucceeds_Completes() + { + var strategy = NewStrategy(); + + await strategy.WaitDisconnectAsync(null, Task.CompletedTask); + } + + /// + /// 断开失败必须外抛:否则故障 Task 永远没人 await(UnobservedTaskException), + /// 运行器也不会记下"连接没断干净"。 + /// + [Fact] + public async Task WaitDisconnectAsync_WhenDisconnectFaulted_Propagates() + { + var strategy = NewStrategy(); + var faulted = Task.FromException(new InvalidOperationException("boom")); + + await Assert.ThrowsAsync(() => strategy.WaitDisconnectAsync(null, faulted)); + } + + /// 断开迟迟不完成时按超时返回,不无限阻塞清理路径 + [Fact] + public async Task WaitDisconnectAsync_WhenDisconnectHangs_ReturnsAfterTimeout() + { + var strategy = NewStrategy(TimeSpan.FromMilliseconds(20)); + var neverCompletes = new TaskCompletionSource().Task; + + await strategy.WaitDisconnectAsync(null, neverCompletes); + + Assert.False(neverCompletes.IsCompleted); + } +} diff --git a/tests/StdUnit.Tags.Tests/Core/TagGrpRunners/DirtyNodeIndexTests.cs b/tests/StdUnit.Tags.Tests/Core/TagGrpRunners/DirtyNodeIndexTests.cs new file mode 100644 index 00000000..07155212 --- /dev/null +++ b/tests/StdUnit.Tags.Tests/Core/TagGrpRunners/DirtyNodeIndexTests.cs @@ -0,0 +1,119 @@ +using StdUnit.Tags.Tests.Fakes; +using Xunit; + +namespace StdUnit.Tags.Tests.Core.TagGrpRunners; + +/// +/// 与 的等价性:索引只收录 Tag / Cbnt, +/// 正是 IsDirty() 的语义;任何一处不一致都会让运行器"该写的没写"或"白走一趟"。 +/// +public class DirtyNodeIndexTests +{ + private static TagGrp NewGroup(string name) => + new(new TagGrpDescriptor { Name = name }, new FakedChannel(new TagChannelDescriptor { Name = "ch" })); + + private static FakedTag NewTag(string name, ITagGrp parent) => + new(new TagDescriptor { TagName = name }, new FakedChannel(new TagChannelDescriptor { Name = "ch" }), parent); + + private static FakedTagCbnt NewCbnt(string name) => new(new TagCbntDescriptor { Name = name }); + + private static void AssertEquivalent(ITagGrp entry) + { + var index = DirtyNodeIndex.Build(entry); + Assert.Equal(entry.IsDirty(), index.AnyDirty()); + } + + [Fact] + public void EmptyEntry_IsClean() + { + var entry = NewGroup("entry"); + var index = DirtyNodeIndex.Build(entry); + + Assert.False(index.AnyDirty()); + AssertEquivalent(entry); + } + + [Fact] + public void DirtyTag_IsDetected() + { + var entry = NewGroup("entry"); + var tag = NewTag("t", entry); + entry.AddTag(tag); + + var index = DirtyNodeIndex.Build(entry); + Assert.False(index.AnyDirty()); + + tag.IsDirty = true; + Assert.True(index.AnyDirty()); + AssertEquivalent(entry); + + tag.IsDirty = false; + Assert.False(index.AnyDirty()); + AssertEquivalent(entry); + } + + [Fact] + public void DirtyCbnt_IsDetected() + { + var entry = NewGroup("entry"); + var cbnt = NewCbnt("c"); + entry.AddTag(cbnt); + + var index = DirtyNodeIndex.Build(entry); + Assert.False(index.AnyDirty()); + + cbnt.IsDirty = true; + Assert.True(index.AnyDirty()); + AssertEquivalent(entry); + } + + [Fact] + public void DirtyTag_InNestedGroup_IsDetected() + { + var entry = NewGroup("entry"); + var inner = NewGroup("inner"); + entry.AddTag(inner); + var tag = NewTag("t", inner); + inner.AddTag(tag); + + var index = DirtyNodeIndex.Build(entry); + Assert.False(index.AnyDirty()); + + tag.IsDirty = true; + Assert.True(index.AnyDirty()); + AssertEquivalent(entry); + } + + [Fact] + public void MixedTree_StaysEquivalent() + { + var entry = NewGroup("entry"); + var t1 = NewTag("t1", entry); + var c1 = NewCbnt("c1"); + var nested = NewGroup("nested"); + var t2 = NewTag("t2", nested); + entry.AddTag(t1); + entry.AddTag(c1); + entry.AddTag(nested); + nested.AddTag(t2); + + var index = DirtyNodeIndex.Build(entry); + + Assert.False(index.AnyDirty()); + AssertEquivalent(entry); + + c1.IsDirty = true; + Assert.True(index.AnyDirty()); + AssertEquivalent(entry); + + c1.IsDirty = false; + t2.IsDirty = true; + Assert.True(index.AnyDirty()); + AssertEquivalent(entry); + + t2.IsDirty = false; + t1.IsDirty = true; + Assert.True(index.AnyDirty()); + AssertEquivalent(entry); + } +} diff --git a/tests/StdUnit.Tags.Tests/Core/TagGrpRunners/MetricsContractTests.cs b/tests/StdUnit.Tags.Tests/Core/TagGrpRunners/MetricsContractTests.cs new file mode 100644 index 00000000..4ae287b3 --- /dev/null +++ b/tests/StdUnit.Tags.Tests/Core/TagGrpRunners/MetricsContractTests.cs @@ -0,0 +1,174 @@ +using System; +using System.Collections.Generic; +using System.Diagnostics.Metrics; +using System.Threading.Tasks; +using Xunit; + +namespace StdUnit.Tags.Tests.Core.TagGrpRunners; + +/// +/// (公开契约:名称/单位/tag 键)与 (实际注册与记录)的固化测试: +/// Meter 名、指标名、单位、tag 键一旦改名,使用方的 dashboard 会静默变空,所以用字面量钉住; +/// 同时验证这些常量确实被传给了 Meter.CreateCounter/CreateHistogram,而不只是两个字符串相等。 +/// +public class MetricsContractTests +{ + private static bool HasEntryTag(ReadOnlySpan> tags, string expected) + { + foreach (var tag in tags) + { + if (tag.Key == "entry" && Equals(tag.Value, expected)) + { + return true; + } + } + + return false; + } + + [Fact] + public void Meter_Name_IsStable() + { + Assert.Equal("StdUnit.Tags", TagsMetricContract.MeterName); + } + + /// + /// 把每个契约字符串钉在字面量上。
+ /// 常量本身改起来毫无编译阻力,但使用方的 dashboard 会静默变空——这条测试就是那道阻力: + /// 谁改了常量,这里先红;要放行就得连同 CHANGELOG / README 一起改(见 的契约区注释)。 + ///
+ [Fact] + public void ContractStrings_ArePinned() + { + Assert.Equal("stdunit.tags.turns", TagsMetricContract.Turns); + Assert.Equal("{turn}", TagsMetricContract.TurnsUnit); + + Assert.Equal("stdunit.tags.turn.duration", TagsMetricContract.TurnDuration); + Assert.Equal("s", TagsMetricContract.TurnDurationUnit); + + Assert.Equal("stdunit.tags.failures", TagsMetricContract.Failures); + Assert.Equal("{failure}", TagsMetricContract.FailuresUnit); + + Assert.Equal("stdunit.tags.reconnects", TagsMetricContract.Reconnects); + Assert.Equal("{reconnect}", TagsMetricContract.ReconnectsUnit); + + Assert.Equal("entry", TagsMetricContract.EntryTag); + } + + /// 四个指标的名称与单位(单位属于契约:`s` 而不是 `ms`) + [Fact] + public void Instruments_HaveStableNamesAndUnits() + { + var units = new Dictionary(); + using var listener = new MeterListener + { + InstrumentPublished = (instrument, l) => + { + if (instrument.Meter.Name != TagsMetricContract.MeterName) + { + return; + } + + units[instrument.Name] = instrument.Unit; + l.EnableMeasurementEvents(instrument); + } + }; + listener.Start(); + + // 触发静态构造(指标在静态 ctor 里创建) + TagsMetric.RecordTurn( + new[] { new KeyValuePair("entry", "unit-test") }, + TimeSpan.FromMilliseconds(1)); + + Assert.Equal("s", units["stdunit.tags.turn.duration"]); + Assert.Equal("{turn}", units["stdunit.tags.turns"]); + Assert.Equal("{failure}", units["stdunit.tags.failures"]); + Assert.Equal("{reconnect}", units["stdunit.tags.reconnects"]); + } + + /// 一次轮次记录 = counter +1、histogram 记秒数,且都带 entry 维度 + [Fact] + public void RecordTurn_RecordsCounterAndHistogram_WithEntryTag() + { + var entry = "record-turn-" + Guid.NewGuid().ToString("N"); + var tags = new[] { new KeyValuePair("entry", entry) }; + + long turns = -1; + double seconds = double.NaN; + using var listener = new MeterListener + { + InstrumentPublished = (instrument, l) => + { + if (instrument.Meter.Name == TagsMetricContract.MeterName) + { + l.EnableMeasurementEvents(instrument); + } + } + }; + listener.SetMeasurementEventCallback((instrument, value, tagList, state) => + { + if (instrument.Name == "stdunit.tags.turns" && HasEntryTag(tagList, entry)) + { + turns = value; + } + }); + listener.SetMeasurementEventCallback((instrument, value, tagList, state) => + { + if (instrument.Name == "stdunit.tags.turn.duration" && HasEntryTag(tagList, entry)) + { + seconds = value; + } + }); + listener.Start(); + + TagsMetric.RecordTurn(tags, TimeSpan.FromSeconds(1.5)); + + Assert.Equal(1, turns); + Assert.Equal(1.5, seconds, 9); + } + + /// + /// 崩溃与恢复各自 +1,且只带 entry 维度(不带 driver——失败可能来自辅通道,标注主通道会算错责任人)。 + /// + [Fact] + public void RecordFailureAndReconnect_OnlyCarryEntryTag() + { + var entry = "record-failure-" + Guid.NewGuid().ToString("N"); + var tags = new[] { new KeyValuePair("entry", entry) }; + + var seen = new Dictionary(); + var tagKeys = new List(); + using var listener = new MeterListener + { + InstrumentPublished = (instrument, l) => + { + if (instrument.Meter.Name == TagsMetricContract.MeterName) + { + l.EnableMeasurementEvents(instrument); + } + } + }; + listener.SetMeasurementEventCallback((instrument, value, tagList, state) => + { + if (!HasEntryTag(tagList, entry)) + { + return; + } + + seen.TryGetValue(instrument.Name, out var current); + seen[instrument.Name] = current + (int)value; + foreach (var tag in tagList) + { + tagKeys.Add(tag.Key); + } + }); + listener.Start(); + + TagsMetric.RecordFailure(tags); + TagsMetric.RecordReconnect(tags); + + Assert.Equal(1, seen["stdunit.tags.failures"]); + Assert.Equal(1, seen["stdunit.tags.reconnects"]); + Assert.All(tagKeys, key => Assert.Equal("entry", key)); + } +} diff --git a/tests/StdUnit.Tags.Tests/Core/TagGrpRunners/TagGrpRunnerTests.cs b/tests/StdUnit.Tags.Tests/Core/TagGrpRunners/TagGrpRunnerTests.cs index 06d833a0..e5638bb9 100644 --- a/tests/StdUnit.Tags.Tests/Core/TagGrpRunners/TagGrpRunnerTests.cs +++ b/tests/StdUnit.Tags.Tests/Core/TagGrpRunners/TagGrpRunnerTests.cs @@ -1,6 +1,7 @@ using System; using System.Collections.Concurrent; using System.Collections.Generic; +using System.Diagnostics.Metrics; using System.Threading; using System.Threading.Channels; using System.Threading.Tasks; @@ -42,6 +43,23 @@ private async Task RunUntilCancelled(TagGrpRunner runner, ITagGrp entry, Cancell } } + /// + /// 往 mock 入口挂一个子测点。MockTagGrp.IsDirty() 按 的契约汇总子节点, + /// 所以"入口是否脏"必须通过子节点表达。 + /// + private static FakedTag AddTag(MockTagGrp entry, bool dirty = false) + { + var tag = new FakedTag( + new TagDescriptor { TagName = $"t{entry.Children.Count}" }, + new FakedChannel(new TagChannelDescriptor { Name = "ch" }), + entry) + { + IsDirty = dirty, + }; + entry.Children.Add(tag.TagName(), new TagUnion.TagUnit(tag)); + return tag; + } + [Fact] public async Task StartAsync_NormalLoop_CallsReadWriteAndEvents() { @@ -49,6 +67,7 @@ public async Task StartAsync_NormalLoop_CallsReadWriteAndEvents() var (runner, entry, _, _) = CreateRunner(); entry.Descriptor!.ScanInterval = 20; entry.IsEnabled = true; + AddTag(entry, dirty: true); // 有脏数据才会触发写 using var cts = new CancellationTokenSource(); var turnStartedCalled = false; @@ -195,6 +214,8 @@ public async Task StartAsync_TurnProcessEvent_FiresAfterRead() using var cts = new CancellationTokenSource(); var processOrder = new List(); + // 先干净,逻辑处理时才变脏——这样第一次写必然发生在 Read/Process 之后。 + var tag = AddTag(entry); entry.OnRead = () => processOrder.Add("Read"); entry.OnWrite = () => processOrder.Add("Write"); @@ -202,6 +223,7 @@ public async Task StartAsync_TurnProcessEvent_FiresAfterRead() runner.TurnProcess += (grp, ch, _) => { processOrder.Add("Process"); + tag.IsDirty = true; cts.Cancel(); return Task.CompletedTask; }; @@ -225,7 +247,7 @@ public async Task StartAsync_IsDirty_CallsWriteBeforeRead() var (runner, entry, _, _) = CreateRunner(); entry.Descriptor!.ScanInterval = 20; entry.IsEnabled = true; - entry.IsDirtyReturn = true; + AddTag(entry, dirty: true); using var cts = new CancellationTokenSource(); var callOrder = new List(); @@ -818,6 +840,56 @@ public async Task StartAsync_WithRealTagGrp_RespectsIsEnabledOfChildren() Assert.Equal(1, enabled.WriteCount); } + /// + /// 运行器把每轮记进 Metrics:stdunit.tags.turns 至少有一条带该入口路径的测量。 + /// 用 MeterListener 的完成信号而不是"等一会儿再断言",避免机器忙时的随机红。 + /// + [Fact] + public async Task StartAsync_RecordsTurnMetrics() + { + var (runner, entry, _, _) = CreateRunner(); + entry.Descriptor!.Name = "metrics-" + Guid.NewGuid().ToString("N"); + entry.Descriptor!.ScanInterval = 10; + entry.IsEnabled = true; + var expectedEntry = entry.GetLocationPath(); + + var turnRecorded = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously); + using var listener = new MeterListener(); + listener.InstrumentPublished = (instrument, l) => + { + if (instrument.Meter.Name == TagsMetricContract.MeterName) + { + l.EnableMeasurementEvents(instrument); + } + }; + listener.SetMeasurementEventCallback((instrument, value, tagList, state) => + { + if (instrument.Name != "stdunit.tags.turns") + { + return; + } + + foreach (var tag in tagList) + { + if (tag.Key == "entry" && Equals(tag.Value, expectedEntry)) + { + turnRecorded.TrySetResult(true); + return; + } + } + }); + listener.Start(); + + using var cts = new CancellationTokenSource(); + var runTask = RunUntilCancelled(runner, entry, cts.Token); + + var completed = await Task.WhenAny(turnRecorded.Task, Task.Delay(TimeSpan.FromSeconds(15))); + Assert.Same(turnRecorded.Task, completed); + + cts.Cancel(); + await runTask; + } + #region Mocks /// @@ -909,7 +981,6 @@ public bool IsEnabled /// 如果不为 null,则 ReadAsync 会抛出此异常。 /// public Exception? ReadAsyncThrows { get; set; } - public bool IsDirtyReturn { get; set; } public Action? OnRead { get; set; } public Action? OnWrite { get; set; } @@ -931,7 +1002,19 @@ public Task WriteAsync(TraversalMode mode, CancellationToken ct) return Task.CompletedTask; } - public bool IsDirty() => IsDirtyReturn; + /// 按契约实现:等价于"子树中任一 Tag/Cbnt 已脏",组自身不持有脏标记。 + public bool IsDirty() + { + foreach (var child in this.Children.Values) + { + if (child.IsDirty()) + { + return true; + } + } + + return false; + } } private class MockProject : ITagsProject diff --git a/tests/StdUnit.Tags.Tests/Core/TagUnions/TagUnionExtensions_ReadWrite_Tests.cs b/tests/StdUnit.Tags.Tests/Core/TagUnions/TagUnionExtensions_ReadWrite_Tests.cs new file mode 100644 index 00000000..cabfda86 --- /dev/null +++ b/tests/StdUnit.Tags.Tests/Core/TagUnions/TagUnionExtensions_ReadWrite_Tests.cs @@ -0,0 +1,357 @@ +using System; +using System.Collections.Generic; +using System.Threading; +using System.Threading.Tasks; +using Xunit; + +namespace StdUnit.Tags.Tests.Core.TagUnions; + +/// +/// / +/// 的分支语义:
+/// 访问模式(R1W / WO / RO)、"读后标记 IsScanned"(同步完成走快路径、真异步走续体)、以及封闭类型之外的兜底。 +///
+public class TagUnionExtensions_ReadWrite_Tests +{ + private sealed class FakeTag : ITag + { + public FakeTag(TagAccessMode? access = null) + => TagDescriptor = new TagDescriptor { TagName = "t", AccessMode = access }; + + public TagDescriptor TagDescriptor { get; set; } + public object? Value { get; set; } + public DateTime Timestamp { get; set; } + + public event TagSyncEventHandler OnTagRead { add { } remove { } } + public event TagSyncEventHandler OnTagWritten { add { } remove { } } + + public bool IsScanned { get; set; } + public bool IsDirty { get; set; } + public ITagChannel? Channel => null; + public TagContainer? Parent { get; set; } + + /// 非 null 时, 返回这个未完成的 Task(模拟设备 I/O)。 + public Task? PendingRead { get; set; } + + public int ReadCount { get; private set; } + public int WriteCount { get; private set; } + + public Task ReadAsync(CancellationToken ct) + { + ReadCount++; + return PendingRead ?? Task.CompletedTask; + } + + public Task WriteAsync(CancellationToken ct) + { + WriteCount++; + IsDirty = false; + return Task.CompletedTask; + } + } + + private sealed class FakeCbnt : ITagCbnt + { + public FakeCbnt(TagAccessMode? access = null) + => Descriptor = new TagCbntDescriptor { Name = "c", AccessMode = access }; + + public TagCbntDescriptor Descriptor { get; set; } + public ITagGrp? Parent { get; set; } + + private readonly Dictionary _children = new(); + public IDictionary Children => _children; + public ITagCbntor this[string key] => _children[key]; + + public bool IsEnabled { get; set; } = true; + public bool IsScanned { get; set; } + public ITagChannel? Channel { get; set; } + public string StartAddress { get; set; } = string.Empty; + public bool IsDirty { get; set; } + + /// 非 null 时, 返回这个未完成的 Task(模拟设备 I/O)。 + public Task? PendingRead { get; set; } + + public int ReadCount { get; private set; } + public int WriteCount { get; private set; } + + public Task ReadAsync(CancellationToken ct) + { + ReadCount++; + return PendingRead ?? Task.CompletedTask; + } + + public Task WriteAsync(CancellationToken ct) + { + WriteCount++; + IsDirty = false; + return Task.CompletedTask; + } + } + + /// + /// 是公开的抽象 record,第三方可以派生——兜底分支必须显式失败而不是静默跳过。 + /// + private sealed record UnknownUnion : TagUnion + { + public override void Accept(ITagUnionVisitor visitor) => throw new NotSupportedException(); + } + + private static TaskCompletionSource PendingCompletion() => + new(TaskCreationOptions.RunContinuationsAsynchronously); + + #region ReadAsync — 访问模式 + + [Fact] + public async Task ReadAsync_TagUnit_R1W_AlreadyScanned_DoesNotRead() + { + var tag = new FakeTag(TagAccessMode.R1W) { IsScanned = true }; + var union = new TagUnion.TagUnit(tag); + + await union.ReadAsync(TraversalMode.IgnoreEnabled, CancellationToken.None); + + Assert.Equal(0, tag.ReadCount); + Assert.True(tag.IsScanned); + } + + [Fact] + public async Task ReadAsync_TagUnit_R1W_NotScanned_ReadsAndMarksScanned() + { + var tag = new FakeTag(TagAccessMode.R1W); + var union = new TagUnion.TagUnit(tag); + + await union.ReadAsync(TraversalMode.IgnoreEnabled, CancellationToken.None); + + Assert.Equal(1, tag.ReadCount); + Assert.True(tag.IsScanned); + } + + [Fact] + public async Task ReadAsync_TagUnit_WriteOnly_DoesNotRead() + { + var tag = new FakeTag(TagAccessMode.WO); + var union = new TagUnion.TagUnit(tag); + + await union.ReadAsync(TraversalMode.IgnoreEnabled, CancellationToken.None); + + Assert.Equal(0, tag.ReadCount); + Assert.False(tag.IsScanned); + } + + [Fact] + public async Task ReadAsync_TagUnit_ReadOnly_Reads() + { + var tag = new FakeTag(TagAccessMode.RO); + var union = new TagUnion.TagUnit(tag); + + await union.ReadAsync(TraversalMode.IgnoreEnabled, CancellationToken.None); + + Assert.Equal(1, tag.ReadCount); + } + + [Fact] + public async Task ReadAsync_TagUnit_AsyncRead_MarksScannedAfterCompletion() + { + var tag = new FakeTag(); + var tcs = PendingCompletion(); + tag.PendingRead = tcs.Task; + var union = new TagUnion.TagUnit(tag); + + var readTask = union.ReadAsync(TraversalMode.IgnoreEnabled, CancellationToken.None); + + Assert.False(readTask.IsCompleted); + Assert.False(tag.IsScanned); + + tcs.SetResult(true); + await readTask; + + Assert.True(tag.IsScanned); + } + + [Fact] + public async Task ReadAsync_TagCbnt_R1W_AlreadyScanned_DoesNotRead() + { + var cbnt = new FakeCbnt(TagAccessMode.R1W) { IsScanned = true }; + var union = new TagUnion.TagCbnt(cbnt); + + await union.ReadAsync(TraversalMode.IgnoreEnabled, CancellationToken.None); + + Assert.Equal(0, cbnt.ReadCount); + } + + [Fact] + public async Task ReadAsync_TagCbnt_R1W_NotScanned_ReadsAndMarksScanned() + { + var cbnt = new FakeCbnt(TagAccessMode.R1W); + var union = new TagUnion.TagCbnt(cbnt); + + await union.ReadAsync(TraversalMode.IgnoreEnabled, CancellationToken.None); + + Assert.Equal(1, cbnt.ReadCount); + Assert.True(cbnt.IsScanned); + } + + [Fact] + public async Task ReadAsync_TagCbnt_WriteOnly_DoesNotRead() + { + var cbnt = new FakeCbnt(TagAccessMode.WO); + var union = new TagUnion.TagCbnt(cbnt); + + await union.ReadAsync(TraversalMode.IgnoreEnabled, CancellationToken.None); + + Assert.Equal(0, cbnt.ReadCount); + } + + [Fact] + public async Task ReadAsync_TagCbnt_AsyncRead_MarksScannedAfterCompletion() + { + var cbnt = new FakeCbnt(); + var tcs = PendingCompletion(); + cbnt.PendingRead = tcs.Task; + var union = new TagUnion.TagCbnt(cbnt); + + var readTask = union.ReadAsync(TraversalMode.IgnoreEnabled, CancellationToken.None); + + Assert.False(readTask.IsCompleted); + Assert.False(cbnt.IsScanned); + + tcs.SetResult(true); + await readTask; + + Assert.True(cbnt.IsScanned); + } + + [Fact] + public async Task ReadAsync_TagCbnt_RespectEnabled_WhenDisabled_DoesNotRead() + { + var cbnt = new FakeCbnt { IsEnabled = false }; + var union = new TagUnion.TagCbnt(cbnt); + + await union.ReadAsync(TraversalMode.RespectEnabled, CancellationToken.None); + + Assert.Equal(0, cbnt.ReadCount); + } + + #endregion + + #region WriteAsync — 访问模式与脏标记 + + [Fact] + public async Task WriteAsync_TagUnit_ReadOnly_DoesNotWrite() + { + var tag = new FakeTag(TagAccessMode.RO) { IsDirty = true }; + var union = new TagUnion.TagUnit(tag); + + await union.WriteAsync(TraversalMode.IgnoreEnabled, CancellationToken.None); + + Assert.Equal(0, tag.WriteCount); + Assert.True(tag.IsDirty); + } + + [Fact] + public async Task WriteAsync_TagUnit_NotDirty_DoesNotWrite() + { + var tag = new FakeTag(TagAccessMode.RW); + var union = new TagUnion.TagUnit(tag); + + await union.WriteAsync(TraversalMode.IgnoreEnabled, CancellationToken.None); + + Assert.Equal(0, tag.WriteCount); + } + + [Fact] + public async Task WriteAsync_TagUnit_Dirty_AndWritable_Writes() + { + var tag = new FakeTag(TagAccessMode.RW) { IsDirty = true }; + var union = new TagUnion.TagUnit(tag); + + await union.WriteAsync(TraversalMode.IgnoreEnabled, CancellationToken.None); + + Assert.Equal(1, tag.WriteCount); + Assert.False(tag.IsDirty); + } + + [Fact] + public async Task WriteAsync_TagCbnt_ReadOnly_DoesNotWrite() + { + var cbnt = new FakeCbnt(TagAccessMode.RO) { IsDirty = true }; + var union = new TagUnion.TagCbnt(cbnt); + + await union.WriteAsync(TraversalMode.IgnoreEnabled, CancellationToken.None); + + Assert.Equal(0, cbnt.WriteCount); + } + + [Fact] + public async Task WriteAsync_TagCbnt_Dirty_AndWritable_Writes() + { + var cbnt = new FakeCbnt(TagAccessMode.RW) { IsDirty = true }; + var union = new TagUnion.TagCbnt(cbnt); + + await union.WriteAsync(TraversalMode.IgnoreEnabled, CancellationToken.None); + + Assert.Equal(1, cbnt.WriteCount); + Assert.False(cbnt.IsDirty); + } + + [Fact] + public async Task WriteAsync_TagCbnt_RespectEnabled_WhenDisabled_KeepsDirty() + { + var cbnt = new FakeCbnt { IsEnabled = false, IsDirty = true }; + var union = new TagUnion.TagCbnt(cbnt); + + await union.WriteAsync(TraversalMode.RespectEnabled, CancellationToken.None); + + Assert.Equal(0, cbnt.WriteCount); + Assert.True(cbnt.IsDirty); + } + + [Fact] + public async Task WriteAsync_TagGrp_DelegatesToGroup() + { + var tag = new FakeTag { IsDirty = true }; + var grp = new TagGrp(new TagGrpDescriptor { Name = "g", IsEntry = true }, null); + grp.AddTag(tag); + + await new TagUnion.TagGrp(grp).WriteAsync(TraversalMode.IgnoreEnabled, CancellationToken.None); + + Assert.Equal(1, tag.WriteCount); + } + + #endregion + + #region 封闭类型之外的兜底 + + [Fact] + public async Task ReadAsync_UnknownUnion_ReturnsFaultedTask() + { + var union = new UnknownUnion(); + + var ex = await Assert.ThrowsAsync( + () => union.ReadAsync(TraversalMode.IgnoreEnabled, CancellationToken.None)); + + Assert.Contains("unknown types", ex.Message); + } + + [Fact] + public async Task WriteAsync_UnknownUnion_ReturnsFaultedTask() + { + var union = new UnknownUnion(); + + var ex = await Assert.ThrowsAsync( + () => union.WriteAsync(TraversalMode.IgnoreEnabled, CancellationToken.None)); + + Assert.Contains("unknown types", ex.Message); + } + + [Fact] + public void IsDirty_UnknownUnion_Throws() + { + var union = new UnknownUnion(); + + var ex = Assert.Throws(() => union.IsDirty()); + + Assert.Contains("unknown types", ex.Message); + } + + #endregion +} diff --git a/tests/StdUnit.Tags.Tests/Core/TagsProjectCtrls/TagsProjectCtrlTests.cs b/tests/StdUnit.Tags.Tests/Core/TagsProjectCtrls/TagsProjectCtrlTests.cs index c187c593..d7c40f2a 100644 --- a/tests/StdUnit.Tags.Tests/Core/TagsProjectCtrls/TagsProjectCtrlTests.cs +++ b/tests/StdUnit.Tags.Tests/Core/TagsProjectCtrls/TagsProjectCtrlTests.cs @@ -1266,6 +1266,34 @@ public async Task StopAsync_WhenChannelListContainsNull_SkipsNullEntry() sp.Dispose(); } + /// + /// 轮询不响应取消、StopAsync 超时返回后:那一次运行其实还活着(卡在 RunAsync 里), + /// 所以独占门必须仍然关着——否则第二次启动会与旧循环并发操作同一个控制器。 + /// + [Fact] + public async Task StopAsync_WhenPollingNeverExits_KeepsGateClosedSoRestartIsRejected() + { + var (ctrl, sp) = CreateCtrl(); + ctrl.PollExitWaitTimeout = TimeSpan.FromMilliseconds(100); + _factory.ProjectRunAsyncNeverCompletes = true; + + using var started = WatchProjectStarted(ctrl); + _ = Task.Run(() => ctrl.StartPollAsync( + dir: "test_dir", + root: new XElement("Project"), + hook: (_, _, _) => Task.CompletedTask)); + + await started.WaitAsync(); + await ctrl.StopAsync().WaitAsync(TimeSpan.FromSeconds(10)); + + // 旧循环仍在跑:不能放新的启动进来 + var ex = await Assert.ThrowsAsync(() => + ctrl.StartPollAsync("dir2", new XElement("Project"), (_, _, _) => Task.CompletedTask)); + Assert.Contains("已经启动", ex.Message); + + sp.Dispose(); + } + /// /// 用于验证"DI 作用域释放失败"的工厂:作用域照常提供项目工厂,但 Dispose 抛异常。 /// diff --git a/tests/StdUnit.Tags.Tests/ModbusTags/Channels/ModbusTcpChannelConnectionTests.cs b/tests/StdUnit.Tags.Tests/ModbusTags/Channels/ModbusTcpChannelConnectionTests.cs index 7351371d..7c6765af 100644 --- a/tests/StdUnit.Tags.Tests/ModbusTags/Channels/ModbusTcpChannelConnectionTests.cs +++ b/tests/StdUnit.Tags.Tests/ModbusTags/Channels/ModbusTcpChannelConnectionTests.cs @@ -1,5 +1,11 @@ using StdUnit.Tags.ModbusTcp; +using StdUnit.Tags.Tests.Fakes; +using Microsoft.Extensions.Logging; using Microsoft.Extensions.Logging.Abstractions; +using Moq; +using NModbus; +using System; +using System.Net.Sockets; using System.Threading; using System.Threading.Tasks; using Xunit; @@ -82,4 +88,81 @@ public async Task Dispose_ThenEnsureConnected_Reconnects() Assert.Equal(new ushort[] { 0x9ABC }, regs); channel.Dispose(); } + + /// + /// Dispose() 与 DisconnectAsync() 是同一条释放路径:不拿 Connected 当守卫、 + /// 释放后把 master 一并清空,且重复释放幂等。 + /// + [Fact] + public async Task Dispose_ReleasesConnectionAndIsIdempotent() + { + using var server = new FakeModbusTcpServer(); + using var channel = NewChannel(server); + await channel.EnsureConnectedAsync(false, CancellationToken.None); + Assert.NotNull(channel.ModbusMaster); + + channel.Dispose(); + + Assert.Null(channel.ModbusMaster); + channel.Dispose(); + channel.Dispose(); + } + + /// + /// 底层 抛异常时,显式的 DisconnectAsync 必须以故障 Task 报告 + /// (调用方要看得到"这次断开失败了"),并且连接引用照样被清掉。 + /// + [Fact] + public async Task DisconnectAsync_WhenCloseThrows_ReturnsFaultedTask() + { + var channel = NewThrowingChannel(NullLogger.Instance); + channel.TcpClient = new ThrowingTcpClient(); + + var ex = await Assert.ThrowsAsync( + () => channel.DisconnectAsync(CancellationToken.None)); + + Assert.Equal("close failed", ex.Message); + Assert.Null(channel.TcpClient); + } + + /// + /// 同一次失败落在 Dispose() 上时只留痕不外抛(.NET 的释放惯例)。 + /// + [Fact] + public void Dispose_WhenCloseThrows_ShouldNotThrowButLog() + { + var logs = new CapturingLoggerProvider(); + using var factory = LoggerFactory.Create(b => b.AddProvider(logs)); + var channel = NewThrowingChannel(factory.CreateLogger()); + channel.TcpClient = new ThrowingTcpClient(); + + channel.Dispose(); + + Assert.Null(channel.TcpClient); + Assert.Contains(logs.Entries, e => e.Level == LogLevel.Warning && e.Message.Contains("释放异常")); + } + + private static TestModbusTcpChannel NewThrowingChannel(ILogger logger) => + new( + new ModbusTcpTagChannelDescriptor { Name = "mb-boom", IpAddr = "127.0.0.1", Port = 1 }, + new Mock(), + logger); +} + +/// +/// 关闭即抛的 :真实 socket 的 Close() 几乎不会失败, +/// 只能用替身构造"关闭失败"这条路径(Dispose(bool) 是 protected virtual)。 +/// +internal sealed class ThrowingTcpClient : TcpClient +{ + protected override void Dispose(bool disposing) + { + if (disposing) + { + throw new InvalidOperationException("close failed"); + } + + // finalizer 走这里:绝不能在终结器线程上抛,否则整个进程都会挂掉。 + base.Dispose(false); + } } diff --git a/tests/StdUnit.Tags.Tests/ModbusTags/TestModbusTcpChannel.cs b/tests/StdUnit.Tags.Tests/ModbusTags/TestModbusTcpChannel.cs index 0ead8677..3fe61b7d 100644 --- a/tests/StdUnit.Tags.Tests/ModbusTags/TestModbusTcpChannel.cs +++ b/tests/StdUnit.Tags.Tests/ModbusTags/TestModbusTcpChannel.cs @@ -1,6 +1,8 @@ +using System.Net.Sockets; using System.Threading; using System.Threading.Tasks; using StdUnit.Tags.ModbusTcp; +using Microsoft.Extensions.Logging; using Microsoft.Extensions.Logging.Abstractions; using Moq; using NModbus; @@ -19,11 +21,26 @@ internal class TestModbusTcpChannel : ModbusTcpChannel public Mock MasterMock { get; } public TestModbusTcpChannel(ModbusTcpTagChannelDescriptor descriptor, Mock masterMock) - : base(descriptor, NullLogger.Instance) + : this(descriptor, masterMock, NullLogger.Instance) + { + } + + public TestModbusTcpChannel(ModbusTcpTagChannelDescriptor descriptor, Mock masterMock, ILogger logger) + : base(descriptor, logger) { MasterMock = masterMock; } + /// + /// 越过 直接塞一个底层 TCP 客户端, + /// 用来构造"关闭连接时抛异常"这种真实 socket 上不好复现的现场。 + /// + public TcpClient? TcpClient + { + get => _tcpClient; + set => _tcpClient = value; + } + protected override Task CreateConnectionAsync(int timeout, CancellationToken ct) => Task.FromResult(MasterMock.Object); } diff --git a/tests/StdUnit.Tags.Tests/OpcUaClientTags/OpcUaClientTagChannelTests.cs b/tests/StdUnit.Tags.Tests/OpcUaClientTags/OpcUaClientTagChannelTests.cs index 2ae8297b..442b9a8d 100644 --- a/tests/StdUnit.Tags.Tests/OpcUaClientTags/OpcUaClientTagChannelTests.cs +++ b/tests/StdUnit.Tags.Tests/OpcUaClientTags/OpcUaClientTagChannelTests.cs @@ -57,6 +57,15 @@ protected override Task CreateSessionAsync() /// 暴露受保护的 PrepareOpcUaAppConfig(),用于校验证书等选项真的被写进了底层配置。 ///
public ApplicationConfiguration ExposeAppConfig() => this.PrepareOpcUaAppConfig(); + + /// + /// 暴露受保护的 ,用于构造"已连接/未连接"的现场。 + /// + public ISession? Session + { + get => this.OpcSession; + set => this.OpcSession = value; + } } public class OpcUaClientTagChannelTests @@ -114,6 +123,21 @@ public async Task DisconnectAsync_ClosesSession() sessionMock.Verify(x => x.CloseAsync(It.IsAny()), Times.Once); } + /// + /// 从未连接过的通道( 为 null)也要能安全断开: + /// 清理路径可能对同一通道调用两次,第二次不能再触到 null。 + /// + [Fact] + public async Task DisconnectAsync_WhenNeverConnected_ShouldBeNoOp() + { + var sessionMock = CreateSessionMock(); + var channel = CreateChannel(sessionMock); + + await channel.DisconnectAsync(CancellationToken.None); + + sessionMock.Verify(x => x.CloseAsync(It.IsAny()), Times.Never); + } + #endregion #region ReadAsync @@ -310,6 +334,60 @@ public async Task Dispose_ClosesSession() sessionMock.Verify(x => x.Close(), Times.Once); } + /// + /// 从未连接过:没有会话可关, 不能因此抛。 + /// + [Fact] + public void Dispose_WhenNeverConnected_ShouldBeNoOp() + { + var sessionMock = CreateSessionMock(); + var channel = CreateChannel(sessionMock); + + channel.Dispose(); + + sessionMock.Verify(x => x.Close(), Times.Never); + sessionMock.Verify(x => x.Dispose(), Times.Never); + } + + /// + /// Close() 失败只留痕不外抛(释放惯例),但会话自身的 + /// 仍必须执行——否则反复启停会攒下没人认领的订阅/传输句柄。 + /// + [Fact] + public void Dispose_WhenCloseThrows_ShouldLogAndStillReleaseSession() + { + var logs = new CapturingLoggerProvider(); + using var factory = LoggerFactory.Create(b => b.AddProvider(logs)); + var sessionMock = CreateSessionMock(); + sessionMock.Setup(x => x.Close()).Throws(new InvalidOperationException("close failed")); + var channel = new TestOpcUaChannel("ch-close-throw", sessionMock, factory.CreateLogger()); + channel.Session = sessionMock.Object; + + channel.Dispose(); + + sessionMock.Verify(x => x.Dispose(), Times.Once); + Assert.Contains(logs.Entries, e => e.Level == LogLevel.Warning && e.Message.Contains("释放异常")); + } + + /// + /// 会话的 Dispose 自己抛异常时也只留痕:它跑在 finally 里,抛出去会盖掉真正的失败原因。 + /// + [Fact] + public void Dispose_WhenSessionDisposeThrows_ShouldLogWarning() + { + var logs = new CapturingLoggerProvider(); + using var factory = LoggerFactory.Create(b => b.AddProvider(logs)); + var sessionMock = CreateSessionMock(connected: false); + sessionMock.Setup(x => x.Dispose()).Throws(new InvalidOperationException("dispose failed")); + var channel = new TestOpcUaChannel("ch-dispose-throw", sessionMock, factory.CreateLogger()); + channel.Session = sessionMock.Object; + + channel.Dispose(); + + var warning = Assert.Single(logs.Entries, e => e.Level == LogLevel.Warning && e.Message.Contains("释放会话异常")); + Assert.Equal("dispose failed", warning.Exception?.Message); + } + #endregion #region 调用方的 CancellationToken diff --git a/tests/StdUnit.Tags.Tests/S7Tags/S7TagChannelTests.cs b/tests/StdUnit.Tags.Tests/S7Tags/S7TagChannelTests.cs index fa824f9c..a638d9c2 100644 --- a/tests/StdUnit.Tags.Tests/S7Tags/S7TagChannelTests.cs +++ b/tests/StdUnit.Tags.Tests/S7Tags/S7TagChannelTests.cs @@ -1,4 +1,5 @@ using StdUnit.Tags.S7; +using StdUnit.Tags.Tests.Fakes; using Microsoft.Extensions.Logging; using Microsoft.Extensions.Logging.Abstractions; using StdUnit.Sharp7; @@ -125,6 +126,48 @@ public async Task EnsureConnectedAsync_Forced_ClientNull_ShouldConnect() Assert.Equal(0, mock.DisconnectCallCount); } + /// + /// 强制重连时旧连接断开失败:只记日志,不能因此把重连也一起废掉 + /// (旧 Client 已被摘下,接着照常建新连接)。 + /// + [Fact] + public async Task EnsureConnectedAsync_Forced_WhenDisconnectThrows_ShouldLogAndStillReconnect() + { + var logs = new CapturingLoggerProvider(); + using var factory = LoggerFactory.Create(b => b.AddProvider(logs)); + var channel = new S7TagChannel(new S7TagChannelDescriptor { Name = "forced-throw" }, factory.CreateLogger()); + var mock = new MockS7Client { ConnectToResult = 0 }; + mock.DisconnectAction = () => throw new InvalidOperationException("disconnect failed"); + channel.ClientFactory = _ => mock; + channel.Client = mock; + + await channel.EnsureConnectedAsync(force: true, CancellationToken.None); + + Assert.Equal(1, mock.DisconnectCallCount); + Assert.Equal(1, mock.ConnectToCallCount); + Assert.Same(mock, channel.Client); + Assert.Contains(logs.Entries, e => e.Level == LogLevel.Error && e.Message.Contains("强制断开异常")); + } + + /// + /// 没配 时走默认的 : + /// 连不上(本机 102 端口没人监听)也必须以带地址/机架/槽位的错误消息快速失败,而不是静默留下半成品。 + /// + [Fact] + public async Task EnsureConnectedAsync_WithoutFactory_UsesDefaultClient_AndReportsFailure() + { + var channel = new S7TagChannel( + new S7TagChannelDescriptor { Name = "no-factory", IpAddr = "127.0.0.1" }, + NullLogger.Instance); + + var ex = await Assert.ThrowsAsync( + () => channel.EnsureConnectedAsync(force: false, CancellationToken.None)); + + Assert.Contains("no-factory", ex.Message); + Assert.Contains("连接PLC失败", ex.Message); + Assert.Null(channel.Client); + } + [Fact] public async Task EnsureConnectedAsync_ConnectFails_ShouldThrow() { @@ -357,15 +400,18 @@ public void Dispose_WhenClientConnected_ShouldDisconnect() Assert.Null(channel.Client); } + /// + /// 不判 Connected:它是底层 Socket 的快照,半死连接上返回 false,恰好会把最该关的连接留下来。 + /// [Fact] - public void Dispose_WhenClientNotConnected_ShouldNotDisconnect() + public void Dispose_WhenClientNotConnected_ShouldStillDisconnect() { var (channel, mock) = CreateChannel(connected: false); channel.Client = mock; channel.Dispose(); - Assert.Equal(0, mock.DisconnectCallCount); + Assert.Equal(1, mock.DisconnectCallCount); Assert.Null(channel.Client); }