SSW Vertical Slice Architecture Template

• 🤔 What is it?
• ✨ Features
• 🎉 Getting Started
• 🎓 Learn More
• 🚀 Publishing Template
• 🤝 Contributing

An enterprise ready solution template for Vertical Slice Architecture. This template is just one way to apply the Vertical Slice Architecture.

Read more on SSW Rules to Better Vertical Slice Architecture

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

  • 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 Vertical Slice Architecture fundamentals
  • The tests are automated so discovering the defects is fast

• Docker / Podman
• Dotnet 9

1. Install the SSW VSA template

   dotnet new install SSW.VerticalSliceArchitecture.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 Sprout
   cd Sprout

3. Create a new solution

   dotnet new ssw-vsa

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-vsa --name {{SolutionName}}

To speed up development there is a dotnet new template to create a full Vertical Slice:

• Creates a domain object in Common/Domain/*
• Adds domain configuration in Common/Persistence/*
• Creates Command & Query API endpoints in Features/*

1. Add a new Feature

   cd src/WebApi/
   dotnet new ssw-vsa-slice --feature Person --feature-plural People

--feature or -f where the value is the singular name of the feature. --feature-plural or -fp where the value is the plural name of the feature.

2. Configure this Feature This project uses strongly typed IDs, which require registration in the VogenEfCoreConverters class:

   // Register the newly created Entity ID here
   [EfCoreConverter<PersonId>]
   internal sealed partial class VogenEfCoreConverters;

3. Add a migration for the new Entity

   dotnet ef migrations add --project src/WebApi/WebApi.csproj --startup-project src/WebApi/WebApi.csproj --output-dir Common/Database/Migrations PersonTable 

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 https://localhost:7255/scalar/v1 in your browser to see it running ️🏃‍♂️

graph TD;
    subgraph ASP.NET Core Web App
        subgraph Slices
            A[Feature A]
            B[Feature B]
        end
        Slices --> |depends on| Common
        Host --> |depends on| Common
        Host --> |depends on| Slices
        ASPNETCore[ASP.NET Core] --> |uses| Host
    end

    Common[Common]

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

1. Update the version attribute in VerticalSliceArchitecture.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).

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