TAF.CRUD.SDK 6.0.8

TAF.CRUD.SDK

Official .NET SDK for consuming TAF.CRUD microservice. Provides both synchronous and asynchronous CRUD operations with a fluent query builder API.

Installation

dotnet add package TAF.CRUD.SDK

Features

• Dual Client Modes: Synchronous (wait for results) or asynchronous (fire-and-forget with RabbitMQ events)
• Fluent Query Builder: Strongly-typed filter conditions with all SQL operators
• Automatic Retries: Configurable retry logic for failed requests (sync mode only)
• Event Carried State Transfer: Pass metadata through Context.Properties to consuming microservices
• Multi-Tenant Support: Built-in context headers for tenant isolation
• Self-Contained Package: All dependencies bundled - install one package, get everything

Quick Start

Configuration

Register both clients with a single method:

using TAF.CRUD.SDK.Extensions;

// Register both Sync and Async clients
builder.Services.AddCRUDClient(
    // Sync client (with retry options)
    syncOptions =>
    {
        syncOptions.BaseUrl = "https://api.example.com";
        syncOptions.TimeoutSeconds = 30;
        syncOptions.MaxRetryAttempts = 3;
        syncOptions.RetryDelayMs = 1000;
        syncOptions.ApiKey = "your-api-key";
    },
    // Async client (fire-and-forget)
    asyncOptions =>
    {
        asyncOptions.BaseUrl = "https://api.example.com";
        asyncOptions.TimeoutSeconds = 30;
        asyncOptions.ApiKey = "your-api-key";
    }
);

// Or register only Sync client
builder.Services.AddCRUDClient(
    syncOptions => { syncOptions.BaseUrl = "https://api.example.com"; }
);

// Or register only Async client
builder.Services.AddCRUDClient(
    asyncConfigure: asyncOptions => { asyncOptions.BaseUrl = "https://api.example.com"; }
);

Synchronous Client Usage

Use for traditional request-response operations:

public class OrderService
{
    private readonly SyncCRUDClient _client;

    public OrderService(SyncCRUDClient client)
    {
        _client = client;
    }

    public async Task<Guid> CreateOrderAsync(string orderNumber, decimal amount)
    {
        var context = new Context
        {
            TenantId = Guid.Parse("tenant-id"),
            AppId = Guid.Parse("app-id"),
            EnvironmentId = Guid.Parse("env-id"),
            UserId = Guid.Parse("user-id")
        };

        var orderId = await _client
            .Query("Orders")
            .Insert(new Dictionary<string, object>
            {
                ["OrderNumber"] = orderNumber,
                ["Amount"] = amount,
                ["OrderDate"] = DateTime.UtcNow
            })
            .WithContext(context)
            .ExecuteAsync();

        return orderId; // Actual GUID returned immediately
    }

    public async Task<List<Dictionary<string, object>>> GetActiveOrdersAsync()
    {
        return await _client
            .Query("Orders")
            .Where(filter => filter
                .And(c => c.Field("IsActive").EqualTo(true))
                .And(c => c.Field("Amount").GreaterThan(100)))
            .WithContext(context)
            .ToListAsync();
    }

    public async Task<int> UpdateOrderAsync(Guid orderId, string status)
    {
        return await _client
            .Query("Orders")
            .Where(filter => filter.And(c => c.Field("Id").EqualTo(orderId)))
            .WithContext(context)
            .UpdateAsync(new Dictionary<string, object>
            {
                ["Status"] = status,
                ["UpdatedDate"] = DateTime.UtcNow
            });
    }

    public async Task<int> DeleteOldOrdersAsync()
    {
        return await _client
            .Query("Orders")
            .Where(filter => filter
                .And(c => c.Field("OrderDate").LessThan(DateTime.UtcNow.AddYears(-1))))
            .WithContext(context)
            .DeleteAsync();
    }
}

Asynchronous Client Usage

Use for microservice-to-microservice communication with event-driven results:

public class AsyncOrderService
{
    private readonly AsyncCRUDClient _client;

    public AsyncOrderService(AsyncCRUDClient client)
    {
        _client = client;
    }

    public async Task<Guid> CreateOrderAsync(string orderNumber, decimal amount)
    {
        var context = new Context
        {
            TenantId = Guid.Parse("tenant-id"),
            AppId = Guid.Parse("app-id"),
            EnvironmentId = Guid.Parse("env-id"),
            UserId = Guid.Parse("user-id"),
            // Pass metadata to event consumers
            Properties = new Dictionary<string, object>
            {
                ["OrderType"] = "StandardOrder",
                ["Source"] = "OrderService"
            }
        };

        // Fire-and-forget: Returns CorrelationId immediately
        var correlationId = await _client
            .Query("Orders")
            .Insert(new Dictionary<string, object>
            {
                ["OrderNumber"] = orderNumber,
                ["Amount"] = amount
            })
            .WithContext(context)
            .ExecuteAsync();

        // Actual result arrives via RabbitMQ RecordInsertedEvent
        return correlationId;
    }
}

Event Consumption

Consume RabbitMQ events to get operation results:

using TAF.CRUD.Domain.Events;
using MassTransit;

public class OrderInsertedEventConsumer : IConsumer<RecordInsertedEvent>
{
    public async Task Consume(ConsumeContext<RecordInsertedEvent> context)
    {
        var @event = context.Message;

        if (@event.EntityName != "Orders") return;

        // Access custom metadata
        var orderType = @event.Properties.GetValueOrDefault("OrderType")?.ToString();

        if (@event.IsSuccess)
        {
            // @event.RecordId contains the new order's GUID
            // @event.Properties contains your custom metadata
            // Process successful creation
        }
        else
        {
            // Handle failure: @event.ErrorMessage, @event.ErrorCode
        }
    }
}

Fluent Query API

Filtering

// Simple conditions
.Where(filter => filter.And(c => c.Field("Status").EqualTo("Active")))

// Multiple conditions
.Where(filter => filter
    .And(c => c.Field("Status").EqualTo("Active"))
    .And(c => c.Field("Amount").GreaterThan(1000))
    .Or(c => c.Field("Priority").EqualTo("High")))

// Grouped conditions
.Where(filter => filter
    .And(c => c.Field("IsActive").EqualTo(true))
    .AndGroup(nested => nested
        .And(c => c.Field("Status").EqualTo("Pending"))
        .Or(c => c.Field("Status").EqualTo("InProgress"))))

// Conditional filtering
.Where(filter => filter
    .And(c => c.Field("IsActive").EqualTo(true))
    .AndIf(includeExpensive, c => c.Field("Price").GreaterThan(1000)))

Supported Operators

Comparison: EqualTo, NotEqualTo, GreaterThan, GreaterThanOrEqualTo, LessThan, LessThanOrEqualTo

String: Contains, NotContains, StartsWith, NotStartsWith, EndsWith, NotEndsWith

List: In, NotIn

Range: Between, NotBetween

Null: IsNull, IsNotNull

Field Selection & Ordering

// Select specific fields
.Select("OrderNumber", "Amount", "OrderDate")

// Ordering
.OrderBy("OrderDate")
.OrderByDescending("Amount")

// Single record
.FirstOrDefaultAsync()

Architecture

Unified Registration

The SDK uses a single registration method that supports three scenarios:

// Both clients
services.AddCRUDClient(syncOptions => {...}, asyncOptions => {...});

// Sync only
services.AddCRUDClient(syncOptions => {...});

// Async only
services.AddCRUDClient(asyncConfigure: asyncOptions => {...});

Benefits:

• ✅ 55% less code (70 lines vs 155 lines)
• ✅ Optional parameters - register only what you need
• ✅ Core services registered once and shared
• ✅ Sync client preferred as default for IQueryRepository

Core Services (SOLID Principles)

IUrlBuilder (CRUDUrlBuilder)

Constructs endpoint URLs for all CRUD operations. Singleton lifetime.

string BuildSyncInsertUrl();
string BuildAsyncInsertUrl();  // CorrelationId in header, not URL
string BuildSelectUrl();

IHttpRequestFactory (CRUDHttpRequestFactory)

Creates HTTP requests and converts Context to headers. Singleton lifetime.

HttpRequestMessage CreatePostRequest<TRequest>(string url, TRequest body, Context context);

Context Headers (aligned with TAF.Infra.MassTransit):

• TenantId from context.TenantId
• AppId from context.AppId
• EnvironmentId from context.EnvironmentId
• UserId from context.UserId
• CorrelationId from context.CorrelationId

IResponseProcessor (CRUDResponseProcessor)

Response deserialization, error handling, and validation. Singleton lifetime.

Task<OperationResult<T>> ProcessResponseAsync<T>(HttpResponseMessage response);
Task EnsureSuccessAsync(HttpResponseMessage response, string operation);

Client Comparison

Self-Contained Packaging

The package includes all dependencies:

• TAF.CRUD.SDK.dll
• TAF.CRUD.Contracts.dll
• TAF.CRUD.Domain.dll
• TAF.CRUD.SharedKernel.dll
• TAF.QueryBuilder.Abstractions.dll

External NuGet dependencies (auto-resolved):

• Microsoft.Extensions.Http (>= 8.0.0)
• Microsoft.Extensions.Options (>= 8.0.0)
• TAF.Infra.MassTransit (>= 1.0.4)

Benefit: Install one package, get everything needed. No version conflicts.

Configuration Options

SyncCRUDClientOptions

CRUDClientOptions (Async)

Error Handling

using TAF.CRUD.SDK.Exceptions;

try
{
    var result = await _client.Query("Orders").Insert(fields).WithContext(context).ExecuteAsync();
}
catch (CRUDClientException ex)
{
    Console.WriteLine($"Failed: {ex.Message}");
    Console.WriteLine($"Status: {ex.StatusCode}, Code: {ex.ErrorCode}");
}

When to Use Each Client

Use Synchronous Client When:

• Traditional request-response APIs
• Need immediate results
• Simple error handling
• Fast operations (< 2 seconds)
• No event consumers needed

Use Asynchronous Client When:

• Microservice-to-microservice communication
• Fire-and-forget behavior
• Event Carried State Transfer needed
• High-throughput scenarios
• RabbitMQ/MassTransit architecture

Best Practices

1. Inject Concrete Types: Use SyncCRUDClient or AsyncCRUDClient to choose specific client
2. Context is Required: Always provide tenant/app/environment/user context
3. Retry Configuration: Adjust retry settings based on operation duration
4. Event Metadata: Use Context.Properties for custom metadata in async operations
5. CorrelationId Tracking: Use returned GUID to correlate async operations with events

Troubleshooting

Connection Failures: Verify BaseUrl, network connectivity, API key validity

Event Not Received: Check MassTransit consumer registration, RabbitMQ connection, CorrelationId matching

Timeout Errors: Increase TimeoutSeconds (async client only waits for 202 Accepted)

Authentication Errors: Verify ApiKey and context headers (TenantId, AppId, etc.)

License

MIT License

Support

For issues or questions, contact the TAF platform team.