Upgrading from v10.x to v11.x#

If you started your project with version 10.0.1 (or similar) of the template and want to incorporate the architectural upgrades of version 11.0.0, follow this guide.

The “Diff” Strategy#

Since this template serves as a starting point, the most reliable way to upgrade an existing project is to perform a differential comparison:

  1. Generate a brand new solution using the v11 template (e.g., dotnet new clean-arch -o Your.ProjectName).
  2. Use a diff tool (like Beyond Compare, WinMerge, or git diff) to compare the newly generated solution against the original v10 vanilla template you started with (or your current codebase).
  3. Manually apply the structural or package changes to your existing project.

Key Changes in v11.x#

Several dependencies and implementation details were altered in this release. The most significant changes include:

1. MediatR Replacement#

One of the most noticeable changes in recent versions is the removal of the MediatR library for handling commands and queries inside the UseCases project, favoring alternative implementations or source generators (due to licensing/commercial changes).

  • Action Required: Review how ICommand, IQuery, and their respective handlers (ICommandHandler, IQueryHandler) are defined in the new template. You will need to update your existing Use Case handlers to align with the new library’s interfaces and base types.

2. FastEndpoints API Layer#

Continue leveraging FastEndpoints for the API layer (the REPR pattern).

  • Action Required: Check the /src/Clean.Architecture.Web/Endpoints folder in the new template to see if any base class signatures (Endpoint<TRequest, TResponse>) or FluentValidation extensions have shifted.

3. Template Configuration & Packages#

Compare the Directory.Packages.props file to see the newly pinned versions for Entity Framework Core, Serilog, FastEndpoints, and testing packages.

  • Action Required: Update your Central Package Management file accordingly to resolve any vulnerability or compatibility warnings.
Backward Migration Guides