Tago.Extensions.Configuration 6.0.2

Tago.Extensions.Configuration

Tago.Extensions.Configuration is a comprehensive .NET library that extends the capabilities of the standard Microsoft.Extensions.Configuration framework. It enables dynamic configuration resolution through a powerful pipe-based templating system, allowing developers to reference environment variables, resolve configuration properties, apply type conversions, and implement sophisticated fallback chains—all directly within appsettings.json.

Key Features

• Dynamic Value Resolution: Reference environment variables and configuration properties using template syntax
• Advanced Pipe System: Apply transformations and type conversions (int, bool, double, date, currency, percentage, enum, URI, and more)
• Intelligent Fallback Chains: Define multiple resolution strategies with automatic fallback to alternative sources or hardcoded defaults
• Template Strings: Support multiple references within a single configuration value for complex template resolution
• Seamless Integration: Works transparently with the standard .NET Core configuration system
• Production-Ready: Comprehensive circular reference detection and error handling

Installation

Install via NuGet Package Manager:

dotnet add package Tago.Extensions.Configuration

Or via Package Manager Console:

Install-Package Tago.Extensions.Configuration

Quick Start

1. Setup in Program.cs

var builder = WebApplication.CreateBuilder(args);

// Add dynamic configuration support
builder.Configuration.AddDynamicConfiguration();

var app = builder.Build();

2. Configure appsettings.json

{
  "Database": {
    "Server": "localhost",
    "Port": "5432"
  },
  "AppName": "MyApplication"
}

3. Access Configuration

var server = configuration["Database:Server"];        // "localhost"
var port = configuration["Database:Port"];              // "5432"

---

Usage Examples: Simple to Advanced

Example 1: Simple Static Values

Simplest case - no dynamic resolution needed

{
  "Application": {
    "Name": "My Application",
    "Version": "1.0.0",
    "Environment": "Production"
  }
}

var appName = configuration["Application:Name"];      // "My Application"
var version = configuration["Application:Version"];    // "1.0.0"

---

Example 2: Environment Variable Resolution

Reference environment variables directly in configuration

{
  "Database": {
    "ConnectionString": "{env: DB_CONNECTION_STRING}",
    "Username": "{env: DB_USER}",
    "Password": "{env: DB_PASSWORD}"
  }
}

Environment Variables:

DB_CONNECTION_STRING=Server=prod.database.local;Port=5432
DB_USER=admin
DB_PASSWORD=SecurePassword123

Code Access:

var connectionString = configuration["Database:ConnectionString"];  
// "Server=prod.database.local;Port=5432"

var username = configuration["Database:Username"];                  
// "admin"

---

Example 3: Property Reference Chaining

Reference other configuration properties to avoid duplication

{
  "Server": {
    "Host": "api.prod.local",
    "Port": "8443"
  },
  "Service": {
    "BaseUrl": "https://{property: Server:Host}:{property: Server:Port}",
    "ApiVersion": "/api/v1"
  }
}

Code Access:

var baseUrl = configuration["Service:BaseUrl"];  
// "https://api.prod.local:8443"

var fullPath = configuration["Service:BaseUrl"] + configuration["Service:ApiVersion"];
// "https://api.prod.local:8443/api/v1"

---

Example 4: Type Conversion with Pipes

Automatically convert configuration values to specific types

{
  "Server": {
    "MaxConnections": "{env: MAX_CONNECTIONS | int || 100}",
    "EnableLogging": "{env: ENABLE_LOGGING | bool || true}",
    "RequestTimeout": "{env: TIMEOUT_SECONDS | double || 30.5}",
    "RetryCount": "{env: RETRY_COUNT | int || 3}"
  }
}

Code Access:

// With pipe processor applied
var maxConnections = configuration["Server:MaxConnections"];    // "100"
var enableLogging = configuration["Server:EnableLogging"];      // "true"
var timeout = configuration["Server:RequestTimeout"];           // "30.5"

---

Example 5: Date Parsing with Format Specifications

Parse and validate dates with custom format specifications

{
  "Deployment": {
    "ReleaseDate": "{env: RELEASE_DATE | date:yyyy-MM-dd || 2026-02-15}",
    "LastUpdate": "{env: UPDATE_TIMESTAMP | date:yyyy-MM-dd HH:mm:ss || 2026-02-12 14:30:00}",
    "ExpirationDate": "{env: EXPIRY | date || 2026-12-31}"
  }
}

Environment Variable:

RELEASE_DATE=2026-03-01
UPDATE_TIMESTAMP=2026-02-12 09:15:30

Code Access:

var releaseDate = configuration["Deployment:ReleaseDate"];      
// "2026-03-01" (parsed and validated)

var updateTime = configuration["Deployment:LastUpdate"];         
// "2026-02-12 09:15:30"

var expiry = configuration["Deployment:ExpirationDate"];         
// "2026-12-31"

---

Example 6: Currency and Numeric Formatting

Format numbers as currency, percentages, or with specific precision

{
  "Pricing": {
    "BasePrice": "{env: PRODUCT_PRICE | number:currency:USD || 99.99}",
    "DiscountRate": "{env: DISCOUNT_PERCENT | number:percent || 0.15}",
    "TaxRate": "{env: TAX_RATE | number:percent || 0.085}",
    "Precision": "{env: CALCULATION_VALUE | number:2 || 10.5555}"
  }
}

Environment Variables:

PRODUCT_PRICE=1250.75
DISCOUNT_PERCENT=0.25
TAX_RATE=0.0875
CALCULATION_VALUE=123.456789

Code Access:

var price = configuration["Pricing:BasePrice"];         
// "$1,250.75" (formatted as USD currency)

var discount = configuration["Pricing:DiscountRate"];   
// "25%" (formatted as percentage)

var tax = configuration["Pricing:TaxRate"];             
// "8.75%" (formatted as percentage with 2 decimals)

var precision = configuration["Pricing:Precision"];     
// "123.46" (rounded to 2 decimal places)

---

Example 7: Fallback Chains with Multiple Alternatives

Define multiple resolution strategies, trying each until one succeeds

{
  "Database": {
    "Server": "localhost",
    "Port": "{env: DB_PORT | int || property: DefaultDatabase:Port | int || 5432}"
  },
  "DefaultDatabase": {
    "Port": "5433"
  },
  "Cache": {
    "ConnectionString": "{env: REDIS_CONNECTION || property: Cache:DefaultConnection || localhost:6379}",
    "DefaultConnection": "localhost:6379",
    "Timeout": "{env: CACHE_TIMEOUT | int || 300}"
  }
}

Resolution Logic:

• DB_PORT environment variable → if set, use it and convert to int
• Otherwise, try property: DefaultDatabase:Port and convert to int
• Otherwise, fall back to hardcoded value 5432

Code Access:

// If DB_PORT env var is not set:
var port = configuration["Database:Port"];              
// "5433" (from DefaultDatabase:Port property)

// If neither env var nor property exists:
// Results in "5432" (final fallback)

var cacheConnection = configuration["Cache:ConnectionString"];
// "localhost:6379" (uses fallback chain)

---

Example 8: Complex Template Strings with Multiple References

Build sophisticated configuration values by combining multiple property and environment variable references

{
  "Database": {
    "Server": "db.prod.local",
    "Port": "5432",
    "Username": "app_user",
    "Password": "{env: DB_PASSWORD || SecurePass123}"
  },
  "ConnectionStrings": {
    "DefaultConnection": "Server={property: Database:Server};Port={property: Database:Port};User={property: Database:Username};Password={env: DB_PASSWORD || SecurePass123}",
    "ApplicationDb": "Host={property: Database:Server};Port={property: Database:Port};Database=ApplicationDb;User={property: Database:Username};Password={env: DB_PASSWORD || secure123}"
  },
  "ApiEndpoints": {
    "Domain": "api.prod.local",
    "Port": "443",
    "Version": "2",
    "BaseUrl": "https://{property: ApiEndpoints:Domain}:{property: ApiEndpoints:Port}/api/v{property: ApiEndpoints:Version}",
    "HealthCheck": "https://{property: ApiEndpoints:Domain}:{property: ApiEndpoints:Port}/api/v{property: ApiEndpoints:Version}/health"
  },
  "Credentials": {
    "Host": "{property: Database:Server}",
    "Port": "{property: Database:Port}",
    "User": "{property: Database:Username}",
    "ConnectionString": "{property: Credentials:User}@{property: Credentials:Host}:{property: Credentials:Port}"
  }
}

Environment Variable:

DB_PASSWORD=MySecurePassword@2026

Code Access:

var connString = configuration["ConnectionStrings:DefaultConnection"];
// "Server=db.prod.local;Port=5432;User=app_user;Password=MySecurePassword@2026"

var appDbConnection = configuration["ConnectionStrings:ApplicationDb"];
// "Host=db.prod.local;Port=5432;Database=ApplicationDb;User=app_user;Password=MySecurePassword@2026"

var baseApi = configuration["ApiEndpoints:BaseUrl"];
// "https://api.prod.local:443/api/v2"

var healthCheck = configuration["ApiEndpoints:HealthCheck"];
// "https://api.prod.local:443/api/v2/health"

var credentials = configuration["Credentials:ConnectionString"];
// "app_user@db.prod.local:5432"

---

Example 9: Case-Insensitive Keywords and Mixed Formats

Keywords support case-insensitive variations and mixed formatting

{
  "Database": {
    "Server": "db.local",
    "Port": "5432"
  },
  "VariationTests": {
    "PropertyLower": "{property: Database:Server}",
    "PropertyUpper": "{PROPERTY: Database:Server}",
    "PropertyMixed": "{PrOpErTy: Database:Server}",
    "EnvLower": "{env: DB_PORT}",
    "EnvUpper": "{ENV: DB_PORT}",
    "EnvMixed": "{eNv: DB_PORT}"
  }
}

All variations resolve to the same values:

var prop1 = configuration["VariationTests:PropertyLower"];    // "db.local"
var prop2 = configuration["VariationTests:PropertyUpper"];    // "db.local"
var prop3 = configuration["VariationTests:PropertyMixed"];    // "db.local"

---

Example 10: Advanced Real-World Scenario

Production-grade configuration combining all features

{
  "Environment": "{env: ASPNETCORE_ENVIRONMENT || Development}",
  
  "Database": {
    "Server": "{env: DB_SERVER || localhost}",
    "Port": "{env: DB_PORT | int || 5432}",
    "Username": "{env: DB_USER || app_user}",
    "Password": "{env: DB_PASSWORD}",
    "ConnectionString": "Server={property: Database:Server};Port={property: Database:Port};Database=ProductionDb;User={property: Database:Username};Password={env: DB_PASSWORD};Pooling=true;Max Pool Size=20"
  },

  "Security": {
    "TokenExpiry": "{env: TOKEN_EXPIRY | int || 3600}",
    "RefreshTokenExpiry": "{env: REFRESH_TOKEN_EXPIRY | int || 86400}",
    "CertificatePath": "{env: CERT_PATH || /etc/certs/default.pem}",
    "EncryptionKey": "{env: ENCRYPTION_KEY || DefaultKey2026}"
  },

  "Logging": {
    "LogLevel": "{env: LOG_LEVEL || Information}",
    "MinimumLevel": "{env: MIN_LOG_LEVEL || Warning}",
    "EnableFileLogging": "{env: FILE_LOGGING | bool || false}",
    "LogPath": "/var/logs/application-{property: Environment}.log"
  },

  "Api": {
    "BaseUrl": "https://{env: API_DOMAIN || api.example.com}:{env: API_PORT | int || 443}",
    "Version": "{env: API_VERSION || 1.0.0}",
    "Timeout": "{env: API_TIMEOUT | int || 30}",
    "RetryCount": "{env: RETRY_ATTEMPTS | int || 3}",
    "RateLimitPerHour": "{env: RATE_LIMIT | int || 1000}"
  },

  "Features": {
    "EnableNewPipeSystem": "{env: ENABLE_PIPES | bool || true}",
    "CacheEnabled": "{env: ENABLE_CACHE | bool || true}",
    "CacheTtl": "{env: CACHE_TTL | int || 3600}",
    "MaintenanceMode": "{env: MAINTENANCE_MODE | bool || false}",
    "DiscountPercentage": "{env: DISCOUNT_RATE | number:percent || 0.15}"
  },

  "Deployment": {
    "ReleaseDate": "{env: RELEASE_DATE | date:yyyy-MM-dd || 2026-02-12}",
    "LastHealthCheck": "{env: HEALTH_CHECK_TIME | date:yyyy-MM-dd HH:mm:ss || 2026-02-12 12:00:00}",
    "ExpirationDate": "{env: LICENSE_EXPIRY | date:yyyy-MM-dd || 2027-12-31}"
  },

  "Pricing": {
    "StandardPrice": "{env: STANDARD_PRICE | number:currency:USD || 99.99}",
    "PremiumPrice": "{env: PREMIUM_PRICE | number:currency:USD || 199.99}",
    "TaxRate": "{env: TAX_RATE | number:percent || 0.085}",
    "BulkDiscountThreshold": "{env: BULK_THRESHOLD | int || 100}"
  }
}

Environment Variables Sample:

ASPNETCORE_ENVIRONMENT=Production
DB_SERVER=prod-db.company.local
DB_PORT=5432
DB_USER=prod_app_user
DB_PASSWORD=SuperSecurePassword!2026
CERT_PATH=/etc/ssl/certs/company.pem
LOG_LEVEL=Error
API_DOMAIN=api.prod.company.com
API_PORT=443
ENABLE_CACHE=true
CACHE_TTL=7200
RELEASE_DATE=2026-02-15
STANDARD_PRICE=149.99
PREMIUM_PRICE=249.99

Code Access:

// Simple access
var connectionString = configuration["Database:ConnectionString"];
// "Server=prod-db.company.local;Port=5432;Database=ProductionDb;..."

var apiUrl = configuration["Api:BaseUrl"];
// "https://api.prod.company.com:443"

var standardPrice = configuration["Pricing:StandardPrice"];
// "$149.99" (formatted as currency)

var taxRate = configuration["Pricing:TaxRate"];
// "8.5%" (formatted as percentage)

// Type-safe extraction
var tokenExpiry = int.Parse(configuration["Security:TokenExpiry"]);  // 3600

var cacheEnabled = bool.Parse(configuration["Features:CacheEnabled"]);  // true

var releaseDate = DateTime.Parse(configuration["Deployment:ReleaseDate"]);  
// 2026-02-15

---

Number Formatting with Advanced Syntax

Comprehensive Number Formatting Support

The number pipe now supports all standard C# number format codes, custom patterns, and input-output transformations. Use colon (:) delimiters with optional quotes for complex format strings.

Format Specifications

1. Simple Decimal Precision

Specify just a number for decimal places:

{
  "Precision": "{env: VALUE | number:2}",
  "ThreeDecimals": "{env: VALUE | number:3}"
}

With VALUE=1234.56789:

• number:2 → "1234.57" (auto-converts to F2)
• number:3 → "1234.568"

---

2. Standard C# Format Codes

Fixed-Point & Number Formats:

{
  "FixedPoint": "{env: VALUE | number:F2}",
  "WithThousands": "{env: VALUE | number:N2}",
  "Percentage": "{env: VALUE | number:P2}",
  "Currency": "{env: VALUE | number:C2}"
}

Code	Name	VALUE=1234.56789	Output
F2	Fixed-point	1234.56789	1234.57
N2	Number	1234.56789	1,234.57
P2	Percentage	0.85	85.00%
C2	Currency	1234.56789	$1,234.57
E2	Exponential	1234.56789	1.23E+003
D2	Decimal (int only)	42	42
G	General	1234.56789	1234.56789
X	Hexadecimal (int only)	255	FF

---

3. Custom Format Patterns

Use any standard .NET custom number format pattern:

{
  "OptionalDecimals": "{env: VALUE | number:0.##}",
  "WithThousands": "{env: VALUE | number:0,0.00}",
  "ThousandsOnly": "{env: VALUE | number:0,0}",
  "Percentage": "{env: VALUE | number:0.0%}",
  "ScientificShort": "{env: VALUE | number:0.00E+00}"
}

Pattern Examples:

• 0.## - At least 1 decimal, up to 2 optional decimals
• 0,0.00 - Thousands separator with 2 required decimals
• 0,0 - Thousands separator, no decimals
• #,##0.## - Thousands separator, optional decimals
• ###,##0 - Thousands separator for numbers > 999

With VALUE=1234.56789:

• 0.## → 1234.57
• 0,0.00 → 1,234.57
• 0,0 → 1,235 (rounded)

---

4. Keywords for Common Formats

{
  "Percentage": "{env: VALUE | number:percent}",
  "Currency": "{env: VALUE | number:currency:USD}",
  "SimplePercent": "{env: VALUE | number:%}"
}

Keywords:

• percent - Format as percentage (VALUE × 100%)
• currency:USD - Format as USD currency (uses en-US culture)
• currency - Format as currency (uses en-US culture)
• % - Shorthand for percent

---

5. Input-Output Format Transformation (Advanced)

Transform number formatting in two steps: parse input format, output desired format. Separate with colon (:).

{
  "SimpleOutput": "{env: VALUE | number::F2}",
  "InputToOutput": "{env: VALUE | number:F2:N2}",
  "LenientCustom": "{env: VALUE | number::0,0.00}"
}

Syntax: number:INPUT_FORMAT:OUTPUT_FORMAT

• Empty input (first colon) = Lenient parsing (accepts any valid number)
• Empty output (trailing colon) = Standard output
• Both specified = Strict input format, custom output format

Examples:

{
  "StandardParsing": "{env: VALUE | number::F2}",
  "Comment": "Parse any number, output F2 format"
}

Syntax	Input Behavior	Output Format
number::2	Lenient	2 decimals (F2)
number:F2:N2	Strict F2	Thousands + 2 decimals
number::0,0	Lenient	Thousands, no decimals

---

6. Complex Formats with Colons (Using Quotes)

When format strings contain colons (e.g., time formats), use quotes to protect them:

{
  "TimeFormat": "{env: TIME_VALUE | number:'HH:mm:ss.fff Z':'HH-mm-ss'}",
  "DateTimeWithMs": "{env: DT | number:'yyyy-MM-dd HH:mm:ss.fff':'yyyy/MM/dd HH:mm'}"
}

Format Strings with Colons:

• 'HH:mm:ss.fff Z' - Input: time with colons
• 'HH-mm-ss' - Output: normalized format

---

Complete Number Formatting Example

{
  "NumberFormatting": {
    "SimpleDecimals": "{env: AMOUNT | number:2 || 100.555}",
    "FixedPoint": "{env: AMOUNT | number:F2 || 100.56}",
    "WithThousands": "{env: AMOUNT | number:N2 || 1,234.57}",
    "Percentage": "{env: RATE | number:P2 || 12.50%}",
    "Currency": "{env: PRICE | number:C2 || $1,234.57}",
    "CustomPattern": "{env: AMOUNT | number:0.## || 1234.57}",
    "InputOutput": "{env: AMOUNT | number::N2 || 1,234.57}",
    "QuotedFormat": "{env: TIME | number:'HH:mm:ss':'HH-mm-ss' || 14-30-45}"
  }
}

Environment Variables:

AMOUNT=1234.56789
RATE=0.125
PRICE=1234.5678
TIME=14:30:45

Code Access:

var simple = configuration["NumberFormatting:SimpleDecimals"];
// "1234.57"

var with Thousands = configuration["NumberFormatting:WithThousands"];
// "1,234.57"

var percent = configuration["NumberFormatting:Percentage"];
// "12.50%"

var currency = configuration["NumberFormatting:Currency"];
// "$1,234.57"

var customPattern = configuration["NumberFormatting:CustomPattern"];
// "1234.57"

---

Pipe System Reference

Available Pipes

Pipe	Syntax	Example	Output
int	value \| int	"42" \| int	"42"
bool	value \| bool	"true" \| bool	"true"
double	value \| double	"3.14" \| double	"3.14"
date	value \| date	"2026-02-12" \| date	"2026-02-12T00:00:00"
date (with format)	value \| date:format	"2026-02-12" \| date:yyyy-MM-dd	"2026-02-12"
date (input→output)	value \| date:'in':'out'	"02/12/2026" \| date:'MM/dd/yyyy':'yyyy-MM-dd'	"2026-02-12"
number (simple)	value \| number:2	"10.5555" \| number:2	"10.56"
number (standard)	value \| number:F2	"1234.567" \| number:F2	"1234.57"
number (thousands)	value \| number:N2	"1234.567" \| number:N2	"1,234.57"
number (percent)	value \| number:P2	"0.15" \| number:P2	"15.00%"
number (currency)	value \| number:C2	"1000" \| number:C2	"$1,000.00"
number (custom)	value \| number:0,0.00	"1234.567" \| number:0,0.00	"1,234.57"
number (input→output)	value \| number:in:out	"1234.5" \| number::N2	"1,234.50"
enum	value \| enum:Val1,Val2,Val3	"Debug" \| enum:Debug,Info,Warn	"Debug"
uri	value \| uri	"https://example.com" \| uri	"https://example.com"
uppercase	value \| uppercase	"hello" \| uppercase	"HELLO"
lowercase	value \| lowercase	"HELLO" \| lowercase	"hello"

---

Fallback Chain Syntax

Fallback chains allow multiple resolution strategies. The system tries each alternative in order until one succeeds:

{
  "Config": "{env: PRIMARY || property:Secondary || literal_default || another_fallback}"
}

Resolution Order:

1. Try environment variable PRIMARY
2. If not found, try property Secondary
3. If not found, use literal value literal_default
4. Continue with additional fallbacks as needed

---

Best Practices

• Environment Secrets: Use environment variables for sensitive information (passwords, API keys, certificates)
• Property Defaults: Use configuration properties for environment-specific defaults
• Fallback Chains: Always provide meaningful fallback values for critical configuration
• Type Safety: Use pipe conversions to validate configuration data types early
• Documentation: Document non-obvious configuration dependencies and format requirements
• Testing: Test configuration resolution with various environment setups

---

Error Handling

The library includes robust error handling:

• Circular References: Automatically detected and prevented
• Missing Values: Return fallback or configured default
• Type Conversion Failures: Falls back to next alternative in chain
• Malformed Syntax: Treated as literal values, does not crash

---

Support

For issues, questions, or contributions, please visit the project repository or contact support@tago-solutions.com.

---

Thank you for using Tago.Extensions.Configuration. We're committed to making your .NET configuration management more powerful, flexible, and maintainable.