[![Nuget][version-shield]][version-url][![contributors][contributors-shield]][contributors-url][![issues][issues-shield]][issues-url][![stars][stars-shield]][stars-url][![build][build-shield]][build-url][![forks][forks-shield]][forks-url]
Build and deploy enterprise-grade business solutions in under an hour
Table of Contents
- About
- Main Features
- Contributing to the Nox library
- Using the Nox Library
# About
Nox.Lib is a .NET framework that allows developers to rapidly build, maintain and deploy enterprise-grade, production-ready business solutions.
> 💡 At its heart, Nox is a code scaffolding engine that is extended through a range of handlers, including message, command, query and event handlers.
Nox pivots around the concept of a *solution definition*. This solution describes the domain, application, integrations, infrastructure, version control and project team. The Nox.Generator interprets this *solution* and scaffolds all the necessary code for a working solution.
# Main 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.
- [Nox.Yaml](src/readme.md) is a dotnet standard wrapper to YamlDotnet that takes the pain out of using YAML configuration files for your projects.
# Contributing to the Nox library
We welcome community pull requests for bug fixes, enhancements, and documentation. See [How to contribute](./docs/CONTRIBUTING.md) for more information.
## Local Development
To run the SampleWebApp you need to have SQL Server running. This is a temporary measure until support for MySQL and PostreSQL is implemented.
In the root of your project start SQL Server in a Docker container by running `docker-compose -f .\docker-compose.sqlServer.yml up`
Update database with migrations by running the command `dotnet ef database update -c "SampleWebAppDbContext"`
Run the Sample the database should be provisioned and properly setup its model.
## Update the Database Model
Migration history do not need to be tracked, usually during local development you can delete 'Migration' folder and create a new migration.
If you don't have .NET [EF Core Tools](https://www.nuget.org/packages/dotnet-ef) installed, run `dotnet tool install --global dotnet-ef` at the command line. You'll also need to add [EF Core Design](https://www.nuget.org/packages/Microsoft.EntityFrameworkCore.Design) to your project to run migrations. Simply run `dotnet add package Microsoft.EntityFrameworkCore.Design`.
To generate initial migration you can use the following command `dotnet ef migrations add "InitialCreate" -c "SampleWebAppDbContext"`
## Odata
[OData](https://www.odata.org/) endpoints in debug mode can be found at `\$odata`
## \[Nox.Solution\] Updating Schemas
Until this process is automated, whenever a new TypeOption is added to the Nox Solution the following steps must be followed:
1. Add your new type to class NoxSimpleTypeDefinition inside the `#region TypeOptions`;
2. Run the test in **NoxSolutionSchemaGenerate**, this test will generate the new schema files;
3. Add and commit changed `.json` schema files to the solution.
## \[Nox.Types\] ToString conventions
Nox does not follow the usual convention for `ToString()`.
The `ToString()` method should return the same result independently of the current culture, for example for DateTime, Currency, dependent types.
The reasoning behind this is to ensure a fully predictable result that facilitates ETL processes and interoperability with other systems.
The same is expected for the `ToString(string format)` overload.
If you need a culture dependent representation create an overload with a `IFormatProvider` parameter, example:
```csharp
ToString(IFormatProvider formatProvider);
```
LatLong Nox.Type example:
```csharp
public override string ToString()
{
return $"{Value.Latitude.ToString("0.000000", CultureInfo.InvariantCulture)} {Value.Longitude.ToString("0.000000", CultureInfo.InvariantCulture)}";
}
public string ToString(IFormatProvider formatProvider)
{
return $"{Value.Latitude.ToString(formatProvider)} {Value.Longitude.ToString(formatProvider)}";
}
```
## Versioning
We are using [SemVer](https://semver.org/) for versioning our deliverables.
To manage this version we are using [GitVersion](https://github.com/GitTools/GitVersion) tool.
### Using it locally
You can use gitversion locally to test and setup configuration. To do that intall the dotnet tool `dotnet tool install --global GitVersion.Tool --version 5.*`
Run `dotnet-gitversion` to see the current variables of git version
Run `dotnet-gitversion /updateprojectfiles` to update csproject files
## Release
Create a release in GitHub and tag it properly. In the future we want to automate this process.
# Using the Nox Library
## Environment Variables for Sensitive Data
Do not commit or keep sensitive data on your yaml solution files.
The current way to this is by using Environment Variables.
### Example
Nox will expand any text with the following convention `${{ env.VAR_NAME }}` to the value of **VAR_NAME** Environment Variable if found. Sample Yaml:
```yaml
databaseServer:
name: SampleCurrencyDb
serverUri: ${{ env.DB_SERVER }}
provider: sqlServer
port: 1433
user: ${{ env.DB_USER }}
password: ${{ env.DB_PASSWORD }}
```
## Query and Command Extensibility
### Security and other Validations
To add security, or other business rules to generated/custom queries or commands, add an `IValidator` interface for the query. See the example below for securing `GetStoreByIdquery`
```csharp
public class GetStoreByIdSecurityValidator : AbstractValidator
{
public GetStoreByIdSecurityValidator(ILogger logger)
{
// For the Current User
// TODO Get Stores that he can see....
// Do Validation The current user can only see EUR Store
RuleFor(query => query.key).Must(key => key == "EUR").WithMessage("No permissions to access this store");
}
}
```
The validator will be excuted before the request. Adding the validator to the service collection as per the code snippet below should yield a `ValidationException` at runtime:
```csharp
services.AddSingleton, GetStoreByIdSecurityValidator>();
```
