Build and deploy enterprise-grade microservices in under an hour

View the documentation »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Main Features
   • Built With
2. Getting Started
   • Prerequisites
   • Creating a Project
   • Adding Nox
   • Define Your Service and Entities
   • Setup SqlServer with Docker
   • Start Your Service
   • Exploring Your New API
   • Swagger Docs
   • Add a Currency
   • Display Currencie
   • Filtering and Pagination
   • Next Steps
3. Roadmap
4. Contributing
5. License
6. Contact
7. Acknowledgments

About The Project

---

Nox is a .NET microservice framework that allows developers to rapidly build, maintain and deploy enterprise-grade, production-ready microservices.

It removes all the ceremony, repetition and technical details associated with building and maintaining applications without constraining developer creativity or control in any way.

Main Features

---

Nox lets you focus on your business problem and domain, and provides you with the following auto-magic features:-

• Declaration of your core application and domain (models, data, entities, attributes and bounded contexts) in a declaritive and easily maintainable way (YAML, using YamlDotNet)
• Automatic (and selective) Create, Read, Update and Delete (CRUD) API for entities and/or aggregate roots (supports REST with OData, with GraphQL and gRPC in the making)
• The choice of persisting your data in any database with current support for Sql Server, PostgreSQL or MySql (using Entity Framework)
• Automated Database Migrations (coming soon)
• Validation of entities and attributes (using FluentValidation)
• Logging, Observability and Monitoring (using SeriLog)
• Events and Messaging (In process/Mediator, Azure Servicebus, Amazon SQS, RabbitMQ) using MassTransit
• Extract, transform and load (ETL) definitions from any database, file or API with bulk-load and merge support
• A task scheduler for running recurring tasks at periodic intervals (using Hangfire)
• Automated DevOps including testing and deployment

(back to top)

Built With

---

(back to top)

Getting Started

---

Prerequisites

---

Make sure you have .NET 6 and Docker installed on your PC.

PS> dotnet --version
6.0.404

PS> docker-compose --version
Docker Compose version v2.13.0

Creating A Project

---

Create .NET 6.0 web api project at the command line in your repositories using dotnet.

dotnet new webapi -o SampleCurrencyService

cd SampleCurrencyService

At this point you can do a normal dotnet run which will present you with the standard Microsoft demo WeatherController.

Adding Nox

---

Add the Nox.Lib nuget package to your project.

dotnet add package Nox.Lib

Edit your Program.cs file and add the following three lines..

using Nox; // <--- Add this (1) <---

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.

builder.Services.AddNox(); // <--- Add this (2) <---
builder.Services.AddControllers();
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

app.UseNox(); // <--- Add this (3) <---

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Define Your Service and Entities

---

Create a new file to define your service called SampleCurrency.service.nox.yaml:

#
# SampleCurrency.service.nox.yaml
#
# yaml-language-server: $schema=https://noxorg.dev/schemas/NoxConfiguration.json
#

name: SampleCurrencyService

description: Sample Currency Microservice

database:
  name: SampleCurrencyDb
  provider: sqlServer
  server: localhost
  user: sa  
  password: Developer*123

messagingProviders:
  - name: InProcess
    provider: mediator

Create an entity definition in Currency.entity.nox.yaml

#
# Currency.entity.nox.yaml
#

name: Currency
description: Currency definition and related data

attributes:

  - name: Id
    description: The currency's unique identifier 
    isPrimaryKey: true
    type: int

  - name: Name
    description: The currency's name 
    isRequired: true
    type: string
    maxWidth: 128

  - name: ISO_Alpha3
    description: The currency's official ISO 4217 alpha-3 code
    isRequired: true
    isUnicode: false
    type: char
    minWidth: 3
    maxWidth: 3

  - name: Symbol
    description: The currency's well known symbol
    type: string
    maxWidth: 5

Setup SqlServer with Docker

---

Create a docker-compose.yaml for running a Sql Server conatainer

version: '3.7'

services:
  sqlserver:
    container_name: sqlserver_container
    image: "mcr.microsoft.com/azure-sql-edge:latest"
    user: root
    ports:
      - "1433:1433"
    environment:
      SA_PASSWORD: "Developer*123"
      ACCEPT_EULA: "Y"
      MSSQL_PID: "Developer"
    volumes:
      - ./.docker-data/sqlserver:/var/opt/mssql/data

Then start your database with:

docker-compose up -d

Start Your Service

---

Finally, start your API with:

dotnet run

The application will start up, Nox will dynamically process the YAML files. Take note of the port that dotnet new webapi assigned to your project.

In this case the http port is 5237 and we will use it below (use your port number wherever you see 5237 instead).

Alternatively, you can change the port your service uses by editing the applicationUrl in the profiles section in .\Properties\launcgSettings.json as follows.

  "profiles": {
    "SampleCurrencyService": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "launchUrl": "swagger",
      "applicationUrl": "https://localhost:7237;http://localhost:5237",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },

You will then be able to follow the exploration section of these docs using the same port.

Exploring Your New API

---

Startup Postman or your browser and navigate to http://localhost:5237/WeatherController to see that the Microsoft standard controller works.

Swagger Docs

---

To view the dynamic endpoints that Nox added to your project,browse to http://localhost:5237/swagger.

Add a Currency

---

In Postman, setup a POST request to http://localhost:5237/odata/Currencies, and on the Body tab, set the content-type to raw and JSON and the body content to:

{
    "Id": 8383,
    "Name": "Bitcoin",
    "Symbol": "₿",
    "ISO_Alpha3": "XBT"
}

When you click on the Send button, you should get a 201 (Created) response.

You can create an entry for US Dollars by replacing the body with:-

{
    "Id": 840,
    "Name": "US Dollar",
    "Symbol": "$",
    "ISO_Alpha3": "USD"
}

Display Currencies

---

To display the currencies you've just added send a GET request to http://localhost:5237/odata/Currencies

Filtering and Pagination

---

You can try the following url's with GET to further explore the API.

http://localhost:5237/odata/Currencies(840)
http://localhost:5237/odata/Currencies(840)/Name
http://localhost:5237/odata/Currencies?$select=Id,Name
http://localhost:5237/odata/Currencies?$select=Id,Name&$orderby=Name
http://localhost:5237/odata/Currencies?$filter=Name eq 'US Dollar'
http://localhost:5237/odata/Currencies?$filter=Name ne 'US Dollar'

You can read up more about the many features of OData at https://www.odata.org/

Next Steps

---

This quick-start is really just the tip of the Nox iceberg. To develop serious microservices for business requires quite a bit more than a quick API.

More documentation will be added shortly to help illustrate the broader feature-set of Nox-enabled applications.

Roadmap

---

• Model-driven gRPC API's automatically for high-performance inter-service communication
• GraphQL API automatically from YAML definitions
• Health monitoring and observability as a first class features
• ETL from files, API's and other database types
• Production caching usin ElasticSearch
• Full DevOps automation for creating, deploying and apgrading applications
• Multi-environment support (dev/test/uat/prod/...)
• Proper versioning of application changes accross deployments
• DotNet command line tooling for Nox to interactively create YAML files, Helm charts and other required DevOps artifacts
• E-Mail and other notification mechanisms for applications
• Automated Backend-for-Frontend (BFF) creation
• A universal Blazor-based UX that is dynamic rendered from the YAML definition
• Better Swagger and user project documentation generation
• A universal admin console to combine the various underlying library frontends (eg Hangfire)

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

---

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Hassle-free Development

---

The Nox project uses the goo cross-platform development to make building and testing code hassle free.

git clone https://github.com/noxorg/nox.git

cd Nox

.\.goo.ps1 init

This should guide you through the pre-requisites needed to productively build and change Nox.

To view the project workflows, type:

.\.goo.ps1

and it'll display something like:

(back to top)

You should then be able to simply type `goo` anywhere in your project folder structure to return you to the project root and display these options.

License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

Contact

Twitter: @AndreSharpe72

Project Link: https://github.com/noxorg/nox

(back to top)

Acknowledgments

• Nox was inspired and draws heavily from Paul DeVito's very impressive Wrapt project. Nox is essentially (a less feature-rich) Wrapt without the code generation and aims to keep developer code 100% separate from the framework, and imposes no constraints on application architecture.
• Nox would not have been possible without the many open-source projects that it draws from. The goal is to build on top of an already rich ecosystem of great libraries and tools like Microsoft's .NetCore, YamlDotNet, NewtonSoft.Json, Hangfire, Serilog, SqlKata, ETLBox, Entity Framework, MassTransit and others.

(back to top)