CommandQuery

Content

• Introduction
• Packages
  • CommandQuery ⚙️
  • CommandQuery.AspNetCore 🌐
  • CommandQuery.AWSLambda ⚡
  • CommandQuery.AzureFunctions ⚡
  • CommandQuery.GoogleCloudFunctions ⚡
  • CommandQuery.Client 🧰
  • CommandQuery.AspNet.WebApi 🌐
• Upgrading
• Acknowledgements

Introduction

Command Query Separation (CQS) for .NET and C#

• Build services that separate the responsibility of commands and queries
• Focus on implementing the handlers for commands and queries
• Create APIs with less boilerplate code

Available for:

🌐 ASP.NET Core
⚡ AWS Lambda
⚡ Azure Functions
⚡ Google Cloud Functions
🌐 ASP.NET Web API 2

Command Query Separation?

Queries: Return a result and do not change the observable state of the system (are free of side effects).

Commands: Change the state of a system but do not return a value.

— Martin Fowler

In other words:

• Commands
  • Writes (create, update, delete) data
• Queries
  • Reads and returns data

The traditional approach that commands do not return a value is a bit inconvenient.

CommandQuery has a pragmatic take and supports both commands with and without result 👍

Packages

CommandQuery ⚙️

Command Query Separation for .NET

• 📃 README: CommandQuery.md
• 💁 Samples:
  • CommandQuery.Sample.Contracts
  • CommandQuery.Sample.Handlers

CommandQuery.AspNetCore 🌐

Command Query Separation for ASP.NET Core

• 📃 README: CommandQuery.AspNetCore.md
• 💁 Samples:
  • CommandQuery.Sample.AspNetCore.V6
  • CommandQuery.Sample.AspNetCore.V6.Tests

CommandQuery.AWSLambda ⚡

Command Query Separation for AWS Lambda

• 📃 README: CommandQuery.AWSLambda.md
• 💁 Samples:
  • CommandQuery.Sample.AWSLambda
  • CommandQuery.Sample.AWSLambda.Tests

CommandQuery.AzureFunctions ⚡

Command Query Separation for Azure Functions

• 📃 README: CommandQuery.AzureFunctions.md
• 💁 Samples:
  • CommandQuery.Sample.AzureFunctions.V6
  • CommandQuery.Sample.AzureFunctions.V6.Tests

CommandQuery.GoogleCloudFunctions ⚡

Command Query Separation for Google Cloud Functions

• 📃 README: CommandQuery.GoogleCloudFunctions.md
• 💁 Samples:
  • CommandQuery.Sample.GoogleCloudFunctions
  • CommandQuery.Sample.GoogleCloudFunctions.Tests

CommandQuery.Client 🧰

Clients for CommandQuery APIs

• 📃 README: CommandQuery.Client.md
• 💁 Samples:
  • CommandQuery.Sample.Client

CommandQuery.AspNet.WebApi 🌐

Command Query Separation for ASP.NET Web API 2

⛔ This package is no longer maintained and new versions will not be published

• 📃 README: CommandQuery.AspNet.WebApi.md
• 💁 Samples:
  • CommandQuery.Sample.AspNet.WebApi
  • CommandQuery.Sample.AspNet.WebApi.Tests

Upgrading

⬆️ Upgrading from version 1.0.0 to 2.0.0

Upgrade command/query handlers:

• Upgrade the project target framework from net461 to netstandard2.0 or greater
• Add a CancellationToken parameter to the HandleAsync methods in classes that implement ICommandHandler<TCommand>, ICommandHandler<TCommand, TResult> and IQueryHandler<TQuery, TResult>

Upgrade AspNet.WebApi:

• Migrate from CommandQuery.AspNet.WebApi to CommandQuery.AspNetCore

Upgrade AspNetCore:

• Consider to upgrade the project target framework to netcoreapp3.1 or net5.0
• Consider to use the extension methods AddCommandControllers and AddQueryControllers in Startup.cs

Upgrade AWSLambda:

• Upgrade the project target framework to netcoreapp3.1
• Change the method invocation on CommandFunction and QueryFunction from Handle to HandleAsync
• Change the argument on HandleAsync methods from ILambdaContext to ILambdaLogger
• Consider to use the extension methods AddCommandFunction and AddQueryFunction on IServiceCollection
• Consider to use the JsonSerializerOptions constructor argument in CommandFunction and QueryFunction to configure JSON serialization/deserialization

Upgrade AzureFunctions:

• Upgrade the project target framework to netcoreapp3.1 or net5.0
• Change the method invocation on CommandFunction and QueryFunction from Handle to HandleAsync
• Consider to use the extension methods AddCommandControllers and AddQueryControllers in Startup.cs/Program.cs
• Consider to use the CancellationToken argument on HandleAsync methods in netcoreapp3.1 projects
• Consider to use the JsonSerializerSettings/JsonSerializerOptions constructor argument in CommandFunction and QueryFunction to configure JSON serialization/deserialization

Upgrade Client:

• Change the method invocation on CommandClient and QueryClient from Post to PostAsync and from Get to GetAsync
• Consider to use the AddHttpClient extension method on IServiceCollection to create the CommandClient and QueryClient (see sample)
• Consider to use the CancellationToken argument to methods in CommandClient and QueryClient

Validation:

• Consider to use the AssertConfigurationIsValid method on CommandProcessor and QueryProcessor to validate handler and type configuration

Acknowledgements

Inspired by Steven van Deursen blog posts:

• Meanwhile... on the command side of my architecture
• Meanwhile... on the query side of my architecture