A pragmatic .NET 8 reference architecture for modular monoliths, distributed applications, and microservice systems.
Why ADNC · Design Principles · Architecture · Getting Started · Documentation
简体中文 · English
ADNC is an open-source distributed application framework built on .NET 8. It brings together the infrastructure, conventions, and sample services that teams typically need when building production-grade business systems: gateway routing, service discovery, centralized configuration, authentication, inter-service communication, event-driven integration, persistence, caching, observability, resilience, and deployment support.
The repository is both a framework and a working reference implementation. It includes reusable Adnc.Infra.* packages, shared service-layer packages, an Ocelot gateway, a multi-service demo domain, database scripts, Docker Compose infrastructure assets, and English/Chinese documentation.
ADNC is intentionally not a one-size-fits-all template. It demonstrates how different service shapes can coexist in the same system: classic layered services, compact single-project services, and DDD-style services with explicit domain layers.
Distributed systems fail most often at the boundaries: service ownership, data consistency, configuration drift, operational visibility, authentication, and integration contracts. ADNC focuses on those boundaries instead of only scaffolding controllers and repositories.
Use ADNC when you want:
- A practical
.NET 8architecture baseline for business applications. - A reference implementation for moving from modular monoliths toward microservices.
- Consistent infrastructure abstractions across services without forcing identical project layouts.
- Examples of HTTP, gRPC, and event-driven service integration in one repository.
- A realistic demo that includes gateway, identity, persistence, cache, messaging, tracing, logs, and deployment assets.
- Source code and documentation that can be studied, customized, or selectively adopted.
ADNC is not positioned as:
- A black-box platform that hides .NET application architecture.
- Generated code with no architectural intent.
- A microservice-only template that requires every bounded context to be deployed independently from day one.
- A benchmark report. Performance notes are scenario references, not guarantees.
Modular first, distributed when necessary
Service boundaries should be explicit before deployment boundaries become expensive. ADNC supports modular service design and lets teams adopt distributed deployment where the operational cost is justified.
Different domains deserve different shapes
Small CRUD-oriented services do not need the same structure as domain-heavy services. The demo intentionally includes multiple project styles so teams can make informed trade-offs.
Infrastructure is shared; business behavior is owned by services
Cross-cutting concerns such as authentication, caching, repository patterns, remote calls, events, logging, and health checks are centralized in reusable packages. Business logic remains in service-specific application and domain layers.
Operational concerns are part of the architecture
Configuration, discovery, tracing, logging, gateway routing, health checks, and deployment assets are treated as first-class concerns, not afterthoughts.
Prefer replaceable integrations
The project uses established .NET ecosystem components such as Ocelot, Consul, Refit, gRPC, EF Core, Dapper, CAP, RabbitMQ, Redis, Polly, NLog, SkyAPM, and HealthChecks. ADNC organizes these tools behind consistent conventions rather than reinventing them.
At a high level, ADNC is organized into four parts:
| Layer | Responsibility |
|---|---|
| Gateway | Ocelot-based API gateway, routing, authentication integration, Consul provider, resilience policies |
| Infrastructure | Reusable packages for Consul, Redis, repositories, event bus, ID generation, helpers, and core primitives |
| Shared Service Layer | Common application, domain, repository, remote-call, and web API building blocks |
| Demo Services | Business services that show layered, compact, and DDD-oriented service structures |
The src/Infrastructures directory contains reusable packages under the Adnc.Infra.* namespace.
| Area | Projects |
|---|---|
| Core primitives | Adnc.Infra.Core, Adnc.Infra.Helper |
| Service discovery and configuration | Adnc.Infra.Consul |
| Event bus | Adnc.Infra.EventBus |
| ID generation | Adnc.Infra.IdGenerater |
| Redis | Adnc.Infra.Redis, Adnc.Infra.Redis.Caching |
| Repository abstraction | Adnc.Infra.Repository |
| Repository implementations | Adnc.Infra.Repository.Dapper, Adnc.Infra.Repository.EfCore, Adnc.Infra.Repository.EfCore.MySql, Adnc.Infra.Repository.EfCore.SqlServer, Adnc.Infra.Repository.EfCore.MongoDB |
- NuGet: packages matching
adnc.infra
The src/ServiceShared directory contains reusable service-level building blocks under the Adnc.Shared.* namespace.
| Area | Projects |
|---|---|
| Shared constants and context | Adnc.Shared |
| Application layer | Adnc.Shared.Application, Adnc.Shared.Application.Contracts |
| Domain layer | Adnc.Shared.Domain |
| Repository layer | Adnc.Shared.Repository |
| Remote calls | Adnc.Shared.Remote |
| Web API infrastructure | Adnc.Shared.WebApi |
| Capability | ADNC Direction |
|---|---|
| API gateway | Ocelot gateway with routing, Consul integration, authentication, and Polly support |
| Service discovery | Consul-based registration and discovery |
| Configuration | Local environment settings plus Consul-backed configuration center |
| Service communication | Refit-based HTTP clients and gRPC clients via Grpc.Net.ClientFactory |
| Event integration | CAP, RabbitMQ, integration event contracts, and event tracking support |
| Persistence | EF Core, Dapper, MySQL, SQL Server, and MongoDB-oriented infrastructure |
| Transactions | Unit of Work support and eventual consistency through CAP |
| Caching | Redis provider, distributed cache abstraction, distributed locks, and Bloom filter support |
| Security | JWT authentication, authorization helpers, shared web API infrastructure |
| Observability | NLog, Loki target, SkyAPM/SkyWalking, HealthChecks, Prometheus-related packages |
| Resilience | Polly-based transient fault handling at gateway and service-call boundaries |
| Engineering baseline | Central Package Management, shared build props, editor configuration, solution slicing |
| Category | Technologies |
|---|---|
| Runtime | .NET 8 |
| Gateway | Ocelot |
| Registry and configuration | Consul |
| Remote calls | Refit, gRPC |
| Persistence | EF Core, Dapper, MySQL, SQL Server, MongoDB |
| Messaging and consistency | CAP, RabbitMQ |
| Cache | Redis |
| Resilience | Polly |
| Logging and tracing | NLog, Loki, SkyAPM, SkyWalking |
| Metrics and health | Prometheus packages, AspNetCore HealthChecks |
| API and validation | Swashbuckle, FluentValidation |
| Mapping | AutoMapper |
adnc
├── .github/ GitHub Actions workflows
├── database/ Database initialization script
├── deploy/ Docker Compose assets for staging-like infrastructure
├── docs/
│ ├── architecture/ Architecture decision records
│ └── wiki/ English and Chinese documentation source
├── src/
│ ├── Infrastructures/ ADNC infrastructure packages
│ ├── ServiceShared/ Shared service-layer building blocks
│ ├── Gateways/ Ocelot gateway
│ └── Demo/ Demo microservices
├── test/ Test-related projects
├── README.md
├── README_ZH.md
└── LICENSE
| Path | Purpose |
|---|---|
src/Adnc.sln |
Main solution containing the ADNC framework projects |
src/Infrastructures/Adnc.Infra.sln |
Infrastructure-only solution |
src/ServiceShared/Adnc.Shared.sln |
Shared service-layer solution |
src/Demo/Adnc.Demo.sln |
Demo service solution |
src/Gateways/Ocelot/Adnc.Ocelot.sln |
Ocelot gateway solution |
Build configuration is centralized through:
src/Directory.Build.props: shared build settings, includingnet8.0, nullable reference types, implicit usings, package metadata, and documentation generation.src/Directory.Packages.props: Central Package Management for NuGet versions.src/.editorconfig: cross-editor code style configuration.
The fastest way to get started is to follow the quick start guide. The demo requires infrastructure such as Consul, Redis, RabbitMQ, MySQL, logging components, and service configuration, so the startup sequence matters.
- Install the
.NET 8 SDK. - Read the ADNC Quick Start Guide.
- Open
src/Adnc.slnfor framework packages orsrc/Demo/Adnc.Demo.slnfor demo services. - Prepare infrastructure from the quick start guide or the Docker Compose assets in
docs/devops-staging. - Initialize demo data from
database/mysql/adnc.sql. - Start the gateway and demo services in the documented order.
For Docker-oriented setup, use the Quick Docker Deployment Guide.
The demo contains five business services and shared cross-service contracts. Each service uses a different structure to make the architectural trade-offs visible.
| Service | Business Scope | Architecture Style |
|---|---|---|
| Admin | Organization, users, roles, permissions, dictionaries, and configuration | Classic layered architecture with separated application contracts |
| Maint | Logs, audits, and operations management | Classic layered architecture with contracts merged into the application layer |
| Cust | Customer management | Minimal single-project service |
| Ord | Order management | DDD-style service with a domain layer |
| Whse | Warehouse management | DDD-style service with a domain layer |
src/Demo/Shared
├── Remote.Event/ Integration event contracts
├── Remote.Grpc/ gRPC client definitions
├── Remote.Http/ HTTP client definitions
├── protos/ gRPC protocol definitions
└── resources/ Shared configuration and resources
Admin/
├── Api/
├── Application/
├── Application.Contracts/
└── Repository/
Maint/
├── Api/
├── Application/
└── Repository/
Cust/
└── Api/
Ord/
├── Api/
├── Application/
├── Domain/
└── Migrations/
Whse/
├── Api/
├── Application/
├── Domain/
└── Migrations/
ADNC has a companion admin front-end built with Vue 3, Vite, TypeScript, and Element Plus.
- Official website: https://aspdotnetcore.net
- Documentation: https://docs.aspdotnetcore.net
- Online demo: https://online.aspdotnetcore.net
- Code generator: https://code.aspdotnetcore.net
The project includes JMeter-oriented notes from a demo environment covering gateway routing, service discovery, configuration center access, synchronous service calls, CRUD operations, local transactions, distributed transactions, caching, Bloom filters, tracing, logging, and operation logs.
Reference environment:
- ECS server: 4 vCPU, 8 GB RAM, 8 Mbps bandwidth.
- Approximate remaining capacity during testing: 50 percent CPU and 50 percent memory.
- Observed throughput around 1000 requests per second, constrained by bandwidth.
- Simulated concurrency: 1200 concurrent threads.
- Read/write ratio: 7:3.
These numbers are environment-specific and should be treated as scenario notes, not benchmark guarantees.
Issues, discussions, and pull requests are welcome. For larger changes, start by opening an issue that explains the problem, proposed direction, and expected impact on existing packages, demo services, or documentation.
When contributing code, try to preserve the project intent:
- Keep infrastructure concerns reusable and service-agnostic.
- Keep business behavior inside the relevant demo service.
- Prefer established .NET ecosystem components over custom infrastructure unless there is a clear reason.
- Update documentation when behavior, configuration, or startup flow changes.
If ADNC helps you evaluate, teach, or build .NET distributed systems, consider giving the repository a star.
ADNC is released under the MIT License.