Repository files navigation

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 onSSW 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

• ⚡ FastEndpoints - developer friendly alternative to Minimal APIs.

  • Strongly-typed requests and responses
  • Automatic validation with FluentValidation
  • Support for commands and events

• 📝 OpenAPI/Swagger - easily document your API

  • as perssw.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 theRFC7231 memo

• 🗄️ Entity Framework Core - for data access

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

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

• 🔀 REPR (Request-Endpoint-Response) Pattern - for structured endpoints

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

• 📦 FluentValidation - for validating requests

  • as perssw.com.au/rules/use-fluent-validation/

• 🆔 Strongly Typed IDs - to combat primitive obsession

  • e.g. passCustomerId type into methods instead ofint, orGuid
  • 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 theSSW.EditorConfig

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

• 🧪 Testing

  • as perssw.com.au/rules/rules-to-better-testing/
  • Simpler Unit Tests for Application
    • No Entity Framework mocking required thanks toSpecifications
    • as perssw.com.au/rules/rules-to-better-unit-tests/
  • Better Integration Tests
    • UsingRespawn andTestContainers
    • 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

  • UsingNetArchTest
  • 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 Sproutcd 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 thename andoutput directory as follows:

dotnet new ssw-vsa --name {{SolutionName}}

1. Change directory
   Windows:

   cdtools\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. Openhttps://localhost:7255/swagger in your browser to see it running ️🏃‍♂️

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

• Creates a domain object inCommon/Domain/*
• Adds domain configuration inCommon/Persistence/*
• Creates Command & Query API endpoints inFeatures/*

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 thesingular name of the feature.--feature-plural or-fp where the value is theplural name of the feature.

2. Configure this FeatureThis project usesstrongly typed IDs, which require registration in theVogenEfCoreConverters class:

   // Register the newly created Entity ID here[EfCoreConverter<PersonId>]internalsealedpartialclassVogenEfCoreConverters;

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

Due to .NET Aspire orchestrating the application startup and migration runner, EF migrations need to be handled a little differently to normal.

Adding new migrations is still the same old command you would expect, but with a couple of specific parameters to account for the separation of concerns. This can be performed via native dotnet tooling or through the Aspire CLI:

1. Run either of following commands from the root of the solution.

dotnet ef migrations add YourMigrationName --project ./src/Infrastructure/Infrastructure.csproj --startup-project ./src/WebApi/WebApi.csproj --output-dir ./Persistence/Migrations

aspireexec --resource api -- dotnet ef migrations add YourMigrationName --project ../Infrastructure/Infrastructure.csproj --output-dir ./Persistence/Migrations

.NET Aspire handles this for you - just start the project!

This is where things need to be done a little differently and requires the Aspire CLI.

1. Enable theexec function:

aspire configset features.execCommandEnabledtrue

2. Pass the EF migration shell command through Aspire from the root of the solution:

aspireexec --resource api -- dotnet ef migrations remove --project ..\Infrastructure --force

The template can be deployed to Azure viatheAzure Developer CLI (AZD).This will setup the following:

• Azure App Services: API + MigrationService
• Azure SQL Server + Database: Data storage
• Application Insights + Log Analytics: For monitoring and logging
• Managed Identities: For secure access to Azure resources
• Azure Container Registry: For storing Docker images

1. Authenticate with Azure

   azd auth login

2. Initialize AZD for the project

   azd init

3. Update environment variables

   azd envset ASPNETCORE_ENVIRONMENT Development

4. Deploy to Azure

   azd up

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 toVerticalSliceArchitecture.nuspec on themain branch.

1. Update theversion attribute inVerticalSliceArchitecture.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 formatYYYY.M.D (e.g.2024.2.12).

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