TAF.MetaData.SDK 10.1.5

TAF Metadata Client SDK

👁 NuGet Version
👁 .NET

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.

🆕 New in v6.0.0

• Connection Management - Get database connections by environment or application
• Self-Contained Package - All required DLLs bundled (no external dependencies)
• Removed SDK.Contracts - Now uses bundled Contracts/Domain types directly
• Breaking Change - Consumers using TAF.MetaData.SDK.Contracts namespace must update to TAF.MetaData.Contracts or TAF.MetaData.Domain

🏗️ Architecture & Design Principles

✅ Clean Architecture - Proper separation of layers: Client, Infrastructure, Services, Interfaces, Core
✅ SOLID Principles - Single responsibility, dependency inversion, interface segregation
✅ Industry Standards - Follows AWS, Azure, Stripe SDK naming conventions
✅ HTTP-First - Lightweight, direct API communication
✅ Auto Context Resolution - Automatic TenantId/AppId extraction from headers
✅ Comprehensive Error Handling - Proper exception mapping and status codes
✅ Dependency 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)

Parameters:

• appObjectName - Name of the application object to retrieve
• version - Optional version filter (default: null)
• cancellationToken - Cancellation token

Returns: AppObjectResponse if found, null if not found

Throws:

• ArgumentException - When appObjectName is null/empty
• InvalidOperationException - When required headers are missing
• MetadataServiceException - When service operation fails

GetConnectionsByEnvironmentAsync (New in v6.0)

Task<OperationResult<IEnumerable<ConnectionDto>>> GetConnectionsByEnvironmentAsync(
 Guid appEnvironmentId,
 BusContext context,
 CancellationToken cancellationToken = default)

Parameters:

• appEnvironmentId - The application environment identifier
• context - Context containing TenantId, AppId, CorrelationId
• cancellationToken - Cancellation token

Returns: OperationResult containing collection of connections for the environment

GetConnectionsByAppAsync (New in v6.0)

Task<OperationResult<IEnumerable<ConnectionDto>>> GetConnectionsByAppAsync(
 Guid appId,
 BusContext context,
 CancellationToken cancellationToken = default)

Parameters:

• appId - The application identifier
• context - Context containing TenantId, AppId, CorrelationId
• cancellationToken - Cancellation token

Returns: OperationResult containing collection of connections for the application

📋 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 flow
• MetadataUrlBuilder - Builds URLs only
• MetadataHttpRequestFactory - Creates HTTP requests only
• MetadataResponseProcessor - Processes responses only
• HttpContextProvider - 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 URL
• TimeoutSeconds - 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 runtime
• Microsoft.AspNetCore.Http - HTTP context access
• Microsoft.Extensions.DependencyInjection - DI container
• Microsoft.Extensions.Http - HTTP client factory
• System.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.

🤖 Generated with Claude Code