Nabs.Launchpad.Core.Dtos 10.0.214

Nabs Launchpad Core DTOs Library

The Nabs Launchpad Core DTOs library provides foundational Data Transfer Object (DTO) interfaces and transitive dependency references for building consistent data models across the application. This library serves as a base package that other projects can reference to access common MVVM, validation, and localization capabilities.

Key Features

• Standardized List Item Interface: Common interface for list/dropdown items across the application
• MVVM Support: Includes CommunityToolkit.Mvvm for observable objects, properties, and commands
• Validation Framework: FluentValidation integration for declarative validation rules
• Localization Ready: Microsoft.Extensions.Localization support for multi-language applications
• Lightweight Foundation: Minimal overhead with maximum flexibility

Core Components

IListItem

The foundational interface for list items used in dropdowns, selection lists, and other UI components requiring ID/display value pairs.

Usage Examples

Implementing IListItem

// Simple list item implementation
public class CategoryListItem : IListItem
{
    public string Id { get; init; } = default!;
    public string DisplayValue { get; init; } = default!;
    public string? SubText { get; set; }
}

// Creating list items
var categories = new[]
{
    new CategoryListItem 
    { 
        Id = "1", 
        DisplayValue = "Electronics",
        SubText = "Computers, phones, and accessories"
    },
    new CategoryListItem 
    { 
        Id = "2", 
        DisplayValue = "Clothing",
        SubText = "Apparel and fashion items"
    },
    new CategoryListItem 
    { 
        Id = "3", 
        DisplayValue = "Books",
        SubText = "Physical and digital books"
    }
};

Using with Dropdowns and ComboBoxes

// In Blazor component
@using Nabs.Launchpad.Core.Dtos

<SfComboBox TValue="string" 
            TItem="CategoryListItem"
            DataSource="@categories"
            @bind-Value="@selectedCategoryId">
    <ComboBoxFieldSettings Value="Id" Text="DisplayValue"></ComboBoxFieldSettings>
</SfComboBox>

@code {
    private string? selectedCategoryId;
    private List<CategoryListItem> categories = new();
    
    protected override void OnInitialized()
    {
        categories = GetCategories();
    }
}

Using CommunityToolkit.Mvvm (Transitive Dependency)

using CommunityToolkit.Mvvm.ComponentModel;
using CommunityToolkit.Mvvm.Input;

// Observable DTO with validation
public partial class UserDto : ObservableObject
{
    [ObservableProperty]
    private string _firstName = string.Empty;
    
    [ObservableProperty]
    private string _lastName = string.Empty;
    
    [ObservableProperty]
    private string _email = string.Empty;
    
    // Computed property
    public string FullName => $"{FirstName} {LastName}";
    
    // Command
    [RelayCommand]
    private async Task SaveAsync()
    {
        // Save logic
        await Task.CompletedTask;
    }
}

Using FluentValidation (Transitive Dependency)

using FluentValidation;
using Microsoft.Extensions.Localization;

// Validator with localization support
public class UserDtoValidator : AbstractValidator<UserDto>
{
    public UserDtoValidator(IStringLocalizer<UserDtoValidator> localizer)
    {
        RuleFor(x => x.FirstName)
            .NotEmpty()
            .WithMessage(localizer["FirstNameRequired"])
            .MaximumLength(50)
            .WithMessage(localizer["FirstNameTooLong"]);
        
        RuleFor(x => x.LastName)
            .NotEmpty()
            .WithMessage(localizer["LastNameRequired"])
            .MaximumLength(50)
            .WithMessage(localizer["LastNameTooLong"]);
        
        RuleFor(x => x.Email)
            .NotEmpty()
            .WithMessage(localizer["EmailRequired"])
            .EmailAddress()
            .WithMessage(localizer["EmailInvalid"]);
    }
}

Using Localization (Transitive Dependency)

using Microsoft.Extensions.Localization;

public class ProductDto : IListItem
{
    private readonly IStringLocalizer<ProductDto> _localizer;
    
    public ProductDto(IStringLocalizer<ProductDto> localizer)
    {
        _localizer = localizer;
    }
    
    public string Id { get; init; } = default!;
    public string DisplayValue { get; init; } = default!;
    public string? SubText { get; set; }
    
    public string GetLocalizedCategory(string categoryKey)
    {
        return _localizer[categoryKey];
    }
}

// Resource file: ProductDto.resx
// Key: Electronics, Value: Electronics
// 
// Resource file: ProductDto.es.resx (Spanish)
// Key: Electronics, Value: Electr�nicos

Converting Domain Models to List Items

// Domain model
public class Product
{
    public int Id { get; set; }
    public string Name { get; set; } = string.Empty;
    public string Category { get; set; } = string.Empty;
    public decimal Price { get; set; }
}

// Extension method for conversion
public static class ProductExtensions
{
    public static ProductListItem ToListItem(this Product product)
    {
        return new ProductListItem
        {
            Id = product.Id.ToString(),
            DisplayValue = product.Name,
            SubText = $"{product.Category} - ${product.Price:F2}"
        };
    }
}

// Usage
var products = await productService.GetAllAsync();
var productListItems = products.Select(p => p.ToListItem()).ToList();

API Reference

IListItem

Interface for standardized list items used in UI components.

Properties

Id

public string Id { get; init; }

Unique identifier for the list item. Typically a GUID, database ID, or other unique value.

DisplayValue

public string DisplayValue { get; init; }

The text displayed to the user in lists, dropdowns, and other UI components.

SubText

public string? SubText { get; set; }

Optional secondary text for additional context or description.

Included Transitive Dependencies

This library includes the following packages as transitive dependencies, making them available to consuming projects:

CommunityToolkit.Mvvm

Provides MVVM infrastructure including:

• ObservableObject: Base class for objects that notify property changes
• [ObservableProperty]: Source generator for automatic property change notification
• [RelayCommand]: Source generator for ICommand implementations
• INotifyPropertyChanged and INotifyPropertyChanging implementations
• Messenger for loosely-coupled communication

Documentation: https://learn.microsoft.com/dotnet/communitytoolkit/mvvm/

FluentValidation

Declarative validation framework providing:

• Rule-based validation with fluent interface
• Built-in validators (email, length, range, etc.)
• Custom validator support
• Async validation support
• Integration with dependency injection

Documentation: https://docs.fluentvalidation.net/

Microsoft.Extensions.Localization

Localization support providing:

• IStringLocalizer<T> for type-specific resource access
• Resource file (.resx) support
• Culture-aware string resolution
• Parameterized localization strings

Documentation: https://learn.microsoft.com/aspnet/core/fundamentals/localization

Best Practices

IListItem Implementation

1. Use Immutable Initialization: Use init for Id and DisplayValue to prevent modification
2. Meaningful Display Values: Ensure DisplayValue is user-friendly and localized if needed
3. SubText for Context: Use SubText to provide additional information without cluttering the main display
4. Consistent IDs: Use consistent ID formats (GUIDs, integers as strings, etc.) across the application

MVVM Patterns

1. Use ObservableObject: Inherit from ObservableObject for automatic change notification
2. Use Source Generators: Prefer [ObservableProperty] and [RelayCommand] attributes over manual implementations
3. Separate Concerns: Keep DTOs focused on data, move business logic to services
4. Two-Way Binding: Leverage observable properties for efficient two-way data binding in Blazor

Validation

1. Localize All Messages: Always use IStringLocalizer for validation messages
2. Register Validators: Register validators in dependency injection for automatic discovery
3. Validate Early: Validate DTOs before sending to services or APIs
4. Reuse Validators: Create reusable validator classes for common validation patterns

Localization

1. Use Resource Files: Store all user-facing strings in .resx files
2. Namespace Resources: Use type-specific localizers (IStringLocalizer<T>)
3. Parameterized Strings: Use parameterized localization for dynamic content
4. Culture Testing: Test with multiple cultures during development

Localization Example Structure

MyProject/
  Resources/
    UserDto.resx              (default/English)
    UserDto.es.resx           (Spanish)
    UserDto.fr.resx           (French)
    ValidationMessages.resx   (default/English)
    ValidationMessages.es.resx (Spanish)

Resource file content (UserDto.resx):

<data name="FirstNameRequired" xml:space="preserve">
  <value>First name is required</value>
</data>
<data name="FirstNameTooLong" xml:space="preserve">
  <value>First name must be 50 characters or less</value>
</data>

Spanish resource file (UserDto.es.resx):

<data name="FirstNameRequired" xml:space="preserve">
  <value>El nombre es obligatorio</value>
</data>
<data name="FirstNameTooLong" xml:space="preserve">
  <value>El nombre debe tener 50 caracteres o menos</value>
</data>

Testing

Testing IListItem Implementations

[Fact]
public void ListItem_Properties_ShouldBeSetCorrectly()
{
    // Arrange
    var id = Guid.NewGuid().ToString();
    var displayValue = "Test Item";
    var subText = "Additional context";
    
    // Act
    var item = new TestListItem
    {
        Id = id,
        DisplayValue = displayValue,
        SubText = subText
    };
    
    // Assert
    item.Id.Should().Be(id);
    item.DisplayValue.Should().Be(displayValue);
    item.SubText.Should().Be(subText);
}

Testing with FluentValidation

[Fact]
public async Task Validator_InvalidEmail_ShouldFail()
{
    // Arrange
    var dto = new UserDto
    {
        FirstName = "John",
        LastName = "Doe",
        Email = "invalid-email"
    };
    
    var validator = new UserDtoValidator(mockLocalizer);
    
    // Act
    var result = await validator.ValidateAsync(dto);
    
    // Assert
    result.IsValid.Should().BeFalse();
    result.Errors.Should().Contain(e => e.PropertyName == nameof(UserDto.Email));
}

Architecture and Design

DTO as Foundation

This library serves as a foundational package that:

• Defines common interfaces (like IListItem)
• Provides transitive dependencies for MVVM, validation, and localization
• Enables consistent patterns across all DTO implementations in the solution

Separation of Concerns

• DTOs: Data structures for transferring data between layers
• Validators: Separate classes for validation logic
• View Models: Use ObservableObject for UI binding
• Resources: Separate resource files for localization

Dependencies

• FluentValidation: For declarative validation rules and validators
• CommunityToolkit.Mvvm: For MVVM infrastructure including ObservableObject and commands
• Microsoft.Extensions.Localization: For localization and resource management

Note: These dependencies are transitive, meaning any project that references this library automatically has access to these packages.

Target Framework

• .NET 10