后端微服务【免费下载链接】orleansCloud Native application framework for .NET项目地址https://gitcode.com/gh_mirrors/or/orleans点击查看免费下载导读Microsoft.Orleans.Core.Abstractions是 Orleans 框架的基石库封装了实现 Grain 与编写客户端代码所需的全部公共编程 API包括 Grain 接口、Grain 引用接口以及各类声明式特性Attribute。本文将围绕该库在仓库中的官方 README 展开结合src/Orleans.Core.Abstractions下的真实源码系统讲解包定位、安装方式、Grain 接口定义、Grain 引用机制、基类实现与特性体系帮助你从接口到运行时建立起对 Orleans 编程模型的完整认知并能直接参照写出可运行的第一对 Grain 接口与实现。一、包定位Orleans 编程模型的“公共契约层”官方 README 开门见山地给出了该库的定位Microsoft Orleans Core Abstractions is the foundational library for Orleans containing the public programming APIs for implementing grains and client code. This package defines the core abstractions that form the Orleans programming model, including grain interfaces, grain reference interfaces, and attributes.也就是说这个程序集承载的是 Orleans 编程模型的定义本身而不负责运行时实现。从源码结构看Orleans.Core.Abstractions.csproj 的包 ID 为Microsoft.Orleans.Core.Abstractions根命名空间为Orleans并且只依赖Microsoft.Extensions.Configuration.Abstractions、Microsoft.Extensions.Logging与Orleans.Serialization三个基础库未引用任何运行时实现程序集——这正是它作为“抽象层”的体现。从目录布局可以清晰地看到它覆盖的抽象面Core/Grain 基类、Grain 接口、Grain 工厂、Grain 调用上下文与过滤器Runtime/GrainReference、IAddressable、RequestContext等运行时抽象IDs/GrainId、SiloAddress、ActivationId等身份标识类型Placement/放置策略与对应特性Concurrency/ReentrantAttribute、ReadOnlyAttribute等并发特性Lifecycle/Grain 生命周期抽象Exceptions/OrleansException等运行时异常体系。在 Orleans 的三层包结构中Microsoft.Orleans.Core.Abstractions位于最底层客户端包 src/Orleans.Client 与服务端包 src/Orleans.Server 都构建于它之上。因此无论你引用的是Microsoft.Orleans.Sdk、Microsoft.Orleans.Client还是Microsoft.Orleans.Server这套公共抽象都会被自动带入。二、快速开始安装与项目引用README 给出了最直接的安装命令dotnet add package Microsoft.Orleans.Core.Abstractions执行该命令会在当前项目添加对Microsoft.Orleans.Core.Abstractions的包引用。需要注意它的两条使用前提README 原文要点该包是客户端与服务端应用的共同依赖当你引用Orleans SDK或Orleans 客户端/服务端元包metapackage时本包会被自动包含通常无需显式添加。在实践中更常见的做法是直接引用元包。例如仓库示例项目 samples/HelloWorld/HelloWorld.csproj 通过 SDK 或客户端包引入全部 Orleans 依赖随后在代码中直接using Orleans;即可使用本库暴露的类型。由于该包以“抽象 特性”为核心包内还内置了buildMultiTargeting与buildTransitive的 MSBuild targets见 src/Orleans.Core.Abstractions/buildTransitive/Microsoft.Orleans.Core.Abstractions.targets保证通过包引用传递到应用项目时其编译期代码生成OrleansBuildTimeCodeGen见 csproj与特性处理逻辑能够正确生效。三、示例精讲定义一个 Grain 接口README 给出的示例是 Orleans 教程中最经典的 Hello World 接口using Orleans; namespace MyGrainInterfaces; public interface IHelloGrain : IGrainWithStringKey { Taskstring SayHello(string greeting); }这段代码虽短却包含了 Orleans 编程模型的三个核心规范逐一拆解如下。3.1 接口必须继承“键型标记接口”IGrainWithStringKey是 Orleans 预定义的“带键类型约束”的标记接口。查看 src/Orleans.Core.Abstractions/Core/IGrain.cs 可以看到完整的键型体系标记接口主键类型说明IGrain—无键约束的基础标记接口IGrainWithGuidKeyGuidGUID 主键IGrainWithIntegerKeylong长整型主键IGrainWithStringKeystring字符串主键IGrainWithGuidCompoundKeyGuidstring扩展键复合键IGrainWithIntegerCompoundKeylongstring扩展键复合键这套体系直接决定了IGrainFactory.GetGrainTGrainInterface(...)允许传入的主键参数类型见 src/Orleans.Core.Abstractions/Core/IGrainFactory.cs——例如GetGrainIHelloGrain(world)只能作用于IGrainWithStringKey的接口类型系统在编译期就约束了主键形态这正是“Grain 即分布式寻址单元”的具体体现。3.2 方法签名必须是“Task 风格”接口方法的返回类型必须是Task、TaskT、ValueTask、ValueTaskT或IAsyncEnumerableT等异步类型Taskstring即属此类。原因是 Orleans 的每次接口调用都会被运行时包装为一次跨进程或跨 silo 内调度的异步消息往返同步方法无法适配这一模型。此外方法参数与返回值中的自定义类型必须可被 Orleans 序列化器处理——Orleans.Serialization正是本包的直接依赖之一。3.3 从接口到实现的落地只定义接口还不够仓库的 samples/HelloWorld 给出了完整的实现链路// samples/HelloWorld/HelloGrain.cs public sealed class HelloGrain : Grain, IHelloGrain { public override Taskstring SayHello(string greeting) { return Task.FromResult($Hello, {greeting}!); } }实现类继承本库提供的Grain基类或实现IGrainBase然后由 Orleans 运行时负责实例化、激活与调度。值得注意的是永远不要用new直接创建 Grain 实例来调用其方法——Grain 必须通过IGrainFactory获取引用后调用。GrainExtensions.AsReference的内部注释对此有明确警告见 src/Orleans.Core.Abstractions/Core/GrainExtensions.cs 中的WRONG_GRAIN_ERROR_MSG直接实例化 Grain 类再调用会被视为“半成品 Grain”half baked grain并抛出ArgumentException。四、Grain 引用机制从接口到远程调用的桥梁Grain 接口本身只是一份契约真正可被调用的是一等公民GrainReference。整个引用链路如下。4.1IAddressable一切可寻址端点src/Orleans.Core.Abstractions/Runtime/IAddressable.cs 定义了IAddressable[GenerateMethodSerializers(typeof(GrainReference))] public interface IAddressable { }它是 Grain、Observer 以及系统内部可寻址端点的统一标记接口并标注了GenerateMethodSerializers指示代码生成器为每个 Grain 接口生成消息序列化器——这是 Orleans 编译期代码生成Orleans.CodeGenerator接入点之一。IGrain正是继承自它。4.2GrainReference轻量级代理src/Orleans.Core.Abstractions/Runtime/GrainReference.cs 定义了GrainReference。Grain 引用是一种逻辑地址它只携带GrainId与接口类型信息不绑定具体物理位置具体 silo 与激活由运行时目录服务解析。因此引用可以被自由序列化、跨进程传递引用在故障后依然有效运行时会自动重定位到新激活。4.3IGrainFactory引用的唯一合法来源src/Orleans.Core.Abstractions/Core/IGrainFactory.cs 定义了获取引用的核心接口其典型用法// 通过客户端 ClusterClient 或 Grain 内部的 GrainFactory 获取引用 IHelloGrain hello grainFactory.GetGrainIHelloGrain(world); string reply await hello.SayHello(Orleans);接口提供了针对每种主键形态的重载Guid、long、string三种单键以及Guid keyExtension、long keyExtension两种复合键还包含基于GrainId的泛型/非泛型重载以及针对IGrainObserver的CreateObjectReference/DeleteObjectReference用于把客户端对象暴露给 Grain 回调Observer 模式。4.4GrainExtensions引用与标识的辅助方法src/Orleans.Core.Abstractions/Core/GrainExtensions.cs 提供了一组高频工具方法源码实现清楚地展示了它们的转换逻辑// 获取 Grain 的唯一标识 GrainId id grain.GetGrainId(); // 按主键类型提取 long intKey grain.GetPrimaryKeyLong(); // long 主键 Guid guidKey grain.GetPrimaryKey(); // Guid 主键 string strKey grain.GetPrimaryKeyString(); // string 主键 // 获取可调用的强类型引用 var typed grain.AsReferenceIHelloGrain(); // 等价于 CastIHelloGrain()其内部实现值得留意GetGrainId通过switch同时处理Grain实例、GrainReference、IGrainBase与ISystemTargetBase四种来源GetPrimaryKey在遇到整数主键时还会按字节展开构造出等效Guid体现了新旧键体系的兼容处理。五、实现 GrainGrain基类与IGrainBase5.1 两条实现路径本库为 Grain 实现者提供了两种基座见 src/Orleans.Core.Abstractions/Core/Grain.cs 与 src/Orleans.Core.Abstractions/Core/IGrainBase.cs继承Grain抽象基类提供最丰富的内置能力如GrainFactory、ServiceProvider、DeactivateOnIdle()、DelayDeactivation()、MigrateOnIdle()等实现IGrainBase接口只要求提供GrainContext并约定OnActivateAsync/OnDeactivateAsync两个虚方法带默认实现适合需要自定义基类或轻量实现的场景。Grain基类为子类暴露了这些关键成员成员说明GrainContext当前激活的IGrainContext运行时注入GrainReference指向本 Grain 的引用GrainFactory用于调用其他 Grain 的工厂ServiceProvider运行时托管的IServiceProviderRegisterGrainTimer(...)注册 Grain 定时器已被RegisterGrainTimer扩展方法取代原方法标记为 ObsoleteDeactivateOnIdle()当前调用结束后停用本激活DelayDeactivation(TimeSpan)延迟/取消延迟激活回收MigrateOnIdle()空闲时发起迁移OnActivateAsync/OnDeactivateAsync激活/停用生命周期钩子5.2 带状态的GrainTGrainStateGrain.cs中还定义了GrainTGrainState泛型基类为“声明式持久状态”提供基座public class GrainTGrainState : Grain { protected TGrainState State { get; set; } // 当前状态 protected virtual Task ReadStateAsync(); // 从存储读取 protected virtual Task WriteStateAsync(); // 写回存储 protected virtual Task ClearStateAsync(); // 清空存储 }从源码看它的状态装载是由一个内部LifecycleObserver在GrainLifecycleStage.SetupState阶段完成的激活启动时若状态尚未初始化且没有因迁移脱水/补水而携带 Etag就调用ReadStateAsync从存储加载同时它实现了IGrainMigrationParticipant支持 Grain 迁移时状态随上下文脱水/补水传递。5.3 激活与停用DeactivationReasonCodeOnDeactivateAsync的签名接收一个DeactivationReason其DeactivationReasonCode枚举见 IGrainBase.cs详细枚举了停用原因ShuttingDown进程关闭、ActivationIdle空闲回收、DuplicateActivation重复激活、ApplicationRequested应用主动请求、Migrating迁移中、HighMemoryPressure内存压力等。这些原因码可以用于在停用钩子里区分“正常回收”与“故障清理”从而决定是否持久化中间状态。六、声明式特性体系控制放置、并发与不可迁移性本库通过一系列Attribute把策略声明直接写在 Grain 类上运行时再解析生效。这套体系与Orleans.Metadata的IGrainPropertiesProviderAttribute机制对接——特性实现该接口后其Populate方法会把策略信息写入 Grain 类型属性字典供运行时如 Orleans.Runtime 的目录与调度组件读取。6.1 放置策略Placementsrc/Orleans.Core.Abstractions/Placement/PlacementAttribute.cs 定义了完整的放置策略特性特性策略说明[RandomPlacement]RandomPlacement随机放置默认策略[HashBasedPlacement]HashBasedPlacement基于主键哈希的确定性放置[PreferLocalPlacement]PreferLocalPlacement优先本地放置[ActivationCountBasedPlacement]ActivationCountBasedPlacement按各 silo 近期的激活数量均衡放置[SiloRoleBasedPlacement]SiloRoleBasedPlacement按 silo 角色放置[ResourceOptimizedPlacement]ResourceOptimizedPlacement基于资源使用优化的放置[Immovable]—禁止自动迁移可指定ImmovableKind.Repartitioner/Rebalancer/Any例如[ActivationCountBasedPlacement] [Reentrant] public class ChatRoomGrain : Grain, IChatRoomGrain { ... }ImmovableAttribute尤其值得注意它通过ImmovableKind位标志区分“重分区器Repartitioner”与“重平衡器Rebalancer”两类自动迁移来源与仓库中的 ActivationRebalancing 等 playgroud 实验场景直接相关。6.2 并发与优化特性src/Orleans.Core.Abstractions/Concurrency/GrainAttributeConcurrency.cs 定义了并发控制特性[Reentrant]允许请求在同一个激活内交错执行高级特性需充分理解副作用才能使用[ReadOnly]标记不改写 Grain 状态的方法允许运行时做优化源码通过InvokeMethodOptions.ReadOnly把该选项注入请求调用选项[AlwaysInterleave]/[MayInterleave]控制消息交错[OneWay]单向调用[StatelessWorker(maxLocalWorkers, removeIdleWorkers)]无状态 Worker 放置允许同一 Grain 在本地有多个并发激活[Unordered]已标记为 Obsolete源码注释明确指出“无论是否使用该特性消息顺序都不再保证该特性无实际效果”。七、身份标识体系GrainId与键的底层形态Grain 之所以能在分布式环境中唯一寻址靠的是Orleans.Runtime.GrainId这一核心值类型见 src/Orleans.Core.Abstractions/IDs/GrainId.cs。GrainId由两大部分组成Grain 类型标识Grain Type指明该 Grain 属于哪个实现类型Grain 键Key用户在创建引用时提供的主键Guid/long/string或复合键 扩展键键空间内部以IdSpan存储。IGrainFactory.GetGrainT(...).AsReferenceT()返回的GrainReference就携带了这个GrainId。GrainExtensions.GetGrainId能从任何IAddressableGrain 实例、引用、Observer、系统目标中提取它。与键相关的辅助工具还包括StableHash稳定哈希与GrainIdKeyExtensions它们为基于键的放置、流订阅映射等场景提供底层支持。从源码结构看IDs/目录还包含了SiloAddresssilo 网络地址、ActivationId激活实例标识、ObserverGrainId客户端 Observer 标识等完整寻址原语它们共同构成了 Orleans 的“逻辑地址空间”。八、异常体系面向分布式环境的异常契约src/Orleans.Core.Abstractions/Exceptions 定义了应用会直接接触到的异常类型OrleansException所有 Orleans 异常的基类SiloUnavailableException目标 silo 不可用GatewayTooBusyException网关过载ClientNotAvailableException客户端不可达GrainExtensionNotInstalledExceptionGrain 扩展未安装OrleansConfigurationException配置错误LimitExceededException超出限制WrappedException跨 silo 边界传递的异常包装。这些类型与OrleansMessageRejectionException、OrleansLifecycleCanceledException等共同构成一套“跨进程可理解”的异常语义帮助你在捕获异常时区分网络性故障与逻辑性错误。九、仓库源码导读按图索骥本库源码位于 src/Orleans.Core.Abstractions建议按以下顺序阅读关注点文件包定义与依赖Orleans.Core.Abstractions.csprojGrain 接口与键型体系Core/IGrain.csGrain 基类与持久状态Core/Grain.cs引用辅助方法Core/GrainExtensions.cs工厂接口与扩展Core/IGrainFactory.cs可寻址端点Runtime/IAddressable.csGrain 引用Runtime/GrainReference.cs放置特性Placement/PlacementAttribute.cs并发特性Concurrency/GrainAttributeConcurrency.cs身份标识IDs/GrainId.cs配套的端到端示例可参考 samples/HelloWorld含 IHelloGrain.cs、HelloGrain.cs 与 Program.cs以及 samples/BasicClustering展示 client silo 集群的最小配置。仓库根目录的 Orleans.slnx 与 README.md 提供了整体构建与运行指引。十、小结Microsoft.Orleans.Core.Abstractions虽只是一个抽象层程序集但它定义了 Orleans 的全部“公共词汇”从IGrain键型接口、IGrainFactory引用工厂、GrainReference寻址代理到Grain/GrainTGrainState实现基座再到放置与并发特性体系。理解这一层你就掌握了 Orleans 编程模型的语法骨架配合 Orleans.Core 与 Orleans.Runtime 的运行时实现即可完整还原一条消息从客户端经由网关、目录服务最终抵达 Grain 激活的分布式调用链路。对于想要深入 Orleans 源码的开发者而言从本库开始阅读是最佳的切入点。赞分享后端微服务【免费下载链接】orleansCloud Native application framework for .NET项目地址https://gitcode.com/gh_mirrors/or/orleans点击查看免费下载相关推荐深度解析Graphcool数据库抽象层与数据建模核心技术深度解析Graphcool数据库抽象层与数据建模核心技术 引言传统数据库开发的痛点与Graphcool的解决方案 你是否还在为繁琐的数据库配置、复杂的ORMPTO Tile Intrinsics 编程模型深度解析从 Tile 抽象到 SPMD/MPMD 执行模型PTO Tile Intrinsics 编程模型深度解析从 Tile 抽象到 SPMD/MPMD 执行模型 PTOParallel Tile Operati算子库人工智能CANNCANN/asc-devkit向量相等比较APIasc_eq 产品支持情况 | 产品 | 是否支持 | | : | : :| | term Ascend 950PR/Ascend 950DT/term |人工智能深度学习算子库CANNAscend上一篇FIFA 23生涯模式修改器终极指南免费开源工具打造完美足球经理体验下一篇CodeIgniter String Helper 完全指南8 个内置字符串函数与源码级解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考