netcorepal-cloud-framework v3.3.0 已正式发布。

本次版本继续围绕工程实践中的关键问题进行完善，重点在可观测性、时间字段处理、代码分析可视化体验以及底层稳定性等方面带来增强与修复。

本次更新重点

`v3.3.0` 主要包含以下四项更新：

- 新增 OpenTelemetry Diagnostics 中英文文档

- 为 EF Core + Npgsql 增加 `DateTimeOffset` 写入 UTC 的可选补丁

- 修复代码分析可视化中的两个问题

- 更新部分底层依赖，提升稳定性

1. OpenTelemetry 文档补齐

本次版本补充了 `NetCorePal.OpenTelemetry.Diagnostics` 的中英文文档，并已纳入官方文档导航。

文档内容包括：

- 安装与配置

- 自动追踪的活动类型

- 与 Jaeger、Zipkin、Azure Application Insights 的集成方式

- 采样与导出建议

框架支持对命令、领域事件、集成事件以及事务处理过程进行自动追踪，可为事件驱动和 DDD 项目的运行观测与问题排查提供支持。

2. Npgsql 下 `DateTimeOffset` 处理能力增强

针对 PostgreSQL 场景，新版本增加了一个可选补丁，用于在写入前将 `DateTimeOffset` 统一转换为 UTC。

启用方式如下：

builder.Services.AddDbContext(options =>{ options.UseNpgsql(connectionString); options.UseDateTimeOffsetUtcConversionForNpgsql;});

该能力适用于存在跨时区、国际化、多租户等需求的项目，可在一定程度上降低时间字段在数据库读写过程中的一致性风险。

3. 代码分析可视化体验优化

本次版本修复了两个与代码分析可视化相关的问题：

一是修复聚合关系图中多个 Endpoint 被错误合并为同一节点的问题，避免图表结果失真。

二是修复 `GenerateVisualizationHtml` 在未传入 `snapshots` 时页面脚本报错的问题，当前即使直接使用分析结果，也可以正常生成可视化页面。

上述修复进一步提升了代码分析工具在实际使用场景中的可用性与稳定性。

4. 依赖更新

本次还升级了以下依赖：

-`AsyncKeyedLock`

-`Backport.System.Threading.Lock`

相关更新有助于进一步提升框架底层依赖的稳定性与兼容性。

升级建议

对于正在使用 `netcorepal-cloud-framework` 的项目，建议重点关注以下场景：

- 已接入或准备接入 OpenTelemetry 的项目，可结合新文档完善链路追踪配置

- 使用 PostgreSQL / Npgsql，且实体中包含 `DateTimeOffset` 字段的项目，建议评估是否启用 UTC 转换补丁

- 正在使用代码分析与可视化能力的项目，建议升级后重新验证图表展示与页面生成效果

- 对稳定性和依赖健康度有要求的项目，建议同步跟进本次版本更新

整体来看，`v3.3.0` 是一次以增强与修复为主的版本更新，适合生产项目持续评估与跟进。

- Release 页面：`https://github.com/netcorepal/netcorepal-cloud-framework/releases/tag/v3.3.0`

- Full Changelog：`https://github.com/netcorepal/netcorepal-cloud-framework/compare/v3.2.1...v3.3.0`

- 项目地址：`https://github.com/netcorepal/netcorepal-cloud-framework`

致谢

感谢所有为 `v3.3.0` 提交代码、文档与改进建议的贡献者。

本次版本的相关工作得到了`@zhouda1fu`、`@MarkCiliaVincenti` 等贡献者的支持。正是社区持续、稳定的共建投入，推动了 `netcorepal-cloud-framework` 在工程实践中的不断完善。