TAF.MetaData.SDK v3.0.0 — nugetz
pkg
TechAppForce/ TAF.MetaData.SDK v3.0.0 .NET 8.0
Professional HTTP-based SDK for TAF Metadata Service. v10.0.0: Clean release - no caching dependencies. Features Clean Architecture, SOLID principles, explicit BusContext parameter support, comprehensive error handling, screen management, batch relations support, and GUID-based lookups.
Get Started dotnet CLI PackageReference Package Manager
$ dotnet add package TAF.MetaData.SDKReadme TAF Metadata Client SDK
A professional, HTTP-based SDK for consuming TAF Metadata Service APIs. This SDK follows Clean Architecture and SOLID principles , providing enterprise-grade metadata retrieval capabilities with automatic context resolution.
🏗️ Architecture & Design Principles
✅ Clean Architecture - Proper separation of layers: Client, Infrastructure, Services, Interfaces, CoreSOLID Principles - Single responsibility, dependency inversion, interface segregationIndustry Standards - Follows AWS, Azure, Stripe SDK naming conventionsHTTP-First - Lightweight, direct API communicationAuto Context Resolution - Automatic TenantId/AppId extraction from headersComprehensive Error Handling - Proper exception mapping and status codesDependency Injection - Seamless .NET DI integration with validation
📦 Installation
dotnet add package TAF.MetaData.SDK
🚀 Quick Start
1. Configuration
Add metadata service configuration to your appsettings.json:
{
"MetadataService": {
"BaseUrl": "https://your-metadata-service.com",
"Timeout": 30
}
}
2. Service Registration
Simple configuration from appsettings:
using TAF.MetaData.SDK.Extensions;
var builder = WebApplication.CreateBuilder(args);
// One-line registration with appsettings
builder.Services.AddMetadataClient(builder.Configuration);
var app = builder.Build();
Advanced manual configuration:
// Custom configuration
builder.Services.AddMetadataClient(options =>
{
options.BaseUrl = "https://metadata-api.production.com";
options.TimeoutSeconds = 45;
});
3. Usage Inject and use the client in your services:
public class MyService
{
private readonly IMetadataClient _metadataClient;
public MyService(IMetadataClient metadataClient)
{
_metadataClient = metadataClient;
}
public async Task<AppObjectResponse?> GetUserProfile()
{
// Context (TenantId, AppId) automatically resolved from HTTP headers
return await _metadataClient.GetAppObjectAsync(
appObjectName: "UserProfile",
version: "1.2.0" // optional
);
}
}
4. HTTP Headers (Required) Ensure your HTTP requests include the required context headers:
GET /api/myendpoint
TenantId: 123e4567-e89b-12d3-a456-426614174000
AppId: 987fcdeb-51a2-43d1-9f12-345678901234
CorrelationId: req-12345-67890 (optional)
📚 API Reference
IMetadataClient
GetAppObjectAsync Task<AppObjectResponse?> GetAppObjectAsync(
string appObjectName,
string? version = null,
CancellationToken cancellationToken = default)
appObjectName - Name of the application object to retrieveversion - Optional version filter (default: null)cancellationToken - Cancellation token Returns: AppObjectResponse if found, null if not found
ArgumentException - When appObjectName is null/emptyInvalidOperationException - When required headers are missingMetadataServiceException - When service operation fails
📋 Response Models
AppObjectResponse public class AppObjectResponse
{
public Guid Id { get; set; }
public Guid TenantId { get; set; }
public Guid AppId { get; set; }
public Guid AppObjectId { get; set; }
public string AppObjectName { get; set; }
public string AppObjectJson { get; set; }
public string? Version { get; set; }
public bool IsCustom { get; set; }
public DateTime CreatedAt { get; set; }
public DateTime UpdatedAt { get; set; }
}
🏛️ Clean Architecture Structure TAF.Metadata.SDK/
├── Client/ # Consumer-facing implementations
│ └── HttpMetadataClient.cs
├── Infrastructure/ # External dependencies (HTTP context)
│ └── HttpContextProvider.cs
├── Services/ # Internal business services
│ ├── MetadataUrlBuilder.cs
│ ├── MetadataHttpRequestFactory.cs
│ └── MetadataResponseProcessor.cs
├── Interfaces/ # Contracts/abstractions
│ ├── IMetadataClient.cs
│ ├── IContextProvider.cs
│ └── ...
├── Core/ # Domain objects
│ └── MetadataContext.cs
├── Configuration/ # Options pattern
│ └── MetadataServiceOptions.cs
└── Extensions/ # DI registration
└── ServiceCollectionExtensions.cs
🎯 SOLID Principles Implementation
Single Responsibility Principle (SRP)
HttpMetadataClient - Orchestrates the request flowMetadataUrlBuilder - Builds URLs onlyMetadataHttpRequestFactory - Creates HTTP requests onlyMetadataResponseProcessor - Processes responses onlyHttpContextProvider - Resolves context from headers only
Open/Closed Principle (OCP)
SDK is extensible via interfaces
New response processors or context providers can be added
Dependency Inversion Principle (DIP)
All dependencies via abstractions (IMetadataClient, IContextProvider)
Easy to mock and test
Interface Segregation Principle (ISP)
Small, focused interfaces
Each interface has a single responsibility
⚡ Auto Context Resolution The SDK automatically extracts context from HTTP request headers:
// No manual context needed - extracted automatically!
var appObject = await _metadataClient.GetAppObjectAsync("UserProfile");
// Behind the scenes:
// 1. HttpContextProvider reads Request.Headers["TenantId"]
// 2. HttpContextProvider reads Request.Headers["AppId"]
// 3. HttpContextProvider reads Request.Headers["CorrelationId"] (optional)
// 4. Context passed to metadata service automatically
🛡️ Error Handling try
{
var userProfile = await _metadataClient.GetAppObjectAsync("UserProfile");
if (userProfile == null)
{
// Object not found (404)
Console.WriteLine("UserProfile not found");
}
}
catch (InvalidOperationException ex)
{
// Missing required headers
Console.WriteLine($"Missing context: {ex.Message}");
}
catch (MetadataServiceException ex)
{
// Service errors (network, timeout, API errors)
Console.WriteLine($"Service error: {ex.Message}, Status: {ex.StatusCode}");
}
🔧 Configuration Options
MetadataServiceOptions public class MetadataServiceOptions
{
public string BaseUrl { get; set; } = string.Empty;
public int TimeoutSeconds { get; set; } = 30;
}
Configuration validation:
BaseUrl - Required, must be valid URLTimeoutSeconds - Must be between 1 and 300 seconds
🌟 Key Features
🔄 Industry Standard Naming - IMetadataClient follows AWS/Azure patterns⚡ One-Line Setup - AddMetadataClient(configuration)🤖 Auto Context - No manual TenantId/AppId passing🛡️ Secure - Fixed SSL certificate validation📊 Lightweight - HTTP-only, no message bus dependencies🧪 Testable - All dependencies mockable via interfaces⚙️ Configurable - Supports both appsettings and manual config
📦 Dependencies
.NET 8.0+ - Modern .NET runtimeMicrosoft.AspNetCore.Http - HTTP context accessMicrosoft.Extensions.DependencyInjection - DI containerMicrosoft.Extensions.Http - HTTP client factorySystem.ComponentModel.Annotations - Configuration validation
🤝 Contributing This SDK is maintained by the TAF Development Team. For issues or feature requests, please contact the development team.
📄 License MIT License - see LICENSE file for details.
