ADNC is an open-source distributed/microservice framework based on .NET 8, and it also works well for monolithic applications. It provides a practical set of infrastructure and engineering practices around service registration and discovery, configuration management, distributed tracing, load balancing, circuit breaking and fault tolerance, distributed transactions, distributed caching, message queues, RPC communication (HTTP / gRPC), authentication and authorization, read/write splitting, and logging. The repository also includes supporting documentation and sample code to help you understand the framework design and get started quickly.
- Supports multiple service styles: classic layered architecture,
DDD, and compact single-project service structures. - Ready-to-use infrastructure: pre-integrated solutions for configuration, service discovery, caching, messaging, authentication, and logging.
- Good for both learning and real projects: the repository includes a full demo, supporting documentation, and a front-end example.
- Open and extensible: released under the
MITlicense, so it can be customized, extended, and integrated into existing systems as needed.
Whether you are building a new system from scratch or refactoring and evolving an existing one, ADNC can serve as a reusable engineering foundation and reference implementation.
It is recommended to start in this order:
- Read the Quick Start documentation
- Open the solution with
src/Adnc.slnorsrc/Demo/Adnc.Demo.sln - If you need the front-end project, see the links at the end of this document
- If you need seed data, see the database script link at the end of this document
Before running the demo, prepare the .NET 8 SDK and the required infrastructure described in the quick start guide. For complete setup and local run instructions, refer directly to the quick start documentation.
adnc
├── .github
│ └── workflows CI/CD scripts (GitHub Actions)
├── doc Technical documentation
├── src Source code
│ ├── Infrastructures Infrastructure layer projects
│ ├── ServiceShared Shared service layer projects
│ ├── Gateways Ocelot gateway projects
│ └── Demo Demo projects
├── test Test-related projects
├── .gitignore
├── README.md
└── LICENSE
| Path | Description |
|---|---|
src/Adnc.sln |
The solution containing all adnc projects |
src/Infrastructures/Adnc.Infra.sln |
The solution containing only infrastructure-related projects |
src/ServiceShared/Adnc.Shared.sln |
The solution containing only shared service layer projects |
src/Demo/Adnc.Demo.sln |
The solution containing only demo-related projects |
src/.editorconfig |
Cross-editor configuration used to keep code style consistent across Visual Studio, VS Code, and JetBrains Rider |
src/Directory.Build.props |
Centralized common build properties such as target frameworks, language version, and output paths |
src/Directory.Packages.props |
Central Package Management (CPM) file used to manage NuGet package versions across the solution |
NuGet Gallery | Packages matching adnc.infra
NuGet Gallery | Packages matching adnc.shared
| Name | Description |
|---|---|
| Ocelot | Open-source gateway built on .NET |
| Consul | Configuration center and service registry |
| Refit | Declarative and type-safe REST client library |
| Grpc.Net.ClientFactory Grpc.Tools |
gRPC communication framework |
| SkyAPM.Agent.AspNetCore | SkyWalking .NET agent for tracing and performance monitoring |
| Castle DynamicProxy | Dynamic proxy and AOP component |
| Pomelo.EntityFrameworkCore.MySql | EF Core ORM provider |
| Dapper | Lightweight ORM |
| NLog NLog.MongoDB NLog.Loki |
Logging components |
| AutoMapper | Object-object mapping library |
| Swashbuckle.AspNetCore | Swagger-based API documentation generator |
| StackExchange.Redis | Redis client SDK |
| CAP | Event bus and eventual consistency / distributed transaction component |
| RabbitMQ | Asynchronous message queue component |
| Polly | .NET resilience and transient-fault-handling library |
| FluentValidation | .NET validation framework |
| MaxScale | Mature, high-performance, open-source database middleware from MariaDB |
| AspNetCore.HealthChecks | Health check component that can work together with Consul health checks |
The demo includes five related microservices, each showing a different service decomposition and project organization style.
| Service | Description | Architecture Style |
|---|---|---|
| Admin | System management (organization, users, roles, permissions, dictionaries, configuration) | Classic layered architecture with separate contracts |
| Maint | Operations management (logs, audits) | Classic layered architecture with merged contracts |
| Cust | Customer management | Minimal single-project structure |
| Ord | Order management | Domain-driven design (DDD) with a domain layer |
| Whse | Warehouse management | Domain-driven design (DDD) with a domain layer |
These demos show how to organize code for different business sizes and complexity levels while keeping the overall framework consistent.
Shared demo projects reused by all demo services.
Shared/
├── Remote.Event/ - Event contracts for cross-service communication
├── Remote.Grpc/ - gRPC client definitions
├── Remote.Http/ - HTTP client definitions
├── protos/ - gRPC protocol definitions
└── resources/ - Shared configuration and resources
Admin is the system management service. It uses a classic three-layer structure and places application service contracts in a separate
Adnc.Demo.Admin.Application.Contractsproject. This layout is clear and well suited to back-office scenarios with well-defined boundaries and more modules.
Admin/
├── Api/ - Controllers and API endpoints
├── Application/ - Business logic implementations
├── Application.Contracts/ - DTOs and service interfaces
└── Repository/ - Data access layer
Maint is the operations center service. It uses a more compact three-layer structure, with both contracts and implementations living in
Adnc.Demo.Maint.Application. This reduces the number of projects while keeping responsibilities clear.
Maint/
├── Api/ - Controllers and endpoints
├── Application/ - Contracts and implementations
└── Repository/ - Data access layer
Cust is the customer center service. It uses a single-project structure, with controllers, application services, contracts, and repositories all living in one project. This approach is better suited to smaller services with focused responsibilities and clear boundaries.
Cust/
└── Api/ - Controllers, application logic, and repositories
Ord is the order center service. It uses a DDD structure with an independent domain layer to emphasize business rules and domain models while separating them from application-layer concerns.
Ord/
├── Api/ - API endpoints
├── Application/ - Application services
├── Domain/ - Domain entities, aggregates, and domain services
└── Migrations/ - Database migrations
Whse is the warehouse center service. Its structure is the same as Ord and also uses a DDD organization with an independent domain layer.
Whse/
├── Api/ - API endpoints
├── Application/ - Application services
├── Domain/ - Domain entities, aggregates, and domain services
└── Migrations/ - Database migrations
Explains each configuration section and what it does: View documentation
Covers how to use Docker to install and configure a Consul cluster, the SkyWalking stack, how to write Dockerfiles for the related projects, and how to deploy multiple services: View documentation
Explains why middleware is used for read/write splitting and how to write EF Core code under this approach: View documentation
Includes usage patterns for Cache, Redis, distributed locks, and Bloom filters, as well as strategies to avoid cache avalanche, breakdown, penetration, and synchronization issues: View documentation
Introduces the Yitter Snowflake algorithm, its features, configuration, and how to get a workerId dynamically: View documentation
Explains why a hybrid JwtBearer + Basic authentication model is used, along with the corresponding implementation and configuration: View documentation
Covers repository basics, unit of work, Code First, native SQL, and related demo code and SQL examples.
- How to use the repository (1) - Basic features
- How to use the repository (2) - Distributed transactions / local transactions
- How to use the repository (3) - Code First
- How to use the repository (4) - Writing raw SQL
- How to use the repository (5) - Switching database types
- Documentation is being prepared
- Documentation is being prepared
- Documentation is being prepared
- Documentation is being prepared
- Documentation is being prepared
- Documentation is being prepared
- Documentation is being prepared
- Documentation is being prepared
Six test cases cover the gateway, service discovery, configuration center, synchronous service calls, database CRUD, local transactions, distributed transactions, caching, Bloom filters, SkyAPM tracing, NLog logging, and operation logs.
- ECS server configuration: 4 vCPU, 8 GB RAM, 8 Mbps bandwidth. The server was also running many other components, with about 50% CPU and 50% memory still available.
- Due to bandwidth limits, throughput was around 1000 requests/second.
- Simulated concurrency: 1200 threads/second
- Read/write ratio: 7:3
An out-of-the-box admin front-end template based on Vue 3, Vite, TypeScript, and Element Plus.
-
QQ Group:
780634162 -
If you made it this far, please give the project a
star!
This project is open sourced under the MIT License. See LICENSE for details.