BlackDigital 26.10.20.19

BlackDigital Framework

A comprehensive .NET framework providing essential utilities, automatic REST service generation, advanced data annotations, and model helpers for modern application development.

🚀 Key Features

🌐 Automatic REST Services Generation ⭐

The flagship feature of BlackDigital! Create REST clients automatically through interfaces decorated with attributes. No more manual HTTP calls - just define your interface and let the framework handle the rest.

[Service("api/users", version: "2025-01-15")]
public interface IUserService
{
    [Action]
    Task<List<User>> GetAllUsers();
    
    [Action("{id}", Method = RestMethod.GET)]
    Task<User> GetUserById([Path] int id);
    
    [Action(Method = RestMethod.POST)]
    Task<User> CreateUser([Body] User user);
}

// Usage
var restClient = new RestClient("https://api.example.com");
var userService = new RestService<IUserService>(restClient);
var users = await userService.CallAsync(s => s.GetAllUsers());

📝 Advanced Data Annotations

Powerful validation and display control attributes that extend .NET's built-in capabilities:

public class UserRegistration
{
    [EmailMobile(ErrorMessage = "Enter a valid email or phone")]
    public string Contact { get; set; }
    
    [RequiredIfProperty("UserType", UserType.Business)]
    [ShowIfProperty("UserType", UserType.Business)]
    public string CompanyName { get; set; }
    
    [CompareValue("Password", Symbol.Equal)]
    public string ConfirmPassword { get; set; }
}

🏗️ Model Utilities

Base classes and interfaces for common patterns:

• IId, IActive, ICreated, IUpdated, and IDeleted contracts
• Audit base classes CreatedModel, UpdatedModel, and DeletedModel
• Filtering and sorting helpers
• Option lists and data builders

🛠️ Utility Classes

Essential helpers for everyday development:

• HttpHelper - HTTP utilities and extensions
• DateTimeHelper - Date/time manipulation
• JsonCast - Shared JSON options with built-in converters for enums, Id, and TimeSpan
• ReflectionHelper - Reflection utilities
• ObjectHelper - Object manipulation
• UriHelper - URI building and manipulation

📦 Installation

Install via NuGet Package Manager:

dotnet add package BlackDigital

Or via Package Manager Console:

Install-Package BlackDigital

🏃‍♂️ Quick Start

1. REST Services Example

using BlackDigital.Rest;

// Define your API interface
[Service("api/products", version: "2025-01-15")]
public interface IProductService
{
    [Action]
    Task<List<Product>> GetProducts([Query(QueryParameterType.Parameter)] string? search = null);
    
    [Action("{id}")]
    Task<Product> GetProduct([Path] int id);
    
    [Action(Method = RestMethod.POST)]
    Task<Product> CreateProduct([Body] Product product);
    
    [Action("{id}", Method = RestMethod.PUT)]
    Task<Product> UpdateProduct([Path] int id, [Body] Product product);
    
    [Action("{id}", Method = RestMethod.DELETE)]
    Task DeleteProduct([Path] int id);
}

// Configure and use
var client = new RestClient("https://api.mystore.com");
var productService = new RestService<IProductService>(client);

// Make calls
var products = await productService.CallAsync(s => s.GetProducts("laptop"));
var product = await productService.CallAsync(s => s.GetProduct(1));

2. Data Annotations Example

using BlackDigital.DataAnnotations;

public class ContactForm
{
    [Required]
    public string Name { get; set; }
    
    [EmailMobile(ErrorMessage = "Enter a valid email or phone number")]
    public string Contact { get; set; }
    
    public ContactType Type { get; set; }
    
    [RequiredIfProperty("Type", ContactType.Business)]
    [ShowIfProperty("Type", ContactType.Business)]
    public string CompanyName { get; set; }
    
    [ShowIfProperty("Type", ContactType.Personal)]
    public DateTime? BirthDate { get; set; }
}

3. Model Utilities Example

using BlackDigital.Model;

public class User : IId, IActive
{
    public Id Id { get; set; }
    public bool Active { get; set; }
    
    public string Name { get; set; }
    public string Email { get; set; }
}

public class AuditedUser : UpdatedModel
{
    public Id Id { get; set; }
    public string Name { get; set; }
}

// Use with filters
var activeUsers = query.FilterActive(true);
var pagedUsers = query.ApplyFilter(new BaseFilter { Take = 10 });

📚 Documentation

Core Documentation

• REST Services - Complete guide to automatic REST client generation
• Data Annotations - Advanced validation and display attributes
• Data Builder - Metadata inspection helpers for dynamic forms and UI generation
• Model Utilities - Base classes and model helpers
• Utilities - Helper classes and extensions

Portuguese Documentation

• Serviços REST - Guia completo de geração automática de clientes REST
• Data Annotations - Atributos avançados de validação e exibição
• Data Builder - Helpers de inspeção de metadados para formulários dinâmicos e geração de UI
• Utilitários de Modelo - Classes base e helpers de modelo
• Utilitários - Classes auxiliares e extensões

🏗️ Architecture

The BlackDigital Framework is organized into several key components:

BlackDigital/
├── Rest/                    # Automatic REST service generation
│   ├── RestService<T>      # Main service class
│   ├── RestClient          # HTTP client wrapper
│   └── Attributes/         # Service, action, and parameter attributes
├── DataAnnotations/        # Advanced validation attributes
│   ├── Validation/         # Email, Mobile, RequiredIf, etc.
│   └── Display/           # ShowIf, NotShow, etc.
├── DataBuilder/           # Metadata inspection for dynamic UIs
├── Model/                 # Identification, audit, filters, and options
├── Converters/            # JSON converters for framework types
├── Authentication/        # Shared security abstractions
└── Utilities/             # Helper classes
    ├── HttpHelper         # HTTP utilities
    ├── JsonCast           # Shared JSON configuration
    └── ReflectionHelper   # Reflection utilities

🤝 Contributing

We welcome contributions! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

1. Clone the repository
2. Open BlackDigital.sln in Visual Studio or your preferred IDE
3. Build the solution
4. Run tests to ensure everything works

Guidelines

• Follow existing code style and conventions
• Add tests for new features
• Update documentation as needed
• Ensure all tests pass before submitting PR

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🔗 Links

• NuGet Package
• GitHub Repository
• Issues

📞 Support

If you encounter any issues or have questions, please:

1. Check the documentation
2. Search existing issues
3. Create a new issue if needed

BlackDigital Framework - Simplifying .NET development with powerful utilities and automatic REST service generation.