Genocs .NET library

.NET CLI

Open Source Library For .NET10 Microservice
Read the Documentation »

Report Bug · Request Feature . Request Documentation

Genocs .NET library

This repo contains a set of libraries to build LOB (Line Of Business) applications. The library is open source and built to be PRODUCTION READY. The library is built on top of .NET10, it is designed and maintained by Genocs.

Packages are available on NuGet Genocs.

The idea

Build a software library to be cloud agnostic

Building a software library to be cloud agnostic has several advantages. First, it allows developers to create applications that can be deployed on any cloud platform without having to rewrite code or make major changes. This makes it easier for developers to quickly deploy their applications across multiple cloud providers. Additionally, it reduces the cost of development and maintenance since developers don’t have to write separate code for each cloud provider. Finally, it increases the scalability of applications since they can be easily deployed on different cloud platforms with minimal effort.

Cloud agnostic by use of Containers

The advantages of using containers are numerous. Containers provide a lightweight, portable, and isolated environment for applications to run in, allowing them to be easily moved between different systems. This makes it easier to deploy applications quickly and reliably across different environments. Additionally, containers can help reduce resource consumption by running multiple applications on the same host, as each container is isolated from the others. This helps to improve efficiency and scalability. Finally, containers provide an additional layer of security, as they are isolated from the underlying operating system and other applications.

Documentation

You can find a useful documentation about how to use the library. The documentation contains the complete set of libraries, template, CLI that altogether make the genocs ecosystem a comprensive set of tools to build enterprise solutions.

Documentation available at Genocs Blog

Quick Start

Prerequisites

Install .NET 10 SDK
Install Docker
Install Docker Compose
Install Visual Studio Code with the following extensions:
- C#
- Docker
- YAML
- REST Client

Setup

Clone the repository

git clone https://github.com/Genocs/genocs-library.git
cd genocs-library

Build the solution
```
dotnet build
```
Pack the projects
```
dotnet pack
```

Run project with console

dotnet run --project ./src/demo/WebApi
dotnet run --project ./src/demo/Worker
dotnet run --project ./src/demo/HelloWorld.WebApi

To pack the project with nuspec file

cd src/Genocs.Core
dotnet pack -p:NuspecFile=./Genocs.Core.nuspec --no-restore -o .

To push on nuget

dotnet nuget push
dotnet nuget push *.nupkg -k $NUGET_API_KEY -s $NUGET_SOURCE

Build webapi Docker image

docker build -t genocs/demo-webapi:2.0.0 -t genocs/demo-webapi:latest -f ./src/demo/WebApi/Dockerfile .

Push webapi Docker image to Dockerhub

docker push genocs/demo-webapi:2.0.0
docker push genocs/demo-webapi:latest

Build worker Docker image

docker build -t genocs/demo-worker:2.0.0 -t genocs/demo-worker:latest -f ./src/demo/Worker/Dockerfile .

Push worker Docker image to Dockerhub

docker push genocs/demo-worker:2.0.0
docker push genocs/demo-worker:latest

Features

Cloud Agnostic: Build applications that can run on any cloud platform without code changes.
Containerized: Lightweight and portable applications using container technology.
Microservices Ready: Easily create and manage microservices architectures.
Enterprise Integration: Built-in support for enterprise services like databases, messaging, and caching.
Monitoring and Logging: Integrated solutions for application monitoring and logging.
Security: Robust security features including API management and access control.
Scalability: Effortlessly scale applications horizontally or vertically.
Flexibility: Supports multiple programming models and architectures.
Developer Friendly: Easy to use and well-documented libraries and tools.
Open Source: Fully open source with a permissive license.

Folders structure

The repository is structured as follows:

root-project/
├── .azure/
│   ├── pipelines/
│   │   ├── ci-build.yml
│   │   ├── ci-release.yml
│   │   └── ...
├── .cursor/
│   ├── rules/
│   │   ├── solution_architect.mdc
│   │   └── ...
├── .git/
│   └── ...
├── .github/
│   ├── agents/
│   │   ├── code_reviewer.agent.md
│   │   ├── documentation_writer.agent.md
│   │   └── ...
│   ├── copilot-instructions.md
│   ├── workflows/
│   │   ├── ...
├── .vscode/
│   └── mcp.json
├── devops/
│   ├── azure
│   │   ├── ci-publish_on_acr.yml
│   │   ├── ci-publish_on_nuget.yml
│   │   └── ...
├── docs/
│   └── ...
├── infrastructure/
│   ├── bicep/
│   │   └── ...
│   ├── docker-compose/
│   │   └── ...
│   ├── k8s/
│   │   └── ...
│   ├── terraform/
│   │   └── ...
│   ├── ...
├── scripts/
│   └── ...
├── src/
│   └── ...
├── .dockerignore
├── .editconfig
├── .env
├── .gitattributes
├── .gitignore
├── Directory.Build.props
├── Directory.Build.targets
├── dotnet.ruleset
├── global.json
├── icon.png
├── stylecop.json
├── nuget.config
├── [project].sln
├── README.md
├── LICENSE
├── CHANGELOG.md
├── CONTRIBUTING.md
├── api-workbench.rest
└── ...

Infrastructure

In this section you can find the infrastructure components you need to execute the solution. Infrastructure components are the database, the enterprise service bus, the distributed logging, monitoring, tracing systems along with database and many more. You can use Docker compose to setup the infrastructure components just by running few commands.

cd ./containers

# Setup the infrastructure.
#Use this file to setup the basic infrastructure components (RabbitMQ, MongoDB)
docker compose -f ./infrastructure.yml --env-file ./.env --project-name genocs up -d

# Use this file only in case you want to setup Redis and PostgreSQL (no need if you use MongoDB)
docker compose -f ./infrastructure-db.yml --env-file ./.env --project-name genocs up -d

# Use this file only in case you want to setup monitoring infrastructure components (Prometheus, Grafana, InfluxDB, Jaeger, Seq)
docker compose -f ./infrastructure-monitoring.yml --env-file ./.env --project-name genocs up -d

# Use this file only in case you want to setup scaling infrastructure components (Fabio, Consul)
docker compose -f ./infrastructure-scaling.yml --env-file ./.env --project-name genocs up -d

# Use this file only in case you want to setup security infrastructure components (Vault)
docker compose -f ./infrastructure-security.yml --env-file ./.env --project-name genocs up -d

# Use this file only in case you want to setup sqlserver database (no need if you use PostgreSQL)
docker compose -f ./infrastructure-sqlserver.yml --env-file ./.env --project-name genocs up -d

# Use this file only in case you want to setup mySql database (no need if you use PostgreSQL)
docker compose -f ./infrastructure-mysql.yml --env-file ./.env --project-name genocs up -d

# Use this file only in case you want to setup oracle database (no need if you use PostgreSQL)
docker compose -f ./infrastructure-oracle.yml --env-file ./.env --project-name genocs up -d

# Use this file only in case you want to setup elk stack
docker compose -f ./infrastructure-elk.yml --env-file ./.env --project-name genocs up -d

# Use this file only in case you want to setup AI ML components prepared by Genocs
docker compose -f ./infrastructure-ml.yml --env-file ./.env --project-name genocs up -d

infrastructure.yml allows to install the basic infrastructure components. They are:

infrastructure-db.yml allows to install Redis and PostgreSQL

You can check them locally:

RabbitMQ: localhost:15672
Redis: TCP:localhost:6379
MongoDB: TCP:localhost:27017
Postgres: TCP:localhost:5432

infrastructure-monitoring.yml allows to install the monitoring infrastructure components. They are:

You can find the console locally at:

Aspire: localhost:18888
Prometheus: localhost:9090
Grafana: localhost:3000
InfluxDB: localhost:8086
Jaeger: localhost:16686
Seq: localhost:5341

infrastructure-scaling.yml allows to install the scaling infrastructure components composed by a Fabio (Loadbalancer) Service Discovery (Consul) components. They are:

Fabio
Consul

infrastructure-security.yml allows to install the security infrastructure components.

Inside the file you can find:

vault (Hashicorp)

NOTE

The commands above allows to setup infrastructure components, this means you can find all the containers inside the same network genocs.

Whenever possible the data are persisted on the host machine by means of volumens, so you can restart the containers without losing data.

networks:
  genocs:
    name: genocs-network
    driver: bridge

volumes:
  rabbitmq-data:
  mongo-data:
  redis-data:
  postgres-data:
  influx-data:
  grafana-data:
  jaeger-data:
  seq-data:
  vault-data:
  elk-data:
  fabio-data:
  consul-data:
  prometheus-data:
  ml-data:

Remember to add the network configuration inside your docker compose file to setup the network, before running the containers.

Kubernetes cluster

You can setup the application inside a Kubernetes cluster.

Check the repo enterprise-containers to setup a Kubernetes cluster. There you can find scripts, configuration files and documentation to setup a cluster from scratch.

Aspire Integration

SOON 🚀

Support

Use api-workbench inside Visual Studio code with REST Client plugin

Configuration

   "app": {
    "name": "Demo WebApi",
    "service": "demo-service",
    "instance": "01",
    "version": "v1.0",
    "displayBanner": false,
    "displayVersion": false
  },
  "consul": {
    "enabled": false,
    "url": "http://localhost:8500",
    "service": "demo-service",
    "address": "docker.for.mac.localhost",
    "port": "5070",
    "pingEnabled": true,
    "pingEndpoint": "healthz",
    "pingInterval": 3,
    "removeAfterInterval": 3
  },
  "fabio": {
    "enabled": false,
    "url": "http://localhost:9999",
    "service": "demo-service"
  },
  "httpClient": {
    "type": "fabio",
    "retries": 3,
    "services": {},
    "requestMasking": {
      "enabled": true,
      "maskTemplate": "*****"
    },
    "correlationIdHeader": "x-correlation-id"
  },
  "logger": {
    "level": "information",
    "excludePaths": [
      "/",
      "/healthz",
      "/alive",
      "/metrics"
    ],
    "excludeProperties": [
      "api_key",
      "access_key",
      "ApiKey",
      "ApiSecret",
      "ClientId",
      "ClientSecret",
      "ConnectionString",
      "Password",
      "Email",
      "Login",
      "Secret",
      "Token"
    ],
    "console": {
      "enabled": false
    },
    "elk": {
      "enabled": false,
      "url": "http://localhost:9200"
    },
    "file": {
      "enabled": false,
      "path": "logs/logs.txt",
      "interval": "day"
    },
    "seq": {
      "enabled": false,
      "url": "http://localhost:5341",
      "apiKey": "secret"
    },
    "azure": {
      "enabled": false,
      "connectionString": ""
    },
    "tags": {}
  },
  "jaeger": {
    "enabled": true,
    "serviceName": "orders",
    "endpoint": "http://localhost:4317",
    "protocol": "Grpc",
    "processorType": "Batch",
    "maxQueueSize": 2048,
    "scheduledDelayMilliseconds": 5000,
    "exporterTimeoutMilliseconds": 30000,
    "maxExportBatchSize": 512
  },
  "jwt": {
    "certificate": {
      "location": "certs/localhost.pfx",
      "password": "test",
      "rawData": ""
    },
    "issuer": "genocs-identities-service",
    "validIssuer": "genocs-identities-service",
    "validateAudience": false,
    "validateIssuer": true,
    "validateLifetime": true,
    "expiry": "01:00:00"
  },
  "metrics": {
    "enabled": false,
    "influxEnabled": false,
    "prometheusEnabled": false,
    "influxUrl": "http://localhost:8086",
    "database": "test",
    "env": "local",
    "interval": 5
  },
  "prometheus": {
    "enabled": false,
    "endpoint": "/metrics"
  },
  "mongodb": {
    "connectionString": "mongodb://localhost:27017",
    "database": "genocs-users-service",
    "seed": false
  },
  "outbox": {
    "enabled": false,
    "type": "sequential",
    "expiry": 3600,
    "intervalMilliseconds": 2000,
    "inboxCollection": "inbox",
    "outboxCollection": "outbox",
    "disableTransactions": false
  },
  "rabbitMq": {
    "connectionName": "users-service",
    "retries": 3,
    "retryInterval": 2,
    "conventionsCasing": "snakeCase",
    "logger": {
      "enabled": false
    },
    "username": "guest",
    "password": "guest",
    "virtualHost": "/",
    "port": 5672,
    "hostnames": [
      "localhost"
    ],
    "requestedConnectionTimeout": "00:00:30",
    "requestedHeartbeat": "00:01:00",
    "socketReadTimeout": "00:00:30",
    "socketWriteTimeout": "00:00:30",
    "continuationTimeout": "00:00:20",
    "handshakeContinuationTimeout": "00:00:10",
    "networkRecoveryInterval": "00:00:05",
    "exchange": {
      "declare": true,
      "durable": true,
      "autoDelete": false,
      "type": "topic",
      "name": "users"
    },
    "queue": {
      "declare": true,
      "durable": true,
      "exclusive": false,
      "autoDelete": false,
      "template": "users-service/{{exchange}}.{{message}}"
    },
    "context": {
      "enabled": true,
      "header": "message_context"
    },
    "spanContextHeader": "span_context"
  },
  "redis": {
    "connectionString": "localhost",
    "instance": "users-service:",
    "database": 0
  },
  "swagger": {
    "enabled": false,
    "reDocEnabled": false,
    "name": "v1",
    "title": "API",
    "version": "v1",
    "routePrefix": "swagger",
    "includeSecurity": true
  },
  "security": {
    "certificate": {
      "header": "Certificate"
    }
  },
  "azureKeyVault": {
    "enabled": false,
    "name": "gnx-keyvault",
    "managedIdentityId": "secret",
  },
  "vault": {
    "enabled": false,
    "url": "http://localhost:8200",
    "authType": "token",
    "token": "secret",
    "username": "user",
    "password": "secret",
    "kv": {
      "enabled": true,
      "engineVersion": 2,
      "mountPoint": "kv",
      "path": "users-service/settings"
    },
    "pki": {
      "enabled": true,
      "roleName": "users-service",
      "commonName": "users-service.demo.io"
    },
    "lease": {
      "mongo": {
        "type": "database",
        "roleName": "users-service",
        "enabled": true,
        "autoRenewal": true,
        "templates": {
          "connectionString": "mongodb://{{username}}:{{password}}@localhost:27017"
        }
      }
    }
  }

Demo Application

Inside the library there is a simple demo application you can use to test the library.

Following are the commands to build and run the demo application.

# Build the solution
dotnet build

# Pack the projects
dotnet pack

# Run project with console
dotnet run --project ./src/demo/WebApi
dotnet run --project ./src/demo/Worker
dotnet run --project ./src/demo/HelloWorld.WebApi

# To pack the project with nuspec file
cd src/Genocs.Core
dotnet pack -p:NuspecFile=./Genocs.Core.nuspec --no-restore -o .

# To push on nuget
dotnet nuget push
dotnet nuget push *.nupkg -k $NUGET_API_KEY -s $NUGET_SOURCE

How to build Docker Demo images

# Build webapi
docker build -t genocs/demo-webapi:2.0.0 -t genocs/demo-webapi:latest -f ./src/demo/WebApi/Dockerfile .

# Push on Dockerhub
docker push genocs/demo-webapi:2.0.0
docker push genocs/demo-webapi:latest

# Build worker
docker build -t genocs/demo-worker:2.0.0 -t genocs/demo-worker:latest -f ./src/demo/Worker/Dockerfile .

# Push on Dockerhub
docker push genocs/demo-worker:2.0.0
docker push genocs/demo-worker:latest

Enterprise Application

Application Components

Inside ./src/apps folder you can find a full-fledged application composed by:

ApiGateway
Identity Service
Order Service
Product Service
Notification Service

In that way you can test the entire flow.

Component	Description	Container Port	Visibility
ApiGateway	Handles API requests	:5500	Public
Identity Service	Manages user identities	:5510*	Private through API Gateway
Product Service	Manages product information	:5520*	Private through API Gateway
Order Service	Processes orders	:5530*	Private through API Gateway
Notification Service	Handles real-time communication	:5540*	Private through API Gateway

How to BUILD & RUN the application

The build and run process can be done by using docker-compose.

Pre-requisites:

Docker

# Build with docker compose
./src/apps/scripts/build-images-docker-compose.sh

# *** Before running the solution remember to check ***
# *** if the infrastructure services were setup     ***

# Run with docker compose
docker compose -f ./src/apps/docker-compose.yml --env-file ./local.env --project-name genocs up -d

# Clean Docker cache (optional)
docker builder prune

Some useful commands to manage the application:

# Build docker image one by one
./src/apps/scripts/build-images.sh

# Build the images with docker compose and push to Dockerhub
./src/apps/scripts/build-and-push-images.sh

Kubernetes

KubeCtl

You can deploy the application on Kubernetes cluster by using kubectl.

# Build images
./src/apps/scripts/deploy-k8s.sh

Helm chart

You can deploy the application on Kubernetes cluster by using Helm chart.

Inside the folder ./src/apps/k8s/helm you can find the Helm chart to set a K8s cluster and deploy the application.

The command below allows to install the Helm chart by using MicroK8s.

cd ./src/apps/k8s/helm
microk8s helm install genocs ./gnxchart

makefile

Prerequisites:

make

To install make on MacOS you can use brew

brew install make

To install make on Ubuntu you can use apt

sudo apt install make

To install make on Windows you can use choco

choco install make

Upon installation you can use the makefile to build, run, deploy the application.

# Build the solution
make build

MCP Servers

This repository contains support for MCP servers to be used along with VS Code. You can find the MCP servers inside the folder ./.vscode/mcp.json.

This approach allows to have a set of configured servers to be used along with VS Code and to share them with the team.

As you can immagine the drawback of this approach is that in case to be used across multiple repositories you need to copy the file in each repository. Alternative approach copy the file in a common location and configure VS Code to use that file.

For windows you can create a file named mcp.json inside the folder %USERPROFILE%/.vscode/ and add the content of the file.

NOTE:

PLEASE DOUBLE CHECK THE PATH ON MACOS AND LINUX AS IT MAY CHANGE BASED ON THE INSTALLATION TYPE

For MacOS and Linux you can create a file named mcp.json inside the folder ~/.config/Code/User/ and add the content of the file.

Deploy in a cloud instance

You can deploy Demo Application with one click in Heroku, Microsoft Azure, or Google Cloud Platform:

License

This project is licensed with the MIT license.

Changelog

View Complete Changelog.

Community

Discord @genocs
Facebook Page @genocs
Youtube Channel @genocs

Support

Has this Project helped you learn something New? or Helped you at work? Here are a few ways by which you can support.

⭐ Leave a star!
🥇 Recommend this project to your colleagues.
🦸 Do consider endorsing me on LinkedIn for ASP.NET Core - Connect via LinkedIn
☕ If you want to support this project in the long run, consider buying me a coffee!

Code Contributors

This project exists thanks to all the people who contribute. Submit your PR and join the team!

Financial Contributors

Become a financial contributor and help me sustain the project. Support the Project!

Name		Name	Last commit message	Last commit date
Latest commit History 515 Commits
.azure/pipelines		.azure/pipelines
.cursor/rules		.cursor/rules
.devcontainer		.devcontainer
.github		.github
.vscode		.vscode
assets		assets
containers		containers
docs		docs
infrastructure/bicep		infrastructure/bicep
postman		postman
scripts		scripts
src		src
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.env		.env
.gitattributes		.gitattributes
.gitignore		.gitignore
.travis.yml		.travis.yml
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
Directory.Build.props		Directory.Build.props
Directory.Build.targets		Directory.Build.targets
LICENSE		LICENSE
Makefile		Makefile
NuGet.config		NuGet.config
README.md		README.md
api-workbench.rest		api-workbench.rest
dotnet.ruleset		dotnet.ruleset
genocs.sln		genocs.sln
global.json		global.json
icon.png		icon.png
launchSettings.json		launchSettings.json
local.env		local.env
stylecop.json		stylecop.json
testEnvironments.json		testEnvironments.json

Uh oh!

License

Genocs/genocs-library

Folders and files

Latest commit

History

Repository files navigation

.NET CLI

Genocs .NET library

The idea

Documentation

Table of Contents

Quick Start

Prerequisites

Setup

Features

Folders structure

Infrastructure

Kubernetes cluster

Aspire Integration

Support

Configuration

Demo Application

How to build Docker Demo images

Enterprise Application

Application Components

How to BUILD & RUN the application

Kubernetes

KubeCtl

Helm chart

makefile

MCP Servers

Deploy in a cloud instance

License

Changelog

Community

Support

Code Contributors

Financial Contributors

Acknowledgements

About

Topics

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 13

Sponsor this project

Uh oh!

Packages 0

Uh oh!

Contributors 5

Uh oh!

Languages

Packages