Nano - Your lightweight foundation for building modern .NET applications.
📌 Summary
✨ Highlighted Features
🏛️ Nano Architectures
🧩 Solution Composition
NuGet Packages
🔏 Licenses
🚀 Applications
📡 Api
⚙️ Console
🌐 Web
📜 Logging
🛢️ Data
⚡ Eventing
🗂 Storage
Nano is a lightweight library for rapidly building modern .NET applications.
These pages provide documentation, guides, samples, and other resources to help you understand and use Nano effectively. To set the stage, here’s why Nano is a strong choice when building .NET applications.
At its core, Nano gives you everything you need to start building microservices without getting bogged down in non-business concerns. It provides configurable implementations based on proven practices, patterns, and conventions from modern development. Designed to integrate naturally with dependency injection, Nano allows you to register custom services while retaining full control to override, extend, or disable any part of the framework. This flexibility lets you derive enriched implementations from core abstractions, so you can stay focused on modeling your business domain rather than managing boilerplate.
As your solution evolves, Nano scales with you. It becomes easy to compose multiple applications that work seamlessly together, whether you're building APIs or web applications for different audiences or reusing functionality across domains. Console applications can support scheduled or background batch processing, while built-in features such as event-driven entity synchronization and a dedicated API client simplify communication between services. Combined with support for health monitoring, startup tasks, background workers, audit and more, Nano helps cover the full application lifecycle, from development and configuration to deployment and hosting.
✨ Check out our Highlighted Features
To support production-grade environments, Nano also provides the foundation for running applications securely and at scale in Kubernetes on Azure. Nano includes ready-to-use templates for Kubernetes and GitHub Actions, enabling consistent CI/CD pipelines and infrastructure provisioning.
📖 Learn more about Nano.Azure and Nano.Azure.Kubernetes
Together, these capabilities make Nano a strong choice for designing, building, and maintaining microservice architectures, even for small teams.
Get started quickly by building your own Nano Api, Web, or Console application, and have it configured and running in less than an hour. Nano follows a flexible, opt-in approach, allowing you to configure and enable only the features you need. For the four core pillars of distributed systems, Logging, Data, Eventing, and Storage, Nano provides pluggable providers that integrate seamlessly into your application. Simply choose and configure the providers that match your requirements for each pillar, and Nano handles the rest.
It’s recommended to start with the Quick Start Guide to get familiar with Nano, and then continue exploring the documentation for applications and providers to learn how to configure, use, and customize it. You can also dive into Nano.Lessons, which contains 100+ focused examples that demonstrate individual features in isolation.
💡 Explore API requests for all lessons in our Public Nano Workspace on Postman.
Nano provides a generic API client that enables seamless communication between distributed Nano services. It is designed for API-based applications and allows services to interact in a structured and consistent way across systems.
API clients are configured through application settings and are automatically injected where needed, making service-to-service communication simple and centralized. They provide access to common functional areas such as data operations, authentication, auditing, and identity workflows through consistent conventions.
In addition to built-in capabilities, Nano supports extending API clients with custom endpoints, enabling strongly typed and flexible integration with application-specific functionality. Authentication, headers, and request metadata are handled automatically, including secure propagation between services. This ensures reliable, consistent, and secure communication across all connected Nano applications without additional boilerplate.
📖 Learn more about Api Clients
Entity Events in Nano provide a lightweight, attribute-driven mechanism for synchronizing entity changes across distributed applications. They automatically propagate create, update,
and delete operations through structured EntityEvents, reducing the need for manual integration logic in microservice architectures.
The PublishAttribute defines which entities emit events and which properties are included in the event payload, including support for navigation paths. The SubscribeAttribute
enables models to react to incoming events and automatically apply changes through the built-in event handler.
Entity eventing supports inheritance, deterministic payload shaping, and automatic data hydration to ensure complete event consistency. Reverse dependency tracking allows changes in dependent entities to propagate back to root aggregates.
This model reduces coupling between services while maintaining data consistency across boundaries.
📖 Learn more about Entity Eventing
Nano’s Include feature automatically loads navigation properties when retrieving entities through repositories, enabling full entity graphs with recursive inclusion up to a configured depth. It supports both references and collections, simplifying data access for rich models.
This is especially useful when you want to work with complete object graphs instead of manually composing related data. However, inclusion can be selectively controlled per query, allowing you to retrieve only the main entity when full graphs are not needed.
📖 Learn more about Include Annotations
Nano provides built-in health checks exposed through a /healthz endpoint for monitoring application status.
All Nano providers and services can participate in health monitoring when enabled, automatically reporting their status. Health checks are structured as a dependency tree, where failures propagate through related components and applications to provide a consistent view of overall system health.
In addition, custom health checks can be registered during application startup, allowing application-specific components to integrate seamlessly into the same monitoring system.
📖 Learn more about Api Health Checks
Nano supports multiple distributed architecture styles, depending on the complexity and communication patterns of your system.
| Architecture | Description |
|---|---|
| Solo Application | A single, independent application. |
| Microservice Orchestration (Top-down) | API-driven orchestration where a central API coordinates downstream services. |
| Microservice Orchestration (Service-to-Service) | Decentralized communication where services interact directly with each other. |
All Nano applications follow a consistent and predictable solution structure.
In local Development, the application is orchestrated using Docker Compose, while Staging and Production environments are deployed and managed using Kubernetes.
Continuous Integration and Continuous Delivery (CI/CD) is handled by GitHub Actions and is included as part of the Nano Visual Studio solution.
The solution root also contains several supporting files, such as Docker- and Git-related configuration files, along with various asset files used by the Git repository and NuGet packages.
In the following table shows the different files and folder strucutre.
| Directory / File | API | WEB | CON | Description |
|---|---|---|---|---|
.docker/docker-compose.dcproj |
✓ | ✓ | ✓ | The Docker Compose project used by Visual Studio for local orchestration. |
.docker/docker-compose.yml |
✓ | ✓ | ✓ | The Docker Compose specification for orchestrating the application locally in the Development environment. |
.github/config/slack.yml |
✓ | ✓ | ✓ | Configuration for posting build and deploy notifications to Slack (optional). |
.github/workflows/build-and-deploy.yml |
✓ | ✓ | ✓ | GitHub Actions workflow that builds, tests, publishes artifacts, and deploys a Nano application. |
.kubernetes/configmap.yaml |
✓ | ✓ | ✓ | ConfigMap specification for Kubernetes. |
.kubernetes/autoscaler.yaml |
✓ | ✓ | ✗ | Horizontal Pod Autoscaler (HPA) specification. |
.kubernetes/deployment.yaml |
✓ | ✓ | ✗ | Deployment specification. |
.kubernetes/service.yaml |
✓ | ✓ | ✗ | Service exposure specification. |
.kubernetes/ingress.yaml |
(✓) | (✓) | ✗ | Ingress specification (Optional). |
.kubernetes/certificate.yaml |
(✓) | (✓) | ✗ | SSL Certificate specification (Optional). |
.kubernetes/cronjob.yaml |
✗ | ✗ | ✓ | CronJob specification. |
.tests/Tests.{name}.csproj |
✓ | ✓ | ✓ | Test project, which is empty by default and included to demonstrate the structure and where unit or integration tests should be added. |
.tests/Properties/DoNotParallelize.cs |
✓ | ✓ | ✓ | Ensures tests are not Parallelized. |
{name}/{name}.csproj |
✓ | ✓ | ✓ | The application project file. |
{name}/Properties/InternalsVisibleTo.cs |
✓ | ✓ | ✓ | Exposes internal types to the test project. |
{name}/wwwroot |
✓ | ✓ | ✗ | Root folder for static and dnyamic web content. |
{name}/appsettings.json |
✓ | ✓ | ✓ | Default application configuration file. |
{name}/appsettings.{environment}.json |
✓ | ✓ | ✓ | Overrides application configuration files for for environments: Development, Staging and Production. |
{name}/Dockerfile.Local |
✓ | ✓ | ✓ | Used by Docker Compose in Development environment; must remain in the application project folder. |
{name}/Program.cs |
✓ | ✓ | ✓ | The main entry point to the Nano application, and where the application is configured, build and run. |
{name}/{name}.Models.csproj |
✓ | ✓ | ✗ | The application models project file. The project is configured to publish a NuGet for sharing models and api-client. Nano Nugets should be included here, as a minimum the Nano.App NuGet package. |
.dockerignore |
✓ | ✓ | ✓ | Lists files and folders to ignore when building Docker images. |
.gitignore |
✓ | ✓ | ✓ | Lists files and folders to ignore in Git version control. |
Dockerfile |
✓ | ✓ | ✓ | The Dockerfile used to build the container image for Staging and Production deployments. |
README.md |
(✓) | (✓) | (✓) | Documentation asset for the Git repository and the application’s NuGet package (Optional). |
icon.png |
(✓) | (✓) | ✗ | Icon asset for the application’s NuGet package (Optional). |
LICENSE |
(✓) | (✓) | ✗ | License file for the Git repository and the application’s NuGet package (Optional). |
{name}.sln |
✓ | ✓ | ✓ | The visual studio solution file. |
These packages are all-inclusive packages, where all other Nano packages are included. Easy to get started, but it's recommended to instead select only the packages needed by your application, to avoid unnecessary depdendencies.
| Package | Downloads | |
|---|---|---|
| Nano.All |  |
 |
| NanoCore | |
|
The next packages are application packages. Include only one matching the application type you want to create.
| Package | Type | Downloads | Latest Version |
|---|---|---|---|
| Nano.App | Transitive |
 |
 |
| Nano.App.Api | Application |
 |
 |
| Nano.App.Console | Application |
 |
 |
| Nano.App.Web | Application |
 |
 |
Last, provider packages. These enable functionality related to Nano providers.
| Package | Type | Downloads | Latest Version |
|---|---|---|---|
| Nano.Data | Data, Transitive |
 |
 |
| Nano.Data.Abstractions | Data, Transitive |
 |
 |
| Nano.Data.InMemory | Data |
 |
 |
| Nano.Data.MySql | Data |
 |
 |
| Nano.Data.PostgreSQL | Data |
 |
 |
| Nano.Data.SqLite | Data |
 |
 |
| Nano.Data.SqlServer | Data |
 |
 |
| Nano.Eventing | Eventing, Transitive |
 |
 |
| Nano.Eventing.Abstractions | Eventing, Transitive |
 |
 |
| Nano.Eventing.RabbitMq | Eventing |
 |
 |
| Nano.Logging | Logging, Transitive |
 |
 |
| Nano.Logging.Abstractions | Logging, Transitive |
 |
 |
| Nano.Logging.Log4Net | Logging |
 |
 |
| Nano.Logging.Microsoft | Logging |
 |
 |
| Nano.Logging.NLog | Logging |
 |
 |
| Nano.Logging.Serilog | Logging |
 |
 |
| Nano.Storage | Storage, Transitive |
 |
 |
| Nano.Storage.Abstractions | Storage, Transitive |
 |
 |
| Nano.Storage.Azure | Storage |
 |
 |
| Nano.Storage.Local | Storage |
 |
 |
Nano is free to use and released under the MIT License.
Dependencies are distributed under a combination of the following licenses.
| License | Description |
|---|---|
| MIT | Permissive license with minimal restrictions. |
| Apache-2.0 | Permissive with patent protection. |
| BSD-2 Clause | Simple permissive license with attribution. |
| BSD-3 Clause | Permissive with non-endorsement clause. |
| PostgreSQL | Permissive, similar to MIT/BSD. Only when using PostgreSQL as data provider. |