README.md

SSW Clean Architecture Template

• SSW Clean Architecture Template
  • 🤔 What is it?
  • ✨ Features
  • 🚀 Publishing Template
    • Process
  • 🎉 Getting Started

🤔 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

• 🔨 dotnet new cli template - to get you started quickly

• 🚀 Aspire

  • Dashboard
  • Resource orchestration
  • Observability
  • Simple dev setup - automatic provisioning of database server, schema, and data

• 🎯 Domain Driven Design Patterns

  • Super Hero Domain
  • AggregateRoot
  • Entity
  • ValueObject
  • DomainEvent

• 🌐 Minimal Endpoints - because it's fast & simple. ⚡

  • Extension methods to ensure consistent HTTP Verbs & Status Codes

• 📝 OpenAPI/Scalar - easily document your API

  • as per ssw.com.au/rules/do-you-document-your-webapi/

• 🔑 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

• 🗄️ Entity Framework Core - for data access

  • Comes with Migrations & Data Seeding
  • as per ssw.com.au/rules/rules-to-better-entity-framework/

• 🧩 Specification Pattern - abstract EF Core away from your business logic

• 🔀 CQRS - for separation of concerns

  • as per ssw.com.au/rules/keep-business-logic-out-of-the-presentation-layer/

• 📦 MediatR - for decoupling your application

• 📦 ErrorOr - fluent result pattern (instead of exceptions)

• 📦 FluentValidation - for validating requests

  • as per ssw.com.au/rules/use-fluent-validation/

• 🆔 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.

• 📁 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

• ⚖️ EditorConfig - comes with the SSW.EditorConfig

  • Maintain consistent coding styles for individual developers or teams of developers working on the same project using different IDEs
  • as per ssw.com.au/rules/consistent-code-style/

• 🧪 Testing

  • as per ssw.com.au/rules/rules-to-better-testing/
  • Simpler Unit Tests for Application
    • No Entity Framework mocking required thanks to Specifications
    • as per ssw.com.au/rules/rules-to-better-unit-tests/
  • Better Integration Tests
    • Using Respawn and TestContainers
    • Integration Tests at Unit Test speed
    • Test Commands and Queries against a Real database
    • No Entity Framework mocking required
    • No need for In-memory database provider

• 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

🎉 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.

2. Create a new directory

mkdir Northwind365
cd Northwind365

3. 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}}

2. 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. Change directory

   Windows:

   cd tools\AppHost\

   Mac/Linux:

   cd tools/AppHost/

2. 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.

4. Open http://localhost:5024/swagger/index.html in your browser to see it running ️🏃‍♂️

🚀 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

NOTE: We are now using CalVer for versioning. The version number should be in the format YYYY.M.D (e.g. 2024.2.12).

🎓 Learn More

Training

If you're interested in learning more about Clean Architecture SSW offers two events:

• SSW 1-day Clean Architecture Superpowers Tour
• SSW 2-day Clean Architecture Workshop

Learning Resources

You're interested learning more about Clean Architecture, please see this excellent video by Matt Goldman:

• Clean Architecture with ASP.NET Core and MAUI

Alternatively, SSW has many great rules about Clean Architecture:

• SSW Rules - Clean Architecture

You can also find a collection of commumity projects built on Clean Architecture here:

• Awesome Clean Architecture

🤝 Contributing

Contributions, issues and feature requests are welcome! See Contributing for more information.