Orleans ADO.NET 提供程序配置指南：为集群、持久化、提醒与流式传输接入关系型数据库

后端微服务【免费下载链接】orleansCloud Native application framework for .NET项目地址https://gitcode.com/gh_mirrors/or/orleans点击查看免费下载本文是 Orleans 官方配置文档configuring-ado-dot-net-providers.md的深度实践版系统讲解如何用 ADO.NET 提供程序让 Orleans 的集群成员管理Clustering、Grain 持久化Grain Storage、提醒Reminders、Grain 目录Grain Directory与流式传输Streaming共用一套关系型数据库。读完本文你将掌握各能力对应的 NuGet 包与配置位置、数据库脚本的安装顺序与定制原则、SQL Server / PostgreSQL / MySQL / MariaDB / Oracle 的完整配置方法、基于DbDataSource的高级连接源注入方式以及声明式配置与生产运维要点。ADO.NET 提供程序与运行时能力总览Orleans 的 ADO.NET 提供程序使用一个关系型数据库承载一种或多种运行时能力。每种能力对应独立的 NuGet 包并可在不同端Silo 或外部客户端上配置能力包配置位置集群ClusteringMicrosoft.Orleans.Clustering.AdoNetSilo 与外部客户端Grain 存储Grain storageMicrosoft.Orleans.Persistence.AdoNetSilo提醒RemindersMicrosoft.Orleans.Reminders.AdoNetSiloGrain 目录Grain directoryMicrosoft.Orleans.GrainDirectory.AdoNetSilo流式传输StreamingMicrosoft.Orleans.Streaming.AdoNetSilo 与外部客户端安装原则只安装应用实际用到的能力包同时引用对应的数据库驱动包driver package。例如只做集群 持久化就只安装 Clustering 与 Persistence 两个包并额外引用Microsoft.Data.SqlClient等驱动。从源码看这些包之间的依赖是解耦的集群能力通过 AdoNetHostingExtensions.cs 向 DI 容器注册IMembershipTableSilo 侧或IGatewayListProvider客户端侧实现Grain 存储通过 AdoNetGrainStorageSiloBuilderExtensions.cs 提供AddAdoNetGrainStorage/AddAdoNetGrainStorageAsDefault提醒服务通过 SiloBuilderReminderExtensions.cs 提供UseAdoNetReminderService。各能力按需注册互不强制。准备数据库先运行主脚本再运行能力脚本每个提供程序目录旁都存放着对应的 SQL 脚本。正确的安装顺序是先运行主脚本Main建立基础表与查询注册表再运行该能力自己的脚本。以 SQL Server 上同时启用集群与持久化为例依次执行src/AdoNet/Shared/SQLServer-Main.sqlsrc/AdoNet/Orleans.Clustering.AdoNet/SQLServer-Clustering.sqlsrc/AdoNet/Orleans.Persistence.AdoNet/SQLServer-Persistence.sql其他数据库与能力的脚本对应关系如下完整清单见 adonet-configuration.md脚本类型SQL ServerPostgreSQLMySQL/MariaDBOracleSQLite主脚本SQLServer-Main.sqlPostgreSQL-Main.sqlMySQL-Main.sqlOracle-Main.sqlSqlite-Main.sql集群SQLServer-Clustering.sqlPostgreSQL-Clustering.sqlMySQL-Clustering.sqlOracle-Clustering.sql—持久化SQLServer-Persistence.sqlPostgreSQL-Persistence.sqlMySQL-Persistence.sqlOracle-Persistence.sqlSqlite-Persistence.sql提醒SQLServer-Reminders.sqlPostgreSQL-Reminders.sqlMySQL-Reminders.sqlOracle-Reminders.sql—Grain 目录SQLServer-GrainDirectory.sqlPostgreSQL-GrainDirectory.sqlMySQL-GrainDirectory.sql——流式传输SQLServer-Streaming.sqlPostgreSQL-Streaming.sqlMySQL-Streaming.sql——并非每种能力都支持每种数据库provider 目录中是否存在对应脚本是判断该 Orleans 版本是否支持某数据库的权威依据。例如 Grain 目录与流式传输目前没有 Oracle 脚本SQLite 仅覆盖本地持久化场景Sqlite-Main.sql与Sqlite-Persistence.sql。配置前务必核实所选能力在目标数据库上有对应脚本。[!IMPORTANT] 应使用与应用部署的 Orleans 包同一版本发布的脚本。OrleansQuery脚本与查询的契约机制主脚本不只是建表。以 SQLServer-Main.sql 为例它会创建一个OrleansQuery表QueryKeyQueryText两列用于注册 Orleans 运行时会用到的全部 SQL 语句各能力脚本随后通过INSERT INTO OrleansQuery写入自己的查询定义。主脚本头部注释明确了这一契约Orleans按列名和类型读取结果按参数名和类型写入因此脚本必须保留输入/输出的名称与类型允许针对具体厂商做部署级调优只要不破坏接口契约各厂商脚本应尽量保留一致的约束名便于排查问题ETag 是不透明的版本列实现类型不限SQL Server 脚本用整数实现返回 TRUE/FALSE 的查询按“0 为真、0 为假”解释异常会触发 Orleans 重试。例如 SQLServer-Clustering.sql 创建OrleansMembershipVersionTable以DeploymentId为主键、维护Version与OrleansMembershipTable记录每个 Silo 的地址、端口、代数、状态、心跳时间等并把UpdateIAmAlivetimeKey、InsertMembershipVersionKey等查询写入OrleansQuery。运行期 provider 只通过OrleansQuery中的语句访问数据库。生产库布局与 Schema 定制脚本创建的是未限定名称unqualified的表落在数据库用户的默认 schema 下provider 查询也以未限定名引用这些对象。Orleans 没有提供选择 schema 或 filegroup 的配置项。如果生产库需要专用 schema、filegroup、分区或其他存储布局必须把定制放进数据库部署流程中自行实现并保持以下要素与 Orleans 兼容表名、列名、参数名OrleansQuery中存储的查询及其返回结果形状result shape。脚本只是起点 schema不是放之四海皆准的生产布局。定制后的脚本与查询应在应用启动路径之外完成应用与验证例如先用预发布集群验证不要把“让 Silo 在运行时自行建表”当作常规手段也不要给 Silo 授予 schema-owner 级别的权限。schema 变更应作为受控的部署步骤执行。配置 SQL ServerSQL Server 使用Microsoft.Data.SqlClient驱动与Microsoft.Data.SqlClientinvariant。以下示例来自官方示例片段 HostingExamples.csadonet_silo与adonet_client两段在同一 Silo 上同时启用集群、提醒与 Grain 存储var builder Host.CreateApplicationBuilder(args); var connectionString builder.Configuration.GetConnectionString(orleans) ?? throw new InvalidOperationException( Connection string orleans is required.); builder.UseOrleans(siloBuilder { siloBuilder.UseAdoNetClustering(options { options.Invariant Microsoft.Data.SqlClient; options.ConnectionString connectionString; }); siloBuilder.UseAdoNetReminderService(options { options.Invariant Microsoft.Data.SqlClient; options.ConnectionString connectionString; }); siloBuilder.AddAdoNetGrainStorageAsDefault(options { options.Invariant Microsoft.Data.SqlClient; options.ConnectionString connectionString; }); });外部客户端与 Silo 使用同一个集群数据库builder.UseOrleansClient(clientBuilder { clientBuilder.UseAdoNetClustering(options { options.Invariant Microsoft.Data.SqlClient; options.ConnectionString connectionString; }); });[!IMPORTANT]System.Data.SqlClient不是 SQL Server 的 Orleans invariant。必须引用Microsoft.Data.SqlClient包并使用Microsoft.Data.SqlClientinvariant。从源码看UseAdoNetClustering在 Silo 侧注册 AdoNetClusteringTable 作为IMembershipTable实现在客户端侧注册 AdoNetGatewayListProvider 作为IGatewayListProvider实现见 AdoNetHostingExtensions.cs。也就是说客户端只读网关列表不直接参与成员表写入。Invariant是必填项Orleans 用它选择数据库特有的查询与行为而不是仅靠连接字符串自动推断。各能力 Option 类如 AdoNetClusteringSiloOptions.cs都包含ConnectionString、DataSource与Invariant三个核心属性其中连接字符串与数据源属性带有[Redact]标记日志输出时会自动脱敏。配置其他数据库PostgreSQL、MySQL/MariaDB 与 OraclePostgreSQL、MySQL/MariaDB 与 Oracle 的 Orleans 配置形状与 SQL Server 完全一致只需同时替换三样东西驱动包、invariant、SQL 脚本。官方对应关系如下数据库驱动包Orleans invariantSQL ServerMicrosoft.Data.SqlClientMicrosoft.Data.SqlClientPostgreSQLNpgsqlNpgsqlMySQL/MariaDBMySql.DataMySql.Data.MySqlClientOracleOracle.ManagedDataAccess.CoreOracle.DataAccess.Client此外Orleans 还识别开源 MySQL 驱动MySqlConnectorinvariant 为MySql.Data.MySqlConnector。完整的 invariant 支持列表可以在源码 AdoNetInvariants.cs 中确认共六项Microsoft.Data.SqlClient、Npgsql、MySql.Data.MySqlClient、MySql.Data.MySqlConnector、Oracle.DataAccess.Client、System.Data.SQLite。invariant 并不仅是字符串标记。从 DbConstantsStore.cs 可以看到每个 invariant 都绑定了一组数据库常量标识符转义字符SQL Server 用[]、PostgreSQL 用、MySQL 用、是否原生支持命令取消、是否为同步 ADO.NET 实现MySQL 与 Oracle 标记为同步实现执行时会被包装到线程池任务中以及命令拦截器Oracle 使用专门的OracleCommandInterceptor用于改写 LIMIT 之类的语法差异。这正是“invariant 决定数据库特定查询与行为”的底层机制。配置 PostgreSQL 的示意builder.UseOrleans(siloBuilder { siloBuilder.UseAdoNetClustering(options { options.Invariant Npgsql; options.ConnectionString connectionString; }); });MySQL/MariaDB 只需把Invariant改为MySql.Data.MySqlClient、Oracle 改为Oracle.DataAccess.Client并分别选用对应的脚本。使用 DbDataSource 作为连接源每个 ADO.NET 提供程序的 Option 类型都接受连接字符串或DbDataSource二选一。DbDataSource适合连接字符串无法表达驱动级配置的场景例如需要定期刷新的认证令牌token。配置原则与行为约束恰好配置一个连接源。Orleans 会拒绝同时提供ConnectionString与DataSource、或两者都缺失的配置——这一点同时体现在配置验证器AdoNetGrainStorageOptionsValidator与运行时工厂 RelationalStorage.CreateInstance 中两者都会抛出“必须二选一”的异常即使使用数据源仍然必须设置Invariant因为 Orleans 要据此选择数据库特有的查询与行为将数据源注册为singleton并通过 provider 的OptionsBuilder配置重载解析命名 provider 可以解析不同的keyed 数据源keyed data source生命周期归属数据源由依赖注入容器或应用拥有并负责保持存活Orleans 只打开与释放单个连接不会释放数据源本身。从 RelationalStorage.cs 的OpenConnectionAsync可以看到两种路径的分流配置了DbDataSource时调用_dataSource.OpenConnectionAsync(...)否则通过DbConnectionFactory.CreateConnection(invariant, connectionString)手工创建连接再OpenAsync。声明式配置Declarative Configuration安装 ADO.NET 提供程序包后会自动注册AdoNet这个声明式 provider 类型。这样便可以在配置文件如appsettings.json中直接声明而无需编写代码。例如在一个应用中同时启用 AdoNet 集群、提醒与默认 Grain 存储{ Orleans: { ServiceId: orders, ClusterId: orders-production, Clustering: { ProviderType: AdoNet, Invariant: Microsoft.Data.SqlClient, ConnectionString: ... }, Reminders: { ProviderType: AdoNet, Invariant: Microsoft.Data.SqlClient, ConnectionString: ... }, GrainStorage: { Default: { ProviderType: AdoNet, Invariant: Microsoft.Data.SqlClient, ConnectionString: ... } } } }声明式配置与代码配置最终汇聚到同一套 Option 与 provider 构建器从 AdoNetClusteringProviderBuilder.cs 与 AdoNetGrainStorageProviderBuilder.cs 的源码结构看它们正是声明式配置ProviderType: AdoNet到UseAdoNetClustering/AddAdoNetGrainStorage的桥梁。[!IMPORTANT] 连接字符串属于机密信息应存放在密钥提供程序secret provider或部署环境变量中而不是提交到版本库的配置文件里。生产运维指导保持ClusterOptions.ServiceId稳定Orleans 依据它读取应用所属的行成员表、存储表按DeploymentId隔离。变更 ServiceId 会使其读取不到预期数据。连接池规模按“Silo 进程数 客户端进程数”的总量规划数据库连接池大小避免连接池耗尽。安全基线启用连接加密如 SQL Server 的EncryptTrue使用最小权限的数据库身份能使用托管身份managed identity的场景优先使用托管身份。监控指标持续监控数据库延迟、限流throttling、死锁与连接池耗尽。故障演练在负载下测试数据库故障转移与滚动部署行为。备份策略Grain 状态备份必须遵循应用的恢复目标RPO/RTO成员表membership行是瞬态数据不能替代状态备份。schema 升级从旧版本升级时检查并应用各 providerMigrations目录下的升级脚本当前仓库中可见的如 SQLServer-Clustering-3.7.0.sql、PostgreSQL-Persistence-3.6.0.sql、PostgreSQL-Reminders-3.6.0.sql 等。升级流程建议为按恢复策略备份数据 → 新库先跑主脚本 → 再跑各能力脚本 → 旧 schema 升级时依次审查并执行Migrations下的脚本 → 用同驱动、同数据库引擎版本的预发布集群验证。关于 Azure SQL 的托管身份如果连接的是 Azure SQLMicrosoft 建议使用**托管身份managed identities for Azure resources**作为认证方式——它是当前最安全的认证流程之一详见 managed-identities.md 中的官方说明。配合上文介绍的DbDataSource方案可以在数据源层完成基于托管身份/令牌的认证配置从而避免在连接字符串中存放静态凭据。延伸阅读与源码导航官方配套参考文档ADO.NET database configuration脚本与 invariant 总表官方代码示例片段HostingExamples.csadonet_silo/adonet_client/named_providers共享存储层invariant 常量、连接工厂、查询执行器、数据库常量表src/AdoNet/Shared各能力源码目录集群 src/AdoNet/Orleans.Clustering.AdoNet、持久化 src/AdoNet/Orleans.Persistence.AdoNet、提醒 src/AdoNet/Orleans.Reminders.AdoNet、Grain 目录 src/AdoNet/Orleans.GrainDirectory.AdoNet、流式传输 src/AdoNet/Orleans.Streaming.AdoNet赞分享后端微服务【免费下载链接】orleansCloud Native application framework for .NET项目地址https://gitcode.com/gh_mirrors/or/orleans点击查看免费下载相关推荐Orleans Google Cloud Firestore 提供程序配置指南集群、目录、持久化与提醒服务Orleans Google Cloud Firestore 提供程序配置指南集群、目录、持久化与提醒服务 本指南讲解如何在 Orleans 中使用 Goog后端微服务Orleans 关系数据库ADO.NETGrain 持久化实战指南SQL Server/MySQL/PostgreSQL/Oracle/SQLite 配置与原理Orleans 关系数据库ADO.NETGrain 持久化实战指南SQL Server/MySQL/PostgreSQL/Oracle/SQLite 配置后端微服务Orleans Grain 持久化深度指南IPersistentState、存储提供程序与状态演化Orleans Grain 持久化深度指南IPersistentState、存储提供程序与状态演化 Grain 持久化grain persistence是后端微服务上一篇SDWebImage 手动安装指南从源码构建 Framework、静态库与子工程集成的完整实践下一篇Agent Skills 开源仓库贡献指南从 Mintlify 文档站搭建到 AI 协作披露的完整实践创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考