Command-Query Separation (CQS) - C# Examples

Overview

This repository demonstrates the Command-Query Separation (CQS) design principle through practical C# examples. CQS states that every method should either be a command that performs an action OR a query that returns data, but never both.

What is CQS?

Command-Query Separation is a design principle that states:

"Asking a question should not change the answer."

Core Concepts:

• Commands: Methods that change state but return nothing (void)
• Queries: Methods that return data without changing state

Repository Structure

Examples

1. Shopping Cart System - Complete example showing the difference
   • WithoutCQS/ - Violates CQS (mixed responsibilities)
   • WithCQS/ - Follows CQS (clear separation)

Benefits of CQS

✅ Predictability - Queries produce consistent results
✅ No Hidden Side Effects - Clear what each method does
✅ Easier Debugging - Inspect state safely
✅ Better Testability - Test commands and queries independently
✅ Thread Safety - Queries can run concurrently
✅ Caching Opportunities - Query results can be cached

The Principle

Commands:

• Change system state
• Return void (or simple success/failure)
• Examples: AddItem(), RemoveItem(), UpdateQuantity()

Queries:

• Return data
• Never modify state
• Examples: GetItem(), GetCount(), CalculateTotal()

Running the Examples

Prerequisites

• .NET 8.0 SDK or later
• Visual Studio 2022 / VS Code / Rider

Build and Run

# Navigate to either example
cd WithoutCQS
dotnet build
dotnet run

cd ../WithCQS
dotnet build
dotnet run

Key Takeaways

• Separate methods that change state from methods that return data
• Commands should return void
• Queries should have no side effects
• Clear naming makes intent obvious
• Thread safety and caching become easier

When to Apply CQS

✅ Business logic and domain models
✅ Public APIs (RESTful naturally aligns)
✅ Class interfaces
✅ Any code where testing matters

When to Be Pragmatic

Sometimes violating CQS is acceptable:

• Convenience methods (documented)
• Performance-critical code
• Builder/fluent interfaces
• Private helper methods

Related Principles

• CQRS (Command Query Responsibility Segregation) - Architectural pattern inspired by CQS
• SOLID Principles - Especially Single Responsibility
• YAGNI - Don't build features you don't need
• KISS - Keep it simple

Contributing

Feel free to submit issues or pull requests with improvements!

License

MIT License - Free to use for learning and commercial projects.

Author

Created as part of a series on software design principles.