SGuard.DataAnnotations 0.2.0

SGuard.DataAnnotations

SGuard.DataAnnotations provides localized and extensible DataAnnotations support for .NET, including:

• Localizable validation attributes (with robust fallback and custom error handling)
• Collection, conditional, and property comparison validators are not found in standard DataAnnotations
• Guard pattern (Is.* for boolean return, ThrowIf.* for exception-throwing) for model validation
• Seamless integration with DataAnnotations and SGuard's fail-fast/callback philosophy
• Well-tested and extensible for real-world application scenarios

Note: For fluent validation/guard support, see the upcoming SGuard.FluentValidation package.

Important: If you want to implement custom callback, fail-fast, or chainable guard logic, you should also review the SGuard core project, which provides advanced guard and callback APIs used by this library.

Table of Contents

• Installation
• Features
• Supported Languages
• Supported Attributes
  • String & Common Validators
  • Collection Validators
  • Conditional Validators
  • Comparison Validators
• Guard Pattern API
  • Is.* Methods
  • ThrowIf.* Methods
• Localization & Fallback
• Extending SGuard.DataAnnotations
• Minimal API Example (Real World)
• Advanced Topics
  • Error Handling
• FAQ / Tips
• Contributing
• License

Installation

Install via NuGet:

dotnet add package SGuard.DataAnnotations

Requires .NET 8, 9 or 10, and brings in SGuard 3.0 or later. For .NET 6 and 7, use version 0.1.1.

Features

• Localized error messages via resource files (.resx), with fallback to default or custom messages.
• Advanced collection and conditional validation (min/max count, required-if, required collection, collection element validation, etc.).
• Comparison attributes for property-to-property or value-to-value checks (greater than, less than, between, compare, etc.).
• Full DataAnnotations compatibility—use SGuard attributes anywhere a standard attribute is accepted.
• Guard pattern API (Is/ThrowIf) for easy imperative validation and exception/callback handling.

Supported Languages

SGuard.DataAnnotations ships with built-in resource support for the following languages:

Note:

• If the current UI culture is not found, SGuard will fallback to English or to the fallback message if provided.
• You can add your own resource files to support additional languages.
• How to add your own language?

Supported Attributes

String & Common Validators

Collection Validators

Details:

• SGuardCollectionItemsMatchAttribute can take multiple validators and will apply them to each item.
• AggregateAllErrors (default: false): If true, collects all errors; if false, returns on first failure.
• MaxErrors (default: 10): with AggregateAllErrors, validation stops after this many errors, so a large collection doesn't produce a message for every item.
• Each validator type must be a non-abstract ValidationAttribute with a public parameterless constructor; other types throw ArgumentException.
• Supported on any IEnumerable (e.g., List<T>, arrays, custom collections).
• The collection attributes (SGuardRequiredCollection, SGuardMinCount, SGuardMaxCount, SGuardCollectionItemsMatch) throw InvalidOperationException for an IQueryable, because enumerating it would run the query. Validate a materialized collection (for example ToList()) instead.

Conditional Validators

Comparison Validators

Supported types: int, double, decimal, DateTime, string, etc. (anything implementing IComparable)

Guard Pattern API

SGuard.DataAnnotations provides two imperative APIs for runtime validation, following the SGuard pattern.

Is.* Methods

• Purpose: Return bool for validation checks. An invalid model returns false; only an attribute that is declared wrong throws (see Error Handling).

• Callback: Optional SGuardCallback invoked with GuardOutcome.Success/Failure.
  For advanced callback usage, see the SGuard project documentation.

• Example:

  if (Is.DataAnnotationsValid(model))
  {
      // model is valid
  }
  

• With callback:

  bool valid = Is.DataAnnotationsValid(model, callback: outcome =>
  {
      if (outcome == GuardOutcome.Failure)
          Console.WriteLine("Validation failed!");
  });
  

• Get all validation errors:

  bool valid = Is.DataAnnotationsValid(model, out var results);
  foreach (var err in results)
      Console.WriteLine($"{string.Join(", ", err.MemberNames)}: {err.ErrorMessage}");
  

ThrowIf.* Methods

• Purpose: Throw exception if validation fails.

• Callback: Invoked before throw (GuardOutcome.Failure) or on pass (GuardOutcome.Success).

• Example:

  ThrowIf.DataAnnotationsInValid(model);
  // Throws DataAnnotationsException if model is invalid.
  

• Custom exception:

  ThrowIf.DataAnnotationsInValid<ArgumentException>(model, new ArgumentException("Custom error!"));
  

• Custom exception from a factory (the factory runs only when validation fails):

  ThrowIf.DataAnnotationsInValid(model, () => new ArgumentException("Custom error!"));
  

  The overload that takes constructor arguments (new object[] { "Custom error!" }) is obsolete (SGUARDDA001): it creates the exception with reflection, which the compiler can't check.

Exception Details

• Throws DataAnnotationsException by default, which contains all validation errors.
• Extract errors (see also SGuard.DataAnnotations.Extensions):

  catch (DataAnnotationsException ex)
  {
      if (ex.TryGetValidationErrors(out var errors))
      {
          foreach (var err in errors)
              Console.WriteLine($"{string.Join(", ", err.Members)}: {err.Message}");
      }
  }
  

Localization & Fallback

• All SGuard attributes support:
  • ErrorMessageResourceType and ErrorMessageResourceName (standard .NET resource workflow)
  • FallbackResourceName: Used if the main resource key is missing.
  • FallbackMessage: Used if both resource keys are missing.
• Culture: Error messages are localized to the current UICulture.
• Example:

  [SGuardMinLength(3, typeof(Resources.SGuardDataAnnotations), "Username_MinLength", 
      FallbackResourceName = "Common_MinLength", FallbackMessage = "Min length required.")]
  public string Username { get; set; }
  

How to add a custom language?

1. Copy SGuardDataAnnotations.resx and rename to e.g. SGuardDataAnnotations.es.resx for Spanish.
2. Translate all keys/values.
3. Rebuild and set your thread/UI culture accordingly.

Extending SGuard.DataAnnotations

Want to add your own fully localized validation attribute?
Inherit from SGuardValidationAttributeBase and implement IsValid:

public class MyCustomLocalizedAttribute : SGuardValidationAttributeBase
{
    public MyCustomLocalizedAttribute(Type resourceType, string resourceName)
        : base(resourceType, resourceName) {}

    protected override ValidationResult? IsValid(object? value, ValidationContext validationContext)
    {
        // Your logic here
        if (value == null) 
            return new ValidationResult(FormatErrorMessage(validationContext.DisplayName));
        return ValidationResult.Success;
    }
}

Minimal API Example (Real World)

Here's how you use SGuard.DataAnnotations in an ASP.NET Core Minimal API:

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Http;
using SGuard.DataAnnotations;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapPost("/register", (UserRegistration model) =>
{
    if (!Is.DataAnnotationsValid(model, out var errors))
        return Results.BadRequest(errors.Select(e => new { e.MemberNames, e.ErrorMessage }));

    // If valid, continue
    return Results.Ok("Registration successful!");
});

app.Run();

public class UserRegistration
{
    [SGuardRequired(typeof(Resources.SGuardDataAnnotations), "Username_Required")]
    [SGuardMinLength(3, typeof(Resources.SGuardDataAnnotations), "Username_MinLength")]
    [SGuardMaxLength(20, typeof(Resources.SGuardDataAnnotations), "Username_MaxLength")]
    public string Username { get; set; }

    [SGuardRequired(typeof(Resources.SGuardDataAnnotations), "Email_Required")]
    [SGuardEmailAddress(typeof(Resources.SGuardDataAnnotations), "Email_InvalidFormat")]
    public string Email { get; set; }

    [SGuardRequired(typeof(Resources.SGuardDataAnnotations), "Password_Required")]
    [SGuardStringLength(100, typeof(Resources.SGuardDataAnnotations), "Password_MaxLength")]
    public string Password { get; set; }

    [SGuardCompare("Password", typeof(Resources.SGuardDataAnnotations), "Password_Mismatch")]
    public string ConfirmPassword { get; set; }

    [SGuardRequiredCollection(typeof(Resources.SGuardDataAnnotations), "Profile_Phone_Required")]
    [SGuardCollectionItemsMatch(typeof(SGuardPhoneAttribute), typeof(Resources.SGuardDataAnnotations), "Profile_Phone_Invalid", AggregateAllErrors = true)]
    public List<string> PhoneNumbers { get; set; }
}

Advanced Topics

Error Handling

• Guard methods: Return bool or throw, never both.
• Attributes: Return a ValidationResult for invalid values. They throw InvalidOperationException only when the attribute itself is declared wrong, for example when SGuardCompare, SGuardGreaterThan, SGuardLessThan, SGuardBetween or SGuardRequiredIf names a property that the model doesn't have. That keeps property and type names in your logs instead of in the validation messages that clients see.
• All exceptions: Contain full error detail, member names, and support for extraction/extension.
• For advanced fail-fast, callback, or custom guard usage:
  See SGuard project documentation.

FAQ / Tips

Q: Can I use SGuard attributes in ASP.NET Core, Blazor, WinForms, etc.?
A: Yes, SGuard attributes implement the standard DataAnnotations contract.

Q: What happens if a resource key is missing?
A: The attribute will use FallbackResourceName if provided, otherwise FallbackMessage, otherwise [ResourceKey].

Q: How do I validate a collection’s items?
A: Use [SGuardCollectionItemsMatch(...)]. See Collection Validators.

Q: Can I chain SGuard and standard DataAnnotations attributes?
A: Yes, you can stack any combination on your model.

Q: Will SGuard.DataAnnotations work with FluentValidation?
A: Yes, as long as you use DataAnnotations integration. For a full fluent API, see the upcoming SGuard.FluentValidation package.

Q: I get "ThrowIf is an ambiguous reference" (CS0104).
A: SGuard and SGuard.DataAnnotations both have ThrowIf and Is classes, so a file that imports both namespaces has to say which one it means. Qualify the call or add an alias:

using SGuard;
using DataAnnotationsGuard = SGuard.DataAnnotations.ThrowIf;

ThrowIf.NullOrEmpty(model.Name);                  // SGuard
DataAnnotationsGuard.DataAnnotationsInValid(model); // SGuard.DataAnnotations

Q: How do I quickly test everything?
A:

1. Run all tests (requires .NET SDK):

   dotnet test
   

2. For a quick validation in your app, call:

   if (!Is.DataAnnotationsValid(model, out var results))
       // handle errors, see 'results'
   

Contributing

Pull requests, issues, and suggestions are very welcome!
See CONTRIBUTING.md for guidelines.

License

MIT License. See LICENSE.

See Also

• SGuard (core)