How microsoft/service-fabric-services-and-actors-dotnet works
Project Type and Purpose
• The project is a set of framework libraries – not a front–end application – that provide developers with the APIs to build fault–tolerant, scalable applications on Azure Service Fabric.
• It covers two primary paradigms: Reliable Actors (based on the Virtual Actor model) and Reliable Services (light–weight service framework) with multiple remoting options (native remoting, WCF, and even legacy support).
File Structure
• The top–level directories include configuration files (build scripts, GitHub workflows, licensing, etc.), a “src” directory that contains the C# projects, and a “test” directory for unit tests.
• Within “src”, the code is further subdivided into several project groups:
– “FabActUtil” which provides utilities for Service Fabric Actors.
– “Microsoft.ServiceFabric.Actors” and “Microsoft.ServiceFabric.Actors.Wcf” for core actor logic and remoting.
– “Microsoft.ServiceFabric.Actors.KVSToRCMigration” contains components to support migration scenarios.
– “Microsoft.ServiceFabric.Services.Remoting”, “Microsoft.ServiceFabric.Services.Wcf”, and “Microsoft.ServiceFabric.Services” that target Reliable Services and their communication layers.
– “netstandard” which shows cross–platform compatibility implementations.
• Additional directories such as “nuprojs”, “properties”, “nuget”, and various build scripts indicate a robust build and packaging process.
Key Components
a. Actors Component:
– Core Actors Framework (Microsoft.ServiceFabric.Actors).
– Actor Client and Remoting layers (including remoting V2 and WCF integration).
– Migration sub–components (for handling ambiguous actor IDs and state migration).
– Utilities (such as FabActUtil) that support actor generation, command line parsing, and configuration updates.
b. Services Component:
– Reliable Services Framework (Microsoft.ServiceFabric.Services).
– Service Remoting (both native and via WCF, including remoting V2).
– Communication sub–systems (clients, retry policies, communication listeners).
c. Cross–cutting Concerns:
– Diagnostics and Telemetry (various “Diagnostics” folders across the projects).
– Build & Packaging (build.ps1, CI workflows, and NuGet packaging).
– Testing, which is expressed in the “test” directory.
Relationships and Interactions
• Separation of Reliable Services and how they similarly expose communication interfaces (remoting, WCF) and integrate with Service Fabric’s state management.
• Migration components that handle state or actor ID ambiguities, interacting closely with both Actors and underlying state providers.
• Sharing of underlying infrastructure such as runtime (state providers, communication listeners), diagnostic modules, and serialization/serialization utilities.
Architectural Patterns and Design Principles
• Layered architecture where low–level communication (remoting, fabric transport) is abstracted away from the service and actor business logic.
• The modular design is reflected in having different projects for different protocols (native remoting vs. WCF vs. migration), highlighting the Single Responsibility Principle and separation of concerns.
• Use of dependency injection and extensibility points (for custom serializers, exception converters, etc.) especially in remoting and migration pipelines.
Detail Level
– It should be detailed enough that someone new to the repository could quickly understand how the various Service Fabric packages interrelate, how clients interact with them, and where custom extension points exist.