Skip to content

Open-source eCommerce platform for C# and ASP.NET Core 10 with MongoDB. Build multi-store shops and multi-vendor marketplaces with B2B/B2C, REST API, plugins, Vue 3 and Docker.

5.5 KB
Raw Blame

Best Practice: C# / .NET Idioms

Patterns found across the GrandNode codebase. Covers C# language features and .NET conventions used here.


Immutable Input Types — Records for Validators

Use positional records as input to FluentValidation validators. Records are immutable and their equality is structural:

public record ShoppingCartStandardValidatorRecord(
    Customer Customer,
    Product Product,
    ShoppingCartItem ShoppingCartItem);

public class ShoppingCartStandardValidator : AbstractValidator<ShoppingCartStandardValidatorRecord>
{ ... }

Guard Clauses — ArgumentNullException

Use the built-in static helpers at the top of service methods. Do not write if (x == null) throw new ArgumentNullException(...) manually:

public async Task SaveDeliveryDate(DeliveryDate deliveryDate)
{
    ArgumentNullException.ThrowIfNull(deliveryDate);
    // ...
}

public void Initialize(string keyId, string secretKey, string bucket)
{
    ArgumentNullException.ThrowIfNullOrEmpty(keyId);
    ArgumentNullException.ThrowIfNullOrEmpty(secretKey);
    ArgumentNullException.ThrowIfNullOrEmpty(bucket);
}

Result Objects Instead of Exceptions for Expected Failures

For operations where failure is a valid business outcome, use a result object rather than throwing exceptions:

public class PlaceOrderResult
{
    public bool Success => Errors.Count == 0;
    public IList<string> Errors { get; set; } = new List<string>();
    public Order PlacedOrder { get; set; }

    public void AddError(string error) => Errors.Add(error);
}

Exceptions are for unexpected, unrecoverable conditions. Validation failures, business rule violations, and "entity not found" are expected — return a result object.


Pattern Matching

Use switch with when guards rather than nested if/else:

switch (cartItem.ShoppingCartTypeId)
{
    case ShoppingCartType.ShoppingCart when product.DisableBuyButton:
        context.AddFailure(translationService.GetResource("ShoppingCart.BuyingDisabled"));
        break;
    case ShoppingCartType.Wishlist when product.DisableWishlistButton:
        context.AddFailure(translationService.GetResource("ShoppingCart.WishlistDisabled"));
        break;
}

Nullable Reference Types

The project has nullable reference types enabled. Follow these conventions:

  • string — the property/parameter is never null; calling code must not pass null.
  • string? — explicitly nullable; caller or callee handles null.
  • Do not suppress warnings with ! unless you are certain the value cannot be null at that point.

Configuration Binding

GrandNode uses direct Bind rather than IOptions<T>:

var dbConfig = new DatabaseConfig();
configuration.GetSection("Database").Bind(dbConfig);

Do not introduce IOptions<T>, IOptionsMonitor<T>, or IOptionsSnapshot<T> — they are not used in this codebase and would be inconsistent.


LINQ Expression Trees in Predicates

Repository methods accept Expression<Func<T, bool>>, not strings. Always use typed lambda predicates:

// correct — type-safe, translates to a MongoDB query
var entity = await _repository.GetOneAsync(x => x.ExternalId == externalId);

// wrong — string-based, no compile-time safety
var entity = await collection.Find("{externalId: '" + externalId + "'}").FirstOrDefaultAsync();

Naming Conventions

Concept Convention Example
Private fields _camelCase _orderRepository
Constants UPPER_SNAKE_CASE CacheKey.PRODUCTS_BY_ID
Async methods Async suffix GetByIdAsync
Event handlers EntityDeletedEventHandler ProductDeletedEventHandler
Command *Command PlaceOrderCommand
Query *Query GetSuggestedProductsQuery
Validator input record *ValidatorRecord ShoppingCartStandardValidatorRecord

using Declaration for Disposables

Use the modern using declaration instead of a try/finally block with Dispose. The variable is disposed at the end of the enclosing scope:

// correct — disposed when method exits
await using var response = await httpClient.GetStreamAsync(url);

// also correct for sync disposables
using var stream = File.OpenRead(path);

// old style — still valid but more verbose
using (var stream = File.OpenRead(path))
{
    // ...
}

The await using form is required for IAsyncDisposable (e.g., async streams).

var Usage Conventions

Use var when the type is obvious from the right-hand side (constructor, cast, literal). Don't use it when the type is only readable from a method name:

// clear — type is obvious
var product = new Product();
var products = await _productRepository.GetByIdAsync(id);

// prefer explicit — type is not obvious from method name alone
IList<Product> products = _catalogService.GetFeaturedProducts();

Anti-Patterns

Anti-pattern Correct
if (x == null) throw new ArgumentNullException(nameof(x)) ArgumentNullException.ThrowIfNull(x)
Throwing Exception for a business rule violation Return a result object with .AddError(...)
IOptions<T> for configuration configuration.GetSection(...).Bind(config)
String-based MongoDB queries LINQ expression predicates
null! suppression without a documented reason Remove the null, or handle it
try/finally { Dispose() } using var x = ... or await using var x = ...
new HttpClient() in a service Inject IHttpClientFactory, call CreateClient()