/SSW.CleanArchitecture

v2 of the Clean Architecture approach

Primary LanguageC#MIT LicenseMIT

SSW Banner

SSW Clean Architecture Template

SSW TV | YouTube

.NET Code Scanning Package contributions welcome ADRs

SSW.CleanArchitecture Repo Analytics

๐Ÿค” What is it?

This is a template for creating a new project using Clean Architecture, leveraging SSW Rules & SSW's over 30 years of experience developing software in the Microsoft space.

โœจ Features

  • โš–๏ธ EditorConfig - comes with the SSW.EditorConfig
  • ๐Ÿ“ฆ Slim - no authentication provider, no authorization & no UI framework
  • ๐ŸŒ Minimal Endpoints - because it's fast & simple. โšก
    • Extension methods to ensure consistent HTTP Verbs & Status Codes
  • ๐Ÿ”‘ Global Exception Handling - it's important to handle exceptions in a consistent way & protect sensitive information
    • Transforms exceptions into a consistent format following the RFC7231 memo
  • ๐Ÿ“ OpenAPI/Swagger - easily document your API
  • ๐Ÿ—„๏ธ Entity Framework Core - for data access
  • ๐Ÿงฉ Specification Pattern - abstract EF Core away from your business logic
  • ๐Ÿ”€ CQRS - for separation of concerns
  • ๐Ÿ“ฆ MediatR - for decoupling your application
  • ๐Ÿ“ฆ FluentValidation - for validating requests
  • ๐Ÿ“ฆ AutoMapper - for mapping between objects
  • ๐Ÿ†” Strongly Typed IDs - to combat primitive obsession
    • e.g. pass CustomerId type into methods instead of int, or Guid
    • Entity Framework can automatically convert the int, Guid, nvarchar(..) to strongly typed ID.
  • ๐Ÿ”จ dotnet new cli template - to get you started quickly
  • ๐Ÿ“ Directory.Build.Props
    • Consistent build configuration across all projects in the solution
      • e.g. Treating Warnings as Errors for Release builds
    • Custom per project
      • e.g. for all test projects we can ensure that the exact same versions of common packages are referenced
      • e.g. XUnit and NSubstitute packages for all test projects
  • ๐Ÿงช Testing
  • Architecture Tests
    • Using NetArchTest
    • Know that the team is following the same Clean Architecture fundamentals
    • The tests are automated so discovering the defects is fast

๐Ÿš€ Publishing Template

Template will be published to NuGet.org when changes are made to CleanArchitecture.nuspec on the main branch.

Process

  1. Update the version attribute in CleanArchitecture.nuspec
  2. Merge your PR
  3. package GitHub Action will run and publish the new version to NuGet.org
  4. Create a GitHub release to document the changes

๐ŸŽ‰ Getting Started

Installing the Template

  1. Install the SSW CA template
dotnet new install SSW.CleanArchitecture.Template

NOTE: The template only needs to be installed once. Running this command again will update your version of the template.

  1. Create a new directory
mkdir Northwind365
cd Northwind365
  1. Create a new solution
dotnet new ssw-ca

NOTE: name is optional; if you don't specify it, the directory name will be used as the solution name and project namespaces.

Alternatively, you can specify the name and output directory as follows:

dotnet new ssw-ca --name {{SolutionName}} --output .\

Adding a Feature

  1. Create a query
cd src/Application/Features
mkdir {{FeatureName}}
cd {{FeatureName}}
dotnet new ssw-ca-query --name {{QueryName}} --entityName {{Entity}} --slnName {{SolutionName}}
  1. Create a command
cd src/Application/Features
mkdir {{FeatureName}}
cd {{FeatureName}}
dotnet new ssw-ca-command --name {{CommandName}} --entityName {{Entity}} --slnName {{SolutionName}}

Running the Solution

  1. Start dockerized SQL Server
docker compose up
  1. Run the solution
dotnet run

NOTE: The first time you run the solution, it may take a while to download the docker images, create the DB, and seed the data.