👁 Image
TAF.Infra.QueryHook 2.3.1

TAF.Infra.QueryHook

A common interface library for QueryHook functionality that provides a standardized contract for performing configured actions. Enables consistent implementation of query hook patterns across different services and applications with configurable action execution.

🚀 Features

• Configurable Hook Interface: Common IQueryHook contract for flexible hook implementations
• Three Configurable Hook Methods:
  • ValidateAsync: Validate configurations, results, or business rules
  • PreExecuteAsync: Execute custom operations before main actions (e.g., before user creation)
  • PostExecuteAsync: Execute custom operations after main actions (e.g., send notifications after user creation)
• Independent Hook Execution: Each method can be configured and used independently based on requirements
• Type-Safe Value Objects: Strongly-typed EntityName and FieldName with validation
• Multi-Tenant Support: Built-in context for tenant, user, app, and environment isolation
• SQL Injection Protection: Type-safe entity and field names with validation
• Operation Type Support: Handle Select, Insert, Update, and Delete operations
• Extensible Context: Rich context object with fields, errors, logs, and results
• Clean Architecture: Domain-driven design with value objects and enums

📦 Installation

dotnet add package TAF.Infra.QueryHook

🗃️ Architecture Overview

The library provides configurable hook methods that can be used independently based on your configuration:

Hook Configuration Examples

Configuration 1: Pre + Post Hook
┌──────────────┐ ┌─────────────┐ ┌───────────────┐
│ User Action │ -> │ PreExecute │ -> │ PostExecute │
│ │ │ (Custom Op) │ │ (Send Email) │
└──────────────┘ └─────────────┘ └───────────────┘

Configuration 2: Validation Only
┌──────────────┐ ┌─────────────┐
│ User Action │ -> │ Validate │
│ │ │ (Check Rules)│
└──────────────┘ └─────────────┘

Configuration 3: Post Hook Only
┌──────────────┐ ┌───────────────┐
│ User Action │ -> │ PostExecute │
│ │ │ (Audit Log) │
└──────────────┘ └───────────────┘

Core Components

• IQueryHook: Main interface for configurable hook implementations
• HookContext: Rich context object containing operation details
• OperationType: Enum for database operations (Select, Insert, Update, Delete)
• EntityName: Type-safe entity name value object with SQL injection protection
• FieldName: Type-safe field name value object

🚀 Quick Start

1. Implement Hook for Pre-Execute Custom Operations

using TAF.Infra.QueryHook.Interfaces;
using TAF.Infra.QueryHook.Models;
using TAF.Infra.QueryHook.Enums;

public class UserCreationHook : IQueryHook
{
 public async Task ValidateAsync(HookContext context)
 {
 // Not used in this configuration - can be empty or throw NotImplementedException
 }

 public async Task PreExecuteAsync(HookContext context)
 {
 // Custom operation before user is added
 if (context.Operation == OperationType.Insert && context.EntityName == "Users")
 {
 // Example: Generate unique user code
 var userCode = await GenerateUniqueUserCode();
 context.Fields["UserCode"] = userCode;

 // Example: Set default values
 context.Fields["Status"] = "Pending";
 context.Fields["CreatedDate"] = DateTime.UtcNow;

 context.Logs.Add($"Pre-execute: Generated user code {userCode}");
 }
 }

 public async Task PostExecuteAsync(HookContext context)
 {
 // Not used in this configuration - can be empty or throw NotImplementedException
 }

 private async Task<string> GenerateUniqueUserCode()
 {
 // Your custom logic to generate unique code
 return $"USER_{DateTime.UtcNow:yyyyMMddHHmmss}";
 }
}

2. Implement Hook for Post-Execute Notifications

public class UserNotificationHook : IQueryHook
{
 private readonly IEmailService _emailService;
 private readonly IAuditService _auditService;

 public UserNotificationHook(IEmailService emailService, IAuditService auditService)
 {
 _emailService = emailService;
 _auditService = auditService;
 }

 public async Task ValidateAsync(HookContext context)
 {
 // Not used in this configuration
 }

 public async Task PreExecuteAsync(HookContext context)
 {
 // Not used in this configuration
 }

 public async Task PostExecuteAsync(HookContext context)
 {
 // Send email notification after user is added
 if (context.Operation == OperationType.Insert && context.EntityName == "Users")
 {
 var email = context.Fields["Email"]?.ToString();
 var name = context.Fields["Name"]?.ToString();

 if (!string.IsNullOrEmpty(email))
 {
 await _emailService.SendWelcomeEmailAsync(email, name);
 context.Logs.Add($"Welcome email sent to {email}");
 }

 // Log audit trail
 await _auditService.LogUserCreation(context.UserId, context.TenantId);
 context.Logs.Add("User creation logged for audit");
 }

 // Send notification for user deletion
 if (context.Operation == OperationType.Delete && context.EntityName == "Users")
 {
 await _emailService.SendAccountClosureNotificationAsync(context);
 context.Logs.Add("Account closure notification sent");
 }
 }
}

3. Implement Hook for Validation

public class UserValidationHook : IQueryHook
{
 public async Task ValidateAsync(HookContext context)
 {
 // Validate configuration requirements
 if (context.Operation == OperationType.Insert && context.EntityName == "Users")
 {
 // Validate email format
 if (context.Fields.TryGetValue("Email", out var emailObj))
 {
 var email = emailObj?.ToString();
 if (string.IsNullOrEmpty(email) || !IsValidEmail(email))
 {
 context.Errors.Add("Valid email address is required");
 }
 }

 // Validate business rules
 if (context.Fields.TryGetValue("Age", out var ageObj) &&
 int.TryParse(ageObj?.ToString(), out var age))
 {
 if (age < 18)
 {
 context.Errors.Add("User must be at least 18 years old");
 }
 }

 // Validate configuration-specific requirements
 var requiredRole = GetConfiguredRequiredRole(context.TenantId);
 if (!context.Fields.ContainsKey("Role") ||
 context.Fields["Role"]?.ToString() != requiredRole)
 {
 context.Errors.Add($"User must have role: {requiredRole}");
 }
 }
 }

 public async Task PreExecuteAsync(HookContext context)
 {
 // Not used in this configuration
 }

 public async Task PostExecuteAsync(HookContext context)
 {
 // Not used in this configuration
 }

 private bool IsValidEmail(string email)
 {
 // Email validation logic
 return email.Contains("@");
 }

 private string GetConfiguredRequiredRole(Guid tenantId)
 {
 // Get required role from configuration
 return "StandardUser";
 }
}

4. Using Hooks Based on Configuration

using TAF.Infra.QueryHook.Models;
using TAF.Infra.QueryHook.Enums;
using TAF.Infra.QueryHook.ValueObjects;

public class UserService
{
 private readonly List<IQueryHook> _configuredHooks;

 public UserService(IConfiguration config, IServiceProvider serviceProvider)
 {
 _configuredHooks = LoadConfiguredHooks(config, serviceProvider);
 }

 public async Task CreateUserAsync(CreateUserRequest request)
 {
 var context = new HookContext
 {
 Operation = OperationType.Insert,
 EntityName = new EntityName("Users"),
 UserId = GetCurrentUserId(),
 TenantId = GetCurrentTenantId(),
 AppId = GetCurrentAppId(),
 EnvironmentId = GetCurrentEnvironmentId(),
 Fields = new Dictionary<FieldName, object>
 {
 { new FieldName("Name"), request.Name },
 { new FieldName("Email"), request.Email },
 { new FieldName("Age"), request.Age }
 }
 };

 // Execute configured hooks
 foreach (var hook in _configuredHooks)
 {
 // Only execute if configured for this hook type
 if (IsValidationHookConfigured(hook))
 {
 await hook.ValidateAsync(context);
 }

 if (IsPreExecuteHookConfigured(hook))
 {
 await hook.PreExecuteAsync(context);
 }
 }

 // Check for validation errors
 if (context.Errors.Any())
 {
 throw new ValidationException(string.Join(", ", context.Errors));
 }

 // Execute actual database operation
 var result = await _userRepository.CreateAsync(context.Fields);
 context.Result = result;

 // Execute post-execute hooks if configured
 foreach (var hook in _configuredHooks)
 {
 if (IsPostExecuteHookConfigured(hook))
 {
 await hook.PostExecuteAsync(context);
 }
 }
 }

 private List<IQueryHook> LoadConfiguredHooks(IConfiguration config, IServiceProvider serviceProvider)
 {
 var hooks = new List<IQueryHook>();

 // Load hooks based on configuration
 if (config.GetValue<bool>("Hooks:UserCreation:Enabled"))
 hooks.Add(serviceProvider.GetService<UserCreationHook>());

 if (config.GetValue<bool>("Hooks:UserNotification:Enabled"))
 hooks.Add(serviceProvider.GetService<UserNotificationHook>());

 if (config.GetValue<bool>("Hooks:UserValidation:Enabled"))
 hooks.Add(serviceProvider.GetService<UserValidationHook>());

 return hooks;
 }
}

📚 API Reference

Core Interface

public interface IQueryHook
{
 /// <summary>
 /// Validates configurations, results, or business rules.
 /// Use when you need to validate something before or during operations.
 /// Errors added to context.Errors will indicate validation failures.
 /// </summary>
 Task ValidateAsync(HookContext context);

 /// <summary>
 /// Executes custom operations before the main action.
 /// Use when you need to perform operations before main execution
 /// (e.g., before user creation, set default values, generate codes).
 /// Can modify fields and context.
 /// </summary>
 Task PreExecuteAsync(HookContext context);

 /// <summary>
 /// Executes custom operations after the main action.
 /// Use when you need to perform operations after main execution
 /// (e.g., after user creation, send notifications, log audit trail).
 /// Receives the operation result for further processing.
 /// </summary>
 Task PostExecuteAsync(HookContext context);
}

Hook Usage Patterns

Context Object

public sealed class HookContext
{
 public required OperationType Operation { get; init; }
 public required EntityName EntityName { get; init; }
 public required Guid UserId { get; init; }
 public required Guid TenantId { get; init; }
 public required Guid AppId { get; init; }
 public required Guid EnvironmentId { get; init; }
 public required Dictionary<FieldName, object> Fields { get; init; }
 public string? WhereClause { get; init; }
 public List<string> Errors { get; init; } = [];
 public List<string> Logs { get; init; } = [];
 public object? Result { get; init; }
}

Operation Types

public enum OperationType
{
 Select = 1,
 Insert = 2,
 Update = 3,
 Delete = 4
}

Value Objects

// Strongly-typed entity name with SQL validation
public readonly record struct EntityName
{
 public EntityName(string value);
 public string Value { get; }
 public static bool TryCreate(string? value, out EntityName entityName);
 public static implicit operator string(EntityName entityName);
 public static implicit operator EntityName(string value);
}

// Strongly-typed field name
public readonly record struct FieldName
{
 public FieldName(string value);
 public string Value { get; }
 public static bool TryCreate(string? value, out FieldName fieldName);
 public static implicit operator string(FieldName fieldName);
 public static implicit operator FieldName(string value);
}

🛡️ Security Features

SQL Injection Protection

The EntityName value object provides built-in SQL injection protection:

// Safe - valid SQL identifier
var validEntity = new EntityName("Users"); ✅

// Throws exception - prevents SQL injection
var invalidEntity = new EntityName("Users; DROP TABLE Users--"); ❌
var invalidEntity2 = new EntityName("Users' OR '1'='1"); ❌

Validation Rules

• Entity Names: Must start with letter/underscore, contain only letters/digits/underscores
• Field Names: Must not be null/empty, maximum 128 characters
• Context Validation: All required context properties must be provided

🔧 Advanced Configuration Patterns

Conditional Hook Execution

public async Task PreExecuteAsync(HookContext context)
{
 // Only execute for specific entities
 if (context.EntityName == "Users")
 {
 // Custom user pre-processing
 }
 else if (context.EntityName == "Orders")
 {
 // Custom order pre-processing
 }
}

Multi-Purpose Hooks

public class ComprehensiveUserHook : IQueryHook
{
 public async Task ValidateAsync(HookContext context)
 {
 // Used when validation is configured
 await ValidateBusinessRules(context);
 }

 public async Task PreExecuteAsync(HookContext context)
 {
 // Used when pre-execute is configured
 await SetDefaultValues(context);
 }

 public async Task PostExecuteAsync(HookContext context)
 {
 // Used when post-execute is configured
 await SendNotifications(context);
 }
}

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License.

Built with ❤️ for configurable and flexible hook systems