Command Pattern Best Practices in C#: Code Organization and Maintainability
You understand the command pattern. You've encapsulated a request as an object, wired up an invoker, and maybe even built a basic undo stack. But there's a wide gap between implementing the mechanics and building command architectures that hold up in production. Command pattern best practices in C# go beyond "create an ICommand interface" -- they address how to keep commands focused, how to validate before execution, how to handle undo and redo without corrupting state, and how to organize dozens of command classes so your project doesn't devolve into a maze of scattered files.
This guide covers the practical decisions that separate well-structured command code from the kind that makes future developers question everything. We'll walk through single responsibility per command, immutable command state, proper undo/redo with state snapshots, command validation, naming conventions, dependency injection registration, async command handling, testing strategies, and project organization. If you need a refresher on where the command pattern fits among other behavioral design patterns, start there and come back when you're ready to refine your approach.
Keep Each Command Single-Responsibility
The most important command pattern best practice in C# is ensuring that each command class does exactly one thing. A command that creates a user, sends a welcome email, and logs an audit entry is three responsibilities crammed into one object. When the email requirements change, you're editing a class that also handles user creation -- and that's how bugs spread.
Here's what this looks like when it goes wrong. Consider an ICommand interface for a document editor:
using System;
public interface ICommand
{
void Execute();
}
Now here's the anti-pattern -- a command doing too much:
using System;
using System.IO;
// Bad: Multiple responsibilities in one command
public class SaveAndNotifyCommand : ICommand
{
private readonly Document _document;
private readonly string _filePath;
private readonly IEmailService _emailService;
public SaveAndNotifyCommand(
Document document,
string filePath,
IEmailService emailService)
{
_document = document;
_filePath = filePath;
_emailService = emailService;
}
public void Execute()
{
// Save concern
File.WriteAllText(
_filePath,
_document.Content);
// Notification concern
_emailService.Send(
"[email protected]",
$"Document {_document.Title} saved.");
// Logging concern
Console.WriteLine(
$"[AUDIT] Document saved at " +
$"{DateTimeOffset.UtcNow}");
}
}
And the corrected version -- separate commands for each concern:
using System;
using System.IO;
// Good: Each command handles one concern
public sealed class SaveDocumentCommand : ICommand
{
private readonly Document _document;
private readonly string _filePath;
public SaveDocumentCommand(
Document document,
string filePath)
{
_document = document
?? throw new ArgumentNullException(
nameof(document));
_filePath = filePath
?? throw new ArgumentNullException(
nameof(filePath));
}
public void Execute()
{
File.WriteAllText(
_filePath,
_document.Content);
}
}
public sealed class NotifyDocumentSavedCommand : ICommand
{
private readonly Document _document;
private readonly IEmailService _emailService;
public NotifyDocumentSavedCommand(
Document document,
IEmailService emailService)
{
_document = document
?? throw new ArgumentNullException(
nameof(document));
_emailService = emailService
?? throw new ArgumentNullException(
nameof(emailService));
}
public void Execute()
{
_emailService.Send(
"[email protected]",
$"Document {_document.Title} saved.");
}
}
When each command is small and focused, you gain composability. Need to save without notifying? Use only the save command. Need to batch multiple operations into a sequence? Compose single-responsibility commands using the composite pattern to create macro commands. Each piece is independently testable and independently replaceable. This single-responsibility approach is the foundation that every other command pattern best practice builds on.
Make Command State Immutable
A command object represents a specific request with specific parameters. Once constructed, those parameters should not change. Mutable command state leads to subtle bugs -- if a command sits in a queue and something modifies its properties before execution, the command executes with data the caller never intended.
Here's the anti-pattern:
using System;
// Bad: Mutable state allows modification after creation
public class RenameDocumentCommand : ICommand
{
public Document Document { get; set; }
public string NewName { get; set; }
public void Execute()
{
Document.Title = NewName;
}
}
Nothing prevents someone from changing NewName between creating the command and executing it. The corrected version locks everything down:
using System;
// Good: Immutable state -- set once at construction
public sealed class RenameDocumentCommand : ICommand
{
private readonly Document _document;
private readonly string _newName;
public RenameDocumentCommand(
Document document,
string newName)
{
_document = document
?? throw new ArgumentNullException(
nameof(document));
_newName = newName
?? throw new ArgumentNullException(
nameof(newName));
}
public void Execute()
{
_document.Title = _newName;
}
}
By using readonly fields and requiring all data through the constructor, you guarantee that the command captures a snapshot of the caller's intent at the moment of creation. This is a command pattern best practice in C# that becomes critical when commands are queued, serialized, or replayed. Immutable commands are also inherently thread-safe -- no locking required when passing them between threads. If you're building a command pattern implementation that supports queuing or event sourcing, immutability isn't optional -- it's essential.
Implement Undo and Redo with State Snapshots
Undo support is one of the command pattern's signature features, but a naive implementation causes more problems than it solves. The most common mistake is storing only the "forward" action and trying to reverse-engineer the undo. Instead, capture a state snapshot before execution so the undo path is deterministic.
Define an undoable command interface:
using System;
public interface IUndoableCommand : ICommand
{
void Undo();
}
Here's the anti-pattern -- trying to undo without capturing previous state:
using System;
// Bad: No state snapshot -- undo behavior is guesswork
public class ChangeColorCommand : IUndoableCommand
{
private readonly Shape _shape;
private readonly string _newColor;
public ChangeColorCommand(
Shape shape,
string newColor)
{
_shape = shape;
_newColor = newColor;
}
public void Execute()
{
_shape.Color = _newColor;
}
public void Undo()
{
// What was the previous color?
// We don't know -- it's gone.
_shape.Color = "default";
}
}
And the correct approach -- snapshot the state before mutation:
using System;
// Good: Captures previous state for reliable undo
public sealed class ChangeColorCommand : IUndoableCommand
{
private readonly Shape _shape;
private readonly string _newColor;
private string _previousColor;
public ChangeColorCommand(
Shape shape,
string newColor)
{
_shape = shape
?? throw new ArgumentNullException(
nameof(shape));
_newColor = newColor
?? throw new ArgumentNullException(
nameof(newColor));
}
public void Execute()
{
_previousColor = _shape.Color;
_shape.Color = _newColor;
}
public void Undo()
{
_shape.Color = _previousColor;
}
}
The _previousColor field captures the exact state that existed before execution. Undo restores it precisely. For redo, simply call Execute() again -- the snapshot is still valid.
A command history manager ties this together:
using System;
using System.Collections.Generic;
public sealed class CommandHistory
{
private readonly Stack<IUndoableCommand> _undoStack = new();
private readonly Stack<IUndoableCommand> _redoStack = new();
public void ExecuteCommand(IUndoableCommand command)
{
command.Execute();
_undoStack.Push(command);
_redoStack.Clear();
}
public void Undo()
{
if (_undoStack.Count == 0)
{
return;
}
IUndoableCommand command = _undoStack.Pop();
command.Undo();
_redoStack.Push(command);
}
public void Redo()
{
if (_redoStack.Count == 0)
{
return;
}
IUndoableCommand command = _redoStack.Pop();
command.Execute();
_undoStack.Push(command);
}
}
Notice that _redoStack.Clear() is called after every new execution. This is a critical command pattern best practice in C# -- once the user performs a new action after undoing, the redo history becomes invalid and must be discarded. Skipping this step creates paradoxical states where redo replays commands that no longer make sense. Getting undo/redo right is one of the most rewarding aspects of the command pattern because it gives users confidence that every action is reversible.
Validate Commands Before Execution
Commands should be validated before they run, not during. Mixing validation logic inside Execute() means the command partially executes before discovering invalid state -- and now you need cleanup logic for a half-completed operation.
A clean approach introduces a separate validation step:
using System;
using System.Collections.Generic;
public interface IValidatableCommand : ICommand
{
IReadOnlyList<string> Validate();
}
Here's the anti-pattern -- validation buried inside execution:
using System;
// Bad: Validation mixed with execution
public class TransferFundsCommand : ICommand
{
private readonly Account _source;
private readonly Account _destination;
private readonly decimal _amount;
public TransferFundsCommand(
Account source,
Account destination,
decimal amount)
{
_source = source;
_destination = destination;
_amount = amount;
}
public void Execute()
{
if (_amount <= 0)
{
throw new InvalidOperationException(
"Amount must be positive.");
}
if (_source.Balance < _amount)
{
throw new InvalidOperationException(
"Insufficient funds.");
}
// Now we start mutating state...
_source.Balance -= _amount;
_destination.Balance += _amount;
}
}
And the corrected version:
using System;
using System.Collections.Generic;
// Good: Validation is separate from execution
public sealed class TransferFundsCommand
: IValidatableCommand
{
private readonly Account _source;
private readonly Account _destination;
private readonly decimal _amount;
public TransferFundsCommand(
Account source,
Account destination,
decimal amount)
{
_source = source
?? throw new ArgumentNullException(
nameof(source));
_destination = destination
?? throw new ArgumentNullException(
nameof(destination));
_amount = amount;
}
public IReadOnlyList<string> Validate()
{
List<string> errors = new();
if (_amount <= 0)
{
errors.Add("Amount must be positive.");
}
if (_source.Balance < _amount)
{
errors.Add("Insufficient funds.");
}
if (_source == _destination)
{
errors.Add(
"Source and destination cannot " +
"be the same account.");
}
return errors;
}
public void Execute()
{
_source.Balance -= _amount;
_destination.Balance += _amount;
}
}
The caller validates first, then executes only if validation passes. This keeps Execute() clean -- it does the work, nothing else. The separation also makes command pattern validation independently testable without worrying about side effects.
This is the same principle behind inversion of control -- separating concerns so each piece can evolve independently.
Follow Consistent Naming Conventions
Clear, predictable naming for command classes is a command pattern best practice in C# that pays off immediately when your project has dozens of commands. Every developer should be able to scan a folder and understand what each command does without opening the file.
The convention that works best is {Action}{Target}Command:
SaveDocumentCommand-- saves a documentTransferFundsCommand-- transfers money between accountsChangeColorCommand-- changes a shape's colorDeleteUserCommand-- removes a userResizeImageCommand-- resizes an image
This naming pattern puts the verb first, making it obvious what the command does. When browsing alphabetically, commands group by action -- all "Delete" commands together, all "Create" commands together.
Avoid vague names like DocumentHandler, UserAction, or ProcessManager. These tell you nothing about the specific operation. Similarly, avoid dropping the Command suffix -- SaveDocument could be a method, a service, or a DTO. The suffix Command communicates the design pattern being used and signals that this class encapsulates a discrete operation.
For undoable commands, don't add "Undoable" to the name. Whether a command supports undo is an implementation detail. The class name should describe what the command does, not what interfaces it implements.
Register Commands with Dependency Injection
When your commands have dependencies -- repositories, services, loggers -- you need a clean way to construct them. Using IServiceCollection to register command factories keeps construction logic centralized and testable.
Here's the anti-pattern -- constructing commands manually with new everywhere:
using System;
// Bad: Manual construction scattered across the codebase
public class OrderController
{
private readonly IOrderRepository _orders;
private readonly IEmailService _email;
private readonly ILogger _logger;
public void PlaceOrder(OrderDto dto)
{
var command = new PlaceOrderCommand(
_orders, _email, _logger, dto);
command.Execute();
}
}
And the corrected approach using a factory:
using System;
using Microsoft.Extensions.DependencyInjection;
// Good: Factory registered with DI
public interface ICommandFactory<TParam>
{
ICommand Create(TParam parameter);
}
public sealed class PlaceOrderCommandFactory
: ICommandFactory<OrderDto>
{
private readonly IOrderRepository _orders;
private readonly IEmailService _email;
public PlaceOrderCommandFactory(
IOrderRepository orders,
IEmailService email)
{
_orders = orders;
_email = email;
}
public ICommand Create(OrderDto parameter)
{
return new PlaceOrderCommand(
_orders, _email, parameter);
}
}
Register the factory in your composition root:
using Microsoft.Extensions.DependencyInjection;
var services = new ServiceCollection();
services.AddTransient<
ICommandFactory<OrderDto>,
PlaceOrderCommandFactory>();
Now controllers and handlers depend on ICommandFactory<OrderDto> instead of knowing how to build the command themselves. This follows the same inversion principle that makes the strategy pattern and decorator pattern so effective in well-structured applications.
Handle Async Commands Properly
Modern C# applications are heavily asynchronous. Network calls, database operations, and file I/O all benefit from async execution. Your command pattern abstraction should account for this without forcing synchronous commands into async wrappers.
Define a separate async command interface:
using System;
using System.Threading;
using System.Threading.Tasks;
public interface IAsyncCommand
{
Task ExecuteAsync(
CancellationToken cancellationToken = default);
}
Here's the anti-pattern -- wrapping sync commands in Task.Run:
using System;
using System.Threading.Tasks;
// Bad: Faking async by wrapping sync code
public class FakeAsyncCommand : IAsyncCommand
{
private readonly ICommand _syncCommand;
public FakeAsyncCommand(ICommand syncCommand)
{
_syncCommand = syncCommand;
}
public Task ExecuteAsync(
CancellationToken cancellationToken = default)
{
return Task.Run(
() => _syncCommand.Execute(),
cancellationToken);
}
}
And the corrected version -- a genuinely async command:
using System;
using System.Threading;
using System.Threading.Tasks;
// Good: Truly async operation
public sealed class SaveDocumentAsyncCommand
: IAsyncCommand
{
private readonly Document _document;
private readonly IDocumentRepository _repository;
public SaveDocumentAsyncCommand(
Document document,
IDocumentRepository repository)
{
_document = document
?? throw new ArgumentNullException(
nameof(document));
_repository = repository
?? throw new ArgumentNullException(
nameof(repository));
}
public async Task ExecuteAsync(
CancellationToken cancellationToken = default)
{
await _repository.SaveAsync(
_document,
cancellationToken);
}
}
Keep ICommand and IAsyncCommand as separate interfaces. Don't force every command to be async -- CPU-bound, in-memory operations don't benefit from async overhead. Let commands choose the interface that matches their actual execution model. This is a command pattern best practice in C# that prevents the "async all the way down for no reason" trap that plagues many command pattern implementations.
Always accept a CancellationToken on async commands. Commands may sit in queues for extended periods, and the ability to cancel them cleanly is essential for responsive applications.
Organize Commands in Your Project Structure
As your application accumulates commands, a deliberate folder structure prevents them from scattering across the codebase. This is one of those command pattern best practices in C# that feels unnecessary with five commands but becomes critical with fifty.
Group commands by the domain feature they belong to:
src/
Orders/
Commands/
PlaceOrderCommand.cs
CancelOrderCommand.cs
PlaceOrderCommandFactory.cs
IOrderRepository.cs
Order.cs
Documents/
Commands/
SaveDocumentCommand.cs
RenameDocumentCommand.cs
DeleteDocumentCommand.cs
IDocumentRepository.cs
Document.cs
Shared/
Commands/
ICommand.cs
IAsyncCommand.cs
IUndoableCommand.cs
IValidatableCommand.cs
CommandHistory.cs
This structure keeps related code together. When a developer needs to understand how order placement works, every relevant command is in Orders/Commands/. The shared abstractions live in Shared/Commands/ and are referenced everywhere.
The namespace mirrors the folder structure: MyApp.Orders.Commands. This makes IntelliSense helpful and using statements descriptive.
An alternative approach organizes by command type rather than by feature -- putting all commands in a single Commands/ folder. This works for small applications but breaks down quickly. When you have PlaceOrderCommand, CancelOrderCommand, SaveDocumentCommand, and DeleteUserCommand all in one flat folder, the grouping tells you nothing about the domain.
Pick feature-based organization and apply it consistently. Mixed approaches are worse than either alternative alone. Good project structure is one of those command pattern best practices that compounds in value over the lifetime of the project.
Test Command Classes Thoroughly
Testability is one of the command pattern's greatest strengths. Each command is a self-contained unit with explicit inputs and a clear action. This makes them ideal for focused, isolated tests.
Here's how to test commands effectively:
using System;
using System.Collections.Generic;
using Moq;
using Xunit;
public class TransferFundsCommandTests
{
[Fact]
public void Validate_NegativeAmount_ReturnsError()
{
// Arrange
var source = new Account { Balance = 100m };
var destination = new Account { Balance = 50m };
var command = new TransferFundsCommand(
source, destination, -10m);
// Act
IReadOnlyList<string> errors = command.Validate();
// Assert
Assert.Contains(
errors,
e => e.Contains("positive"));
}
[Fact]
public void Execute_ValidTransfer_UpdatesBalances()
{
// Arrange
var source = new Account { Balance = 100m };
var destination = new Account { Balance = 50m };
var command = new TransferFundsCommand(
source, destination, 30m);
// Act
command.Execute();
// Assert
Assert.Equal(70m, source.Balance);
Assert.Equal(80m, destination.Balance);
}
[Fact]
public void Validate_InsufficientFunds_ReturnsError()
{
// Arrange
var source = new Account { Balance = 10m };
var destination = new Account { Balance = 50m };
var command = new TransferFundsCommand(
source, destination, 100m);
// Act
IReadOnlyList<string> errors = command.Validate();
// Assert
Assert.Contains(
errors,
e => e.Contains("Insufficient"));
}
}
And for undoable commands, test the undo path explicitly:
using System;
using Xunit;
public class ChangeColorCommandTests
{
[Fact]
public void Undo_RestoresPreviousColor()
{
// Arrange
var shape = new Shape { Color = "Red" };
var command = new ChangeColorCommand(
shape, "Blue");
// Act
command.Execute();
command.Undo();
// Assert
Assert.Equal("Red", shape.Color);
}
[Fact]
public void Execute_ThenUndo_ThenRedo_AppliesNewColor()
{
// Arrange
var shape = new Shape { Color = "Red" };
var command = new ChangeColorCommand(
shape, "Blue");
// Act
command.Execute();
command.Undo();
command.Execute();
// Assert
Assert.Equal("Blue", shape.Color);
}
}
A few testing guidelines for command pattern best practices in C#:
- Test validation separately from execution. Validation tests should verify error messages without triggering side effects. Execution tests should assume valid input and verify the outcome.
- Test undo as a first-class behavior. Don't just test that undo "doesn't crash." Verify that it restores the exact previous state.
- Test command factories. Verify that the factory produces commands with the correct dependencies and parameters wired in.
- Use mocks for external dependencies. If a command interacts with a repository or service, mock that dependency so your test focuses on the command's logic, not the infrastructure. Following adapter pattern principles around interface boundaries makes this straightforward.
Frequently Asked Questions
How many responsibilities should a single command class have?
Exactly one. A command should represent a single, discrete operation. If you find a command doing two things -- like saving data and sending a notification -- split it into two commands. You can compose them using a macro command if they need to run together.
When should I use the command pattern instead of direct method calls?
Use the command pattern when you need undo/redo support, command queuing, command logging, or deferred execution. If you're just calling a method and don't need any of these capabilities, a direct method call is simpler and more appropriate. The pattern adds value when operations need to be treated as first-class objects.
How do I handle command failures during undo in a macro command?
If one command's undo fails inside a macro sequence, you should undo all previously undone commands in reverse order to restore consistency. This is essentially a compensation pattern. Log the failure, undo everything that was already undone back to the original state, and surface the error. Partial undo is worse than no undo at all.
Should command constructors throw exceptions for invalid parameters?
Yes -- for null checks and type validation, throw ArgumentNullException or ArgumentException in the constructor. This fails fast and prevents invalid commands from being created in the first place. Business rule validation belongs in a separate Validate() method because those rules may depend on runtime state that changes between construction and execution.
How do I choose between ICommand and IAsyncCommand for a new command?
Choose based on the operation's nature. If the command performs I/O -- database writes, HTTP calls, file operations -- use IAsyncCommand. If the command is purely in-memory and CPU-bound, use ICommand. Don't wrap synchronous code in Task.Run just to satisfy an async interface -- that wastes a thread pool thread without any benefit.
Can I combine the command pattern with other behavioral patterns?
Absolutely. Commands pair naturally with several patterns. Use the composite pattern to build macro commands that execute a sequence of sub-commands as a single unit. Use the strategy pattern to select which command to create based on runtime conditions. Use the decorator pattern to add cross-cutting concerns like logging or retry logic around command execution without modifying the commands themselves.
How do I organize commands when my application has hundreds of them?
Group commands by domain feature, not by pattern type. Put PlaceOrderCommand in Orders/Commands/, not in a flat Commands/ folder alongside every other command in the system. Keep shared abstractions like ICommand and CommandHistory in a Shared/Commands/ namespace. This feature-based organization scales because each domain area remains self-contained.
Wrapping Up Command Pattern Best Practices
Applying these command pattern best practices in C# will help you build command implementations that remain clean, testable, and maintainable as your application grows. The core themes are consistent: give each command a single responsibility, make command state immutable, capture state snapshots for reliable undo, validate before executing, name commands clearly, and organize them by domain feature.
The command pattern is at its best when you treat commands as small, self-contained operation objects rather than dumping grounds for business logic. Each command should be something you can test in isolation, queue for later, undo if needed, and understand at a glance from its name alone. When you centralize construction through factories and dependency injection, the entire team can work with commands without tracing through scattered construction logic.
Remember that best practices are guidelines shaped by production experience, not rigid rules. Start simple, add commands as discrete operations emerge, and refactor when patterns become clear. The goal isn't maximum abstraction -- it's a codebase where operations are explicit, reversible, and easy to reason about.