CodeMatrix.AspNetCore.Utilities.Http 1.0.21

.NET 8.0

dotnet add package CodeMatrix.AspNetCore.Utilities.Http --version 1.0.21

NuGet\Install-Package CodeMatrix.AspNetCore.Utilities.Http -Version 1.0.21

This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.

<PackageReference Include="CodeMatrix.AspNetCore.Utilities.Http" Version="1.0.21" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

<PackageVersion Include="CodeMatrix.AspNetCore.Utilities.Http" Version="1.0.21" />
                    

                            Directory.Packages.props

<PackageReference Include="CodeMatrix.AspNetCore.Utilities.Http" />
                    

                            Project file

For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.

paket add CodeMatrix.AspNetCore.Utilities.Http --version 1.0.21

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: CodeMatrix.AspNetCore.Utilities.Http, 1.0.21"

#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.

#:package CodeMatrix.AspNetCore.Utilities.Http@1.0.21

#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.

#addin nuget:?package=CodeMatrix.AspNetCore.Utilities.Http&version=1.0.21
                    

                            Install as a Cake Addin

#tool nuget:?package=CodeMatrix.AspNetCore.Utilities.Http&version=1.0.21
                    

                            Install as a Cake Tool

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

CodeMatrix.AspNetCore.Utilities

Description

Utilities for Dot Net Core Applications

CodeMatrix.AspNetCore.Utilities is a comprehensive library that provides a collection of tools, extensions, and helpers designed to simplify common tasks in ASP.NET Core applications. This package includes utilities for JSON serialization/deserialization, date and time formatting, database operations, HTTP client interactions, model state validation, and data conversion.

Key features include:

Custom JSON converters for handling special data types
Extensive set of extension methods for common .NET types
Database operation helpers with automatic mapping capabilities
Performance-optimized Dapper integration with analytics and caching
Model state validation filters for API controllers
Configurable HTTP client with logging support
API result wrapper for consistent response formatting
Attribute-based database parameter mapping

Whether you're building a web API, a data-intensive application, or just need to streamline common operations, this library aims to reduce boilerplate code and enhance productivity.

Installation

Package Variants

To reduce dependency conflicts and allow consumers to choose only the features they need, this package is available in multiple variants:

🔹 Core Variant (`CodeMatrix.AspNetCore.Utilities`)

Minimal dependencies - Only essential utilities

Dependencies: Microsoft.Extensions.Caching.Abstractions, Microsoft.Extensions.Http, System.Text.Json
Features: Basic extensions, converters, filters, model validation
Best for: Projects that want minimal dependency footprint

<PackageReference Include="CodeMatrix.AspNetCore.Utilities" Version="1.0.0" />

🔹 Database Variant (`CodeMatrix.AspNetCore.Utilities.Database`)

Core + Database features

Additional Dependencies: Dapper, Microsoft.Data.SqlClient
Features: Core features + DapperHelper, database utilities
Best for: Projects using SQL Server and Dapper ORM

<PackageReference Include="CodeMatrix.AspNetCore.Utilities.Database" Version="1.0.0" />

🔹 Http Variant (`CodeMatrix.AspNetCore.Utilities.Http`)

Core + HTTP Client features

Additional Dependencies: Microsoft.Extensions.Http.Polly, Polly
Features: Core features + Enhanced HTTP client with retry policies
Best for: Projects making HTTP calls that need resilience

<PackageReference Include="CodeMatrix.AspNetCore.Utilities.Http" Version="1.0.0" />

🔹 Azure Variant (`CodeMatrix.AspNetCore.Utilities.Azure`)

Core + Azure integration

Additional Dependencies: Azure.Core, Azure.Identity, Microsoft.Identity.Client
Features: Core features + Azure authentication and integration
Best for: Projects deploying to Azure or using Azure services

<PackageReference Include="CodeMatrix.AspNetCore.Utilities.Azure" Version="1.0.0" />

🔹 Full Variant (`CodeMatrix.AspNetCore.Utilities.Full`)

All features included

Dependencies: All dependencies from above variants
Features: Complete feature set
Best for: Projects that need all features and don't mind the dependency footprint

<PackageReference Include="CodeMatrix.AspNetCore.Utilities.Full" Version="1.0.0" />

Consumer Project Examples

Example 1: Web API with Minimal Dependencies (Core Variant)

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
	<TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>
  
  <ItemGroup>
	
	<PackageReference Include="CodeMatrix.AspNetCore.Utilities" Version="1.0.0" />
  </ItemGroup>
</Project>

Available features: Extensions, Converters, Filters, Basic HTTP utilities

Example 2: Data-Heavy Application (Database Variant)

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
	<TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>
  
  <ItemGroup>
	
	<PackageReference Include="CodeMatrix.AspNetCore.Utilities.Database" Version="1.0.0" />
  </ItemGroup>
</Project>

Available features: Core features + DapperHelper, DBHelpers, Database utilities

Example 3: Microservice with HTTP Calls (Http Variant)

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
	<TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>
  
  <ItemGroup>
	
	<PackageReference Include="CodeMatrix.AspNetCore.Utilities.Http" Version="1.0.0" />
  </ItemGroup>
</Project>

Available features: Core features + Enhanced HTTP client with retry policies

Example 4: Azure-Hosted Application (Azure Variant)

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
	<TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>
  
  <ItemGroup>
	
	<PackageReference Include="CodeMatrix.AspNetCore.Utilities.Azure" Version="1.0.0" />
  </ItemGroup>
</Project>

Available features: Core features + Azure.Identity, Azure.Core integration

Example 5: Complex Application (Full Variant)

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
	<TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>
  
  <ItemGroup>
	
	<PackageReference Include="CodeMatrix.AspNetCore.Utilities.Full" Version="1.0.0" />
  </ItemGroup>
</Project>

Available features: All features included

Dependency Comparison

Variant	Package Size	Key Dependencies	Use Case
Core	~67 KB	System.Text.Json, Extensions.Http	Minimal web APIs
Database	~85 KB	Core + Dapper, SqlClient	Data applications
Http	~90 KB	Core + Polly	Microservices
Azure	~120 KB	Core + Azure.* packages	Azure applications
Full	~150 KB	All dependencies	Complex applications

Choose the smallest variant that meets your needs to minimize dependency conflicts.

Migration Guide

If you're currently using the main package and experiencing dependency conflicts:

Identify which features you actually use in your project
Choose the appropriate variant based on your needs
Replace the package reference with the specific variant
Test your application to ensure all required features are available

Getting Started

Configuring JSON Options

Add the default JSON options to your service collection in Program.cs or Startup.cs:

using CodeMatrix.AspNetCore.Utilities.DependencyInjection;

// Add default JSON serialization options
services.AddDefaultJsonOptions();

// Or with custom configuration
services.AddCustomJsonOptions(options => 
{
	options.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
	options.PropertyNameCaseInsensitive = true;
});

Setting Up HTTP Client Helper

Configure HTTP client helper for making API requests with structured HttpResult<T> responses:

using CodeMatrix.AspNetCore.Utilities.DependencyInjection;
using CodeMatrix.AspNetCore.Utilities.Interfaces;
using CodeMatrix.AspNetCore.Utilities.Models;

// Add HTTP client helper with default options
// Default: 5-minute timeout, compression enabled, SSL verification enabled
services.AddHttpClientHelper();

// Or with custom configuration
services.AddHttpClientHelper(options => 
{
	// Timeout configuration
	options.DefaultTimeoutMinutes = 3;
	
	// Compression - automatically decompress GZIP, Deflate, and Brotli responses
	options.EnableCompression = true;  // Default: true (recommended)
	
	// SSL certificate verification - set to false only for development/testing
	options.VerifySsl = true;          // Default: true (ALWAYS true in production)
	
	// Retry configuration (requires Polly integration)
	options.MaxRetryAttempts = 3;      // Retry on transient failures (5xx errors)
	options.RetryDelaySeconds = 1;     // Initial delay with exponential backoff
});

// Inject and use in your services
public class MyService 
{
	private readonly IHttpClientHelper _httpClient;
	
	public MyService(IHttpClientHelper httpClient)
	{
		_httpClient = httpClient;
	}
	
	public async Task<ApiResult<MyData>> GetDataAsync()
	{
		// All methods now return HttpResult<T> with status codes and structured responses
		HttpResult<string> result = await _httpClient.InvokeGetAsync("https://api.example.com/data");
		
		if (result.IsSuccessful)
		{
			return new ApiResult<MyData>
			{
				IsSuccessful = true,
				Data = JsonSerializer.Deserialize<MyData>(result.Data),
				Message = $"Data retrieved successfully (HTTP {result.StatusCode})"
			};
		}
		else
		{
			return new ApiResult<MyData>
			{
				IsSuccessful = false,
				Message = $"Failed to retrieve data: {result.Message} (HTTP {result.StatusCode})"
			};
		}
	}
	
	public async Task<ApiResult<string>> PostDataAsync(MyData data)
	{
		string jsonBody = JsonSerializer.Serialize(data);
		var headers = new Dictionary<string, string>
		{
			{ "X-API-Key", "your-api-key" }
		};
		
		// HttpResult includes status code and error handling without exceptions
		HttpResult<string> result = await _httpClient.InvokePostAsync(
			"https://api.example.com/data", 
			jsonBody, 
			headers, 
			timeoutInMinutes: 5
		);
		
		return new ApiResult<string>
		{
			IsSuccessful = result.IsSuccessful,
			Data = result.Data,
			Message = result.Message
		};
	}
}

Target Framework and Dependencies

Target Framework: .NET 8.0
Key Dependencies:
- Dapper 2.1.28
- Microsoft.Data.SqlClient 6.0.2
- Microsoft.Extensions.Http.Polly 9.0.5
- Polly 8.5.2

For the complete list of dependencies, check the .csproj file.

CodeMatrix.AspNetCore.Utilities

Attributes

DbParamAttribute

Description: Represents an attribute that specifies the name of a database parameter.

Namespace: CodeMatrix.AspNetCore.Utilities.Attributes

Usage:

The DbParamAttribute can be applied to properties or fields to specify the name of the corresponding database parameter. This can be useful in scenarios where you need to map class properties to database parameters for data access operations.

Signature:

[AttributeUsage(AttributeTargets.Property | AttributeTargets.Field, AllowMultiple = false)] 

public class DbParamAttribute : Attribute  
{  
	public string Name { get; set; }
	public DbParamAttribute(string name);
}

Example:

using CodeMatrix.AspNetCore.Utilities.Attributes;

public class User { 

	[DbParam("user_id")] 
	public int Id { get; set; }

	[DbParam("user_name")]
	public string Name { get; set; }

	[DbParam("user_email")]
	public string Email { get; set; }
}

In this example, the DbParamAttribute is used to specify the database parameter names for the Id, Name, and Email properties of the User class. When performing database operations, these attributes can be used to map the class properties to the corresponding database parameters.

Converters

BooleanJsonConverter

Description: Converts a nullable boolean value to and from JSON.

Namespace: CodeMatrix.AspNetCore.Utilities.Converters

Usage:

The BooleanJsonConverter can be used to handle nullable boolean values when serializing and deserializing JSON. This converter supports various representations of boolean values, such as "true", "yes", "y", "1" for true and "false", "no", "n", "0" for false.

Signature:

public class BooleanJsonConverter : JsonConverter<bool?> { 
	public override bool? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options); 
	public override void Write(Utf8JsonWriter writer, bool? value, JsonSerializerOptions options); 
}

Example:

using System.Text.Json; 
using System.Text.Json.Serialization; 
using CodeMatrix.AspNetCore.Utilities.Converters;

public class Example { 
	[JsonConverter(typeof(BooleanJsonConverter))] 
	public bool? IsActive { get; set; } 
}

public class Program { 
	public static void Main() { 
		var json = "{\"IsActive\":\"yes\"}"; 
		var options = new JsonSerializerOptions { Converters = { new BooleanJsonConverter() } };

		var example = JsonSerializer.Deserialize<Example>(json, options);
		Console.WriteLine(example?.IsActive); // Output: True

		var serializedJson = JsonSerializer.Serialize(example, options);
		Console.WriteLine(serializedJson); // Output: {"IsActive":true}
	}
}

In this example, the BooleanJsonConverter is used to handle the IsActive property of the Example class. The converter allows the property to be deserialized from various string representations of boolean values and serialized back to JSON.

DateTimeJsonConverter

Description: Converts a nullable DateTime to and from JSON using configurable date formats.

Namespace: CodeMatrix.AspNetCore.Utilities.Converters

Usage:

The DateTimeJsonConverter can be used to handle nullable DateTime values when serializing and deserializing JSON. This converter supports various input date formats and a configurable output date format. It has enhanced handling for fractional seconds with support for different precision levels (1-7 digits) and automatically normalizes them to millisecond precision.

Signature:

public class DateTimeJsonConverter : JsonConverter<DateTime?> { 
	public DateTimeJsonConverter(); 
	public DateTimeJsonConverter(string outputFormat, bool useUtc = false); 
	public DateTimeJsonConverter(string[] inputFormats, string outputFormat, bool useUtc = false); 
	public override DateTime? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options); 
	public override void Write(Utf8JsonWriter writer, DateTime? value, JsonSerializerOptions options); 
}

Examples:

Below are comprehensive examples demonstrating the various ways to use DateTimeJsonConverter:

Example 1: Default Usage (Property Attribute)

using System;
using System.Text.Json;
using System.Text.Json.Serialization;
using CodeMatrix.AspNetCore.Utilities.Converters;

public class Example
{
	// Uses default format (dd/MM/yyyy HH:mm:ss)
	[JsonConverter(typeof(DateTimeJsonConverter))]
	public DateTime? EventDate { get; set; }

	// Using a custom format
	[JsonConverter(typeof(DateTimeJsonConverter), "yyyy-MM-dd")]
	public DateTime? DateOnly { get; set; }
}

public class Program
{
	public static void Main()
	{
		// Deserializing with various date formats
		var json = "{\"EventDate\":\"2022-01-01T12:00:00\",\"DateOnly\":\"2022-05-15\"}";
		var example = JsonSerializer.Deserialize<Example>(json);
		
		Console.WriteLine(example?.EventDate); // Output: 01/01/2022 12:00:00
		Console.WriteLine(example?.DateOnly); // Output: 15/05/2022 00:00:00

		// Serializing back to JSON
		var serializedJson = JsonSerializer.Serialize(example);
		Console.WriteLine(serializedJson); 
		// Output: {"EventDate":"01/01/2022 12:00:00","DateOnly":"2022-05-15"}
	}
}

Example 2: Using JsonSerializerOptions

using System;
using System.Text.Json;
using System.Text.Json.Serialization;
using CodeMatrix.AspNetCore.Utilities.Converters;

public class Event
{
	public DateTime? StartDate { get; set; }
	public DateTime? EndDate { get; set; }
}

public class Program
{
	public static void Main()
	{
		// JSON with different date formats
		var json = @"{
			""StartDate"": ""2022-06-01T09:00:00"",
			""EndDate"": ""01/07/2022 17:30:00""
		}";

		// Setup options with default converter
		var defaultOptions = new JsonSerializerOptions { 
			Converters = { new DateTimeJsonConverter() }
		};
		
		// Setup options with custom format
		var customOptions = new JsonSerializerOptions { 
			Converters = { new DateTimeJsonConverter("MM/dd/yyyy") }
		};

		// Setup options with UTC conversion
		var utcOptions = new JsonSerializerOptions { 
			Converters = { new DateTimeJsonConverter("yyyy-MM-dd'T'HH:mm:ss'Z'", true) }
		};

		// Deserialize with default options
		var eventObj = JsonSerializer.Deserialize<Event>(json, defaultOptions);
		Console.WriteLine($"Default format - Start: {eventObj?.StartDate}, End: {eventObj?.EndDate}");
		// Output: Default format - Start: 01/06/2022 09:00:00, End: 01/07/2022 17:30:00

		// Serialize with different formats
		Console.WriteLine(JsonSerializer.Serialize(eventObj, defaultOptions));
		// Output: {"StartDate":"01/06/2022 09:00:00","EndDate":"01/07/2022 17:30:00"}

		Console.WriteLine(JsonSerializer.Serialize(eventObj, customOptions));
		// Output: {"StartDate":"06/01/2022","EndDate":"07/01/2022"}

		Console.WriteLine(JsonSerializer.Serialize(eventObj, utcOptions));
		// Output: {"StartDate":"2022-06-01T09:00:00Z","EndDate":"2022-07-01T17:30:00Z"}
	}
}

Example 3: Using Custom Input Formats

using System;
using System.Text.Json;
using CodeMatrix.AspNetCore.Utilities.Converters;

public class Meeting
{
	public DateTime? ScheduledTime { get; set; }
}

public class Program
{
	public static void Main()
	{
		// Define specific input formats you want to support
		string[] customFormats = new[] {
			"MM/dd/yy HH:mm", 
			"dd-MMM-yyyy HH:mm:ss",
			"yyyy.MM.dd"
		};

		// Create converter with custom input/output formats
		var converter = new DateTimeJsonConverter(
			inputFormats: customFormats,
			outputFormat: "dd MMM yyyy HH:mm:ss"
		);
		
		var options = new JsonSerializerOptions { 
			Converters = { converter }
		};

		// Parse various format examples
		string[] jsonExamples = {
			@"{""ScheduledTime"": ""06/17/25 14:30""}",
			@"{""ScheduledTime"": ""17-Jun-2025 14:30:00""}",
			@"{""ScheduledTime"": ""2025.06.17""}"
		};

		foreach (var jsonExample in jsonExamples)
		{
			var meeting = JsonSerializer.Deserialize<Meeting>(jsonExample, options);
			Console.WriteLine($"Parsed: {meeting?.ScheduledTime}");
			
			var serialized = JsonSerializer.Serialize(meeting, options);
			Console.WriteLine($"Serialized: {serialized}");
		}
		
		// Output:
		// Parsed: 17 Jun 2025 14:30:00
		// Serialized: {"ScheduledTime":"17 Jun 2025 14:30:00"}
		// Parsed: 17 Jun 2025 14:30:00
		// Serialized: {"ScheduledTime":"17 Jun 2025 14:30:00"}  
		// Parsed: 17 Jun 2025 00:00:00
		// Serialized: {"ScheduledTime":"17 Jun 2025 00:00:00"}
	}
}

Example 4: Common Format Handling

The DateTimeJsonConverter supports numerous common date formats out of the box, including flexible handling of fractional seconds. Here are some examples:

using System;
using System.Text.Json;
using CodeMatrix.AspNetCore.Utilities.Converters;

public class DateExample
{
	public string Format { get; set; }
	public DateTime? Date { get; set; }
}

public class Program
{
	public static void Main()
	{
		// Create options with the converter
		var options = new JsonSerializerOptions { 
			Converters = { new DateTimeJsonConverter() }
		};

		// Array of date formats with examples
		var dateExamples = new[] {
			// Basic date formats
			new { Format = "ISO 8601", Json = @"{""Date"": ""2025-06-17T14:30:00""}" },
			new { Format = "Short date", Json = @"{""Date"": ""17/06/2025""}" },
			new { Format = "US date", Json = @"{""Date"": ""06/17/2025""}" },
			new { Format = "Basic", Json = @"{""Date"": ""20250617""}" },
			
			// Date time formats
			new { Format = "Standard datetime", Json = @"{""Date"": ""17/06/2025 14:30:00""}" },
			new { Format = "With milliseconds", Json = @"{""Date"": ""2025-06-17 14:30:00.123""}" },
			
			// 12-hour formats
			new { Format = "12-hour format", Json = @"{""Date"": ""06/17/2025 2:30:00 PM""}" },
			
			// RFC formats
			new { Format = "RFC format", Json = @"{""Date"": ""Tue, 17 Jun 2025 14:30:00 GMT""}" }
		};

		foreach (var example in dateExamples)
		{
			try
			{
				var obj = JsonSerializer.Deserialize<DateExample>(
					$"{{\"Format\": \"{example.Format}\", {example.Json.Substring(1)}", 
					options
				);
				
				Console.WriteLine($"{obj.Format}: {obj.Date}");
			}
			catch (JsonException ex)
			{
				Console.WriteLine($"Error parsing {example.Format}: {ex.Message}");
			}
		}
	}
}

Flexible Fractional Seconds Handling

The DateTimeJsonConverter includes enhanced handling for fractional seconds, supporting various precision levels and automatically normalizing them to millisecond precision:

using System;
using System.Text.Json;
using CodeMatrix.AspNetCore.Utilities.Converters;
using CodeMatrix.AspNetCore.Utilities.Helpers;

public class Program
{
	private class TestClass
	{
		[JsonConverter(typeof(DateTimeJsonConverter))]
		public DateTime? Value { get; set; }
	}
	
	public static void Main()
	{
		// These examples demonstrate flexible fractional seconds handling
		var examples = new[]
		{
			"2023-06-19T12:30:45.1",      // 1 digit (parsed as 100ms)
			"2023-06-19T12:30:45.12",     // 2 digits (parsed as 120ms)
			"2023-06-19T12:30:45.123",    // 3 digits (parsed as 123ms)
			"2023-06-19T12:30:45.1234",   // 4 digits (truncated to 123ms)
			"2023-06-19T12:30:45.123Z",   // With Z timezone
			"2023-06-19T12:30:45.12+02:00" // With timezone offset
		};
		
		JsonSerializerOptions options = JsonOptionsProvider.GetJsonOptions();
		
		foreach (var dateString in examples)
		{
			string json = $@"{{ ""Value"": ""{dateString}"" }}";
			TestClass? result = JsonSerializer.Deserialize<TestClass>(json, options);
			
			Console.WriteLine($"Input: {dateString}");
			Console.WriteLine($"Parsed: {result?.Value?.ToString("yyyy-MM-dd HH:mm:ss.fff")}");
			Console.WriteLine();
		}
	}
}

These examples showcase the flexibility and power of the DateTimeJsonConverter in handling different date formats, customizing output, and working with UTC conversions. The converter can handle a wide range of date formats for deserialization while providing precise control over how dates are serialized to JSON.

Example 5: Combining Custom Formats with Default Formats

using System;
using System.Text.Json;
using CodeMatrix.AspNetCore.Utilities.Converters;

public class DateExample
{
	public string Format { get; set; }
	public DateTime? Date { get; set; }
}

public class Program
{
	public static void Main()
	{
		// Define your custom formats
		string[] myCustomFormats = new[] {
			"yyyy/dd/MM", // Year first, then day, then month (unusual format)
			"MMMM d, yyyy" // Month name, day, year (e.g., "June 17, 2025")
		};
		
		// Method 1: Default behavior now combines your formats with default formats
		// Your formats are given higher priority (checked first)
		var combinedConverter = new DateTimeJsonConverter(
			inputFormats: myCustomFormats,
			outputFormat: "yyyy-MM-dd HH:mm:ss"
		);
		
		// Method 2: Explicitly control whether to include default formats
		var customOnlyConverter = new DateTimeJsonConverter(
			inputFormats: myCustomFormats,
			outputFormat: "yyyy-MM-dd HH:mm:ss",
			includeDefaultFormats: false, // Only use the custom formats
			useUtc: false
		);
		
		var combinedOptions = new JsonSerializerOptions { 
			Converters = { combinedConverter }
		};
		
		var customOnlyOptions = new JsonSerializerOptions { 
			Converters = { customOnlyConverter }
		};
		
		// Examples using the different converters
		var customFormatJson = @"{""Format"": ""Custom format"", ""Date"": ""June 17, 2025""}";
		var standardFormatJson = @"{""Format"": ""Standard format"", ""Date"": ""2025-06-17T14:30:00""}";
		
		// Combined converter can handle both custom and standard formats
		var customDate = JsonSerializer.Deserialize<DateExample>(customFormatJson, combinedOptions);
		Console.WriteLine($"Combined converter with custom format: {customDate?.Date}");
		
		var standardDate = JsonSerializer.Deserialize<DateExample>(standardFormatJson, combinedOptions);  
		Console.WriteLine($"Combined converter with standard format: {standardDate?.Date}");
		
		// Custom-only converter can only handle the custom formats
		try {
			var customOnlyDate = JsonSerializer.Deserialize<DateExample>(customFormatJson, customOnlyOptions);
			Console.WriteLine($"Custom-only converter with custom format: {customOnlyDate?.Date}");
			
			var willFail = JsonSerializer.Deserialize<DateExample>(standardFormatJson, customOnlyOptions);
			Console.WriteLine("This line won't execute");
		}
		catch (JsonException) {
			Console.WriteLine("Custom-only converter failed with standard format (as expected)");
		}
	}
}

This example demonstrates how the DateTimeJsonConverter now automatically combines your custom formats with the default formats, giving priority to your custom formats. It also shows how to use the new constructor parameter includeDefaultFormats to explicitly control whether default formats should be included.

DateTimeOffsetJsonConverter

Description: Converts a nullable DateTimeOffset to and from JSON using configurable date formats.

Namespace: CodeMatrix.AspNetCore.Utilities.Converters

Usage:

The DateTimeOffsetJsonConverter can be used to handle nullable DateTimeOffset values when serializing and deserializing JSON. This converter supports various input date formats including timezone information and a configurable output date format.

Signature:

public class DateTimeOffsetJsonConverter : JsonConverter<DateTimeOffset?> { 
	public DateTimeOffsetJsonConverter(); 
	public DateTimeOffsetJsonConverter(string outputFormat, bool preserveOffset = true); 
	public DateTimeOffsetJsonConverter(string[] inputFormats, string outputFormat, bool preserveOffset = true); 
	public override DateTimeOffset? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options); 
	public override void Write(Utf8JsonWriter writer, DateTimeOffset? value, JsonSerializerOptions options); 
}

Example:

using System; 
using System.Text.Json; 
using System.Text.Json.Serialization; 
using CodeMatrix.AspNetCore.Utilities.Converters;

public class Example { 
	[JsonConverter(typeof(DateTimeOffsetJsonConverter))] 
	public DateTimeOffset? EventDate { get; set; } 
}

public class Program { 
	public static void Main() { 
		var json = "{\"EventDate\":\"2022-01-01T12:00:00+05:30\"}"; 
		var options = new JsonSerializerOptions { 
			Converters = { new DateTimeOffsetJsonConverter() } 
		};

		var example = JsonSerializer.Deserialize<Example>(json, options);
		Console.WriteLine(example?.EventDate); // Output: 01/01/2022 12:00:00 +05:30

		var serializedJson = JsonSerializer.Serialize(example, options);
		Console.WriteLine(serializedJson); // Output: {"EventDate":"2022-01-01T12:00:00+05:30"}
		
		// Use custom format and normalize to UTC
		var utcOptions = new JsonSerializerOptions { 
			Converters = { new DateTimeOffsetJsonConverter("yyyy-MM-dd'T'HH:mm:ss'Z'", false) } 
		};
		
		var serializedUtc = JsonSerializer.Serialize(example, utcOptions);
		Console.WriteLine(serializedUtc); // Output: {"EventDate":"2022-01-01T06:30:00Z"}
	}
}

In this example, the DateTimeOffsetJsonConverter is used to handle the EventDate property with timezone information. The converter preserves the original offset by default but can also normalize to UTC if needed.

NumberToStringJsonConverter

Description: Converts a number or string to a JSON string representation.

Namespace: CodeMatrix.AspNetCore.Utilities.Converters

Usage:

The NumberToStringJsonConverter can be used to handle numbers and strings when serializing and deserializing JSON. This converter ensures that numbers are converted to their string representation in JSON.

Signature:

public class NumberToStringJsonConverter : JsonConverter { 
	public override bool CanConvert(Type typeToConvert); 
	public override string? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options); 
	public override void Write(Utf8JsonWriter writer, string value, JsonSerializerOptions options); 
}

Example:

using System; 
using System.Text.Json; 
using System.Text.Json.Serialization; 
using CodeMatrix.AspNetCore.Utilities.Converters;

public class Example { 
	[JsonConverter(typeof(NumberToStringJsonConverter))] 
	public string? Value { get; set; }
}
	public class Program { 
	public static void Main() { 
		var json = "{\"Value\":12345}"; 
		var options = new JsonSerializerOptions { Converters = { new NumberToStringJsonConverter() } };

		var example = JsonSerializer.Deserialize<Example>(json, options);
		Console.WriteLine(example?.Value); // Output: "12345"

		var serializedJson = JsonSerializer.Serialize(example, options);
		Console.WriteLine(serializedJson); // Output: {"Value":"12345"}
	}
}

In this example, the NumberToStringJsonConverter is used to handle the Value property of the Example class. The converter allows the property to be deserialized from a number and serialized back to JSON as a string.

Extensions

BoolExtension

Description: Provides extension methods for boolean values.

Namespace: CodeMatrix.AspNetCore.Utilities.Extensions

Usage:

The ToYesNo extension method can be used to convert a boolean value to a "Yes" or "No" string representation.

Signature:

public static partial class Extensions { 
	public static string ToYesNo(this bool @this); 
}

Method: ToYesNo

Description: Converts a boolean value to a "Yes" or "No" string representation.

Example:

using System; 
using CodeMatrix.AspNetCore.Utilities.Extensions;

public class Program { 
	public static void Main() { 
		bool isActive = true; 
		string result = isActive.ToYesNo();
		Console.WriteLine(result); // Output: "Yes"

		isActive = false; 
		result = isActive.ToYesNo(); 
		Console.WriteLine(result); // Output: "No"
	}
}

Method: ToYesNo (bool?)

Description: Converts a nullable boolean value to a "Yes" or "No" string representation.

Signature:

public static string ToYesNo(this bool? @this);

Example:

using System;
using CodeMatrix.AspNetCore.Utilities.Extensions;

public class Program
{
	public static void Main()
	{
		bool? isActive = true;
		string result = isActive.ToYesNo();
		Console.WriteLine(result); // Output: "Yes"

		isActive = false;
		result = isActive.ToYesNo();
		Console.WriteLine(result); // Output: "No"

		isActive = null;
		result = isActive.ToYesNo();
		Console.WriteLine(result); // Output: "No"
	}
}

CollectionExtension

Description: Provides extension methods for collections.

Namespace: CodeMatrix.AspNetCore.Utilities.Extensions

Usage:

The CollectionExtension class provides methods to convert collections to dictionaries.

Methods:

ToDictionary (IFormCollection)

Description: Converts an IFormCollection to a dictionary.

Signature:

public static IDictionary<string, object> ToDictionary(this IFormCollection @this);

Example:

using System; 
using System.Collections.Generic; 
using Microsoft.AspNetCore.Http; 
using CodeMatrix.AspNetCore.Utilities.Extensions;

public class Program { 
	public static void Main() { 
		IFormCollection formCollection = new FormCollection(new Dictionary<string, Microsoft.Extensions.Primitives.StringValues> { { "Key1", "Value1" }, { "Key2", "Value2" } });
		IDictionary<string, object> dictionary = formCollection.ToDictionary();
		foreach (var kvp in dictionary)
		{
			Console.WriteLine($"{kvp.Key}: {kvp.Value}");
		}
		// Output:
		// Key1: Value1
		// Key2: Value2
	}
}

ToDictionary (NameValueCollection)

Description: Converts a NameValueCollection to a dictionary.

Signature:

public static IDictionary<string, object> ToDictionary(this NameValueCollection @this);

Example:

using System; 
using System.Collections.Generic; 
using System.Collections.Specialized; 
using CodeMatrix.AspNetCore.Utilities.Extensions;

public class Program { 
	public static void Main() { 
		NameValueCollection nameValueCollection = new NameValueCollection { { "Key1", "Value1" }, { "Key2", "Value2" } };
		IDictionary<string, object> dictionary = nameValueCollection.ToDictionary();
		foreach (var kvp in dictionary)
		{
			Console.WriteLine($"{kvp.Key}: {kvp.Value}");
		}
		// Output:
		// Key1: Value1
		// Key2: Value2
	}
}

DateTimeExtension

Description: Provides extension methods for DateTime.

Namespace: CodeMatrix.AspNetCore.Utilities.Extensions

Usage:

The DateTimeExtension class provides methods to convert DateTime and nullable DateTime instances to formatted date strings.

Methods:

ToDateString (DateTime)

Description: Converts the DateTime to a formatted date string.

Signature:

public static string ToDateString(this DateTime @this);

Example:

using System; 
using CodeMatrix.AspNetCore.Utilities.Extensions;

public class Program { 
	public static void Main() { 
		DateTime now = DateTime.Now; 
		string formattedDate = now.ToDateString(); 
		Console.WriteLine(formattedDate); // Output: "2023-10-15 14:30:00.000" (example) 
	} 
}

ToDateString (DateTime?)

Description: Converts the nullable DateTime to a formatted date string.

Signature:

public static string? ToDateString(this DateTime? @this);

Example:

using System; 
using CodeMatrix.AspNetCore.Utilities.Extensions;

public class Program { 
	public static void Main() { 
		DateTime? now = DateTime.Now; 
		string? formattedDate = now.ToDateString(); 
		Console.WriteLine(formattedDate); // Output: "2023-10-15 14:30:00.000" (example)

		DateTime? nullDate = null; 
		formattedDate = nullDate.ToDateString(); 
		Console.WriteLine(formattedDate); // Output: (null)
	}
}

ToDateString (DateTime?, string)

Description: Converts the nullable DateTime to a formatted date string using the specified format.

Signature:

public static string ToDateString(this DateTime? @this, string dateFormat);

Example:

using System; 
using CodeMatrix.AspNetCore.Utilities.Extensions;

public class Program { 
	public static void Main() { 
		DateTime? now = DateTime.Now; 
		string formattedDate = now.ToDateString("MM/dd/yyyy"); 
		Console.WriteLine(formattedDate); // Output: "10/15/2023" (example)

		DateTime? nullDate = null; 
		formattedDate = nullDate.ToDateString("MM/dd/yyyy"); 
		Console.WriteLine(formattedDate); // Output: "" (empty string)
	}
}

ToShortDateString (DateTime)

Description: Converts the DateTime to a formatted short date string.

Signature:

public static string ToShortDateString(this DateTime @this);

Example:

using System; 
using CodeMatrix.AspNetCore.Utilities.Extensions;

public class Program { 
	public static void Main() { 
		DateTime now = DateTime.Now; 
		string shortDate = now.ToShortDateString(); 
		Console.WriteLine(shortDate); // Output: "2023-10-15" (example)
	}
}

ToShortDateString (DateTime?)

Description: Converts the nullable DateTime to a formatted short date string.

Signature:

public static string ToShortDateString(this DateTime? @this);

Example:

using System; 
using CodeMatrix.AspNetCore.Utilities.Extensions;

public class Program { 
	public static void Main() { 
		DateTime? now = DateTime.Now; 
		string shortDate = now.ToShortDateString(); 
		Console.WriteLine(shortDate); // Output: "2023-10-15" (example)

		DateTime? nullDate = null; 
		shortDate = nullDate.ToShortDateString(); 
		Console.WriteLine(shortDate); // Output: "" (empty string)
	}
}

ToIndianStandardDateTime (DateTime)

Description: Converts the specified DateTime to Indian Standard Time (IST).

Signature:

public static DateTime ToIndianStandardDateTime(this DateTime @this);

Example:

using System; 
using CodeMatrix.AspNetCore.Utilities.Extensions;

public class Program { 
	public static void Main() { 
		DateTime utcNow = DateTime.UtcNow; 
		DateTime istNow = utcNow.ToIndianStandardDateTime(); 
		Console.WriteLine(istNow); // Output: IST time equivalent of UTC time
	}
}

ExceptionExtension

Description: Provides extension methods for handling exceptions.

Namespace: CodeMatrix.AspNetCore.Utilities.Extensions

Usage:

The ExceptionExtension class provides a method to convert exceptions to API result objects.

Methods:

ToApiResult

Description: Converts an exception to an API result.

Signature:

public static ApiResult<T> ToApiResult<T>(this Exception ex, IHostEnvironment env);

Example:

using System; 
using Microsoft.Extensions.Hosting; 
using CodeMatrix.AspNetCore.Utilities.Extensions; 
using CodeMatrix.AspNetCore.Utilities.Models;

public class Program { 
	public static void Main() { 
		IHostEnvironment env = new HostEnvironment { EnvironmentName = Environments.Development }; 
		try { 
			// Simulate an exception
			throw new InvalidOperationException("An error occurred."); 
		} 
		catch (Exception ex) { 
			ApiResult<string> result = ex.ToApiResult<string>(env); 
			Console.WriteLine($"IsSuccessful: {result.IsSuccessful}"); 
			Console.WriteLine($"Message: {result.Message}"); 
		} 
	} 
}

HostEnvironmentExtension

Description: Provides extension methods for IHostEnvironment.

Namespace: CodeMatrix.AspNetCore.Utilities.Extensions

Usage:

The HostEnvironmentExtension class provides a method to check if the current host environment is UAT (User Acceptance Testing).

Methods:

IsUAT

Description: Checks if the current host environment name is UAT.

Signature:

public static bool IsUAT(this IHostEnvironment hostEnvironment);

Example:

using System; 
using Microsoft.Extensions.Hosting; 
using CodeMatrix.AspNetCore.Utilities.Extensions;

public class Program { 
	public static void Main() { 
		// Test with UAT environment
		IHostEnvironment env = new HostEnvironment { EnvironmentName = "UAT" }; 
		bool isUAT = env.IsUAT(); 
		Console.WriteLine($"Is UAT Environment: {isUAT}"); // Output: Is UAT Environment: True
		
		// Test with Production environment
		env.EnvironmentName = "Production";
		isUAT = env.IsUAT();
		Console.WriteLine($"Is UAT Environment: {isUAT}"); // Output: Is UAT Environment: False
		
		// Test with Development environment
		env.EnvironmentName = "Development";
		isUAT = env.IsUAT();
		Console.WriteLine($"Is UAT Environment: {isUAT}"); // Output: Is UAT Environment: False
	}
}

JsonExtension

Description: Provides extension methods for working with JsonElement.

Namespace: CodeMatrix.AspNetCore.Utilities.Extensions

Usage:

The JsonExtension class provides methods to retrieve properties or elements from a JsonElement.

Methods:

GetByName

Description: Retrieves a property from the JsonElement by its name.

Signature:

public static JsonElement? GetByName(this JsonElement element, string name);

Example:

using System.Text.Json; 
using CodeMatrix.AspNetCore.Utilities.Extensions;

public class Program { 
	public static void Main() { 
		string json = "{\"name\":\"John\",\"age\":30}";
		JsonDocument doc = JsonDocument.Parse(json);
		JsonElement? nameElement = doc.RootElement.GetByName("name");
		Console.WriteLine(nameElement?.GetString()); // Output: John
	}
}

GetByIndex

Description: Retrieves an element from the JsonElement array by its index.

Signature:

public static JsonElement? GetByIndex(this JsonElement element, int index);

Example:

using System.Text.Json; 
using CodeMatrix.AspNetCore.Utilities.Extensions;

public class Program { 
	public static void Main() { 
		string json = "[\"apple\",\"banana\",\"cherry\"]";
		JsonDocument doc = JsonDocument.Parse(json);
		JsonElement? element = doc.RootElement.GetByIndex(1);
		Console.WriteLine(element?.GetString()); // Output: banana
	}
}

GetByPath

Description: Retrieves a nested property or element from the JsonElement by a dot-separated path.

Signature:

public static JsonElement? GetByPath(this JsonElement jsonElement, string path);

Example:

using System.Text.Json; 
using CodeMatrix.AspNetCore.Utilities.Extensions;

public class Program { 
	public static void Main() { 
		string json = "{\"person\":{\"name\":\"John\",\"age\":30}}";
		JsonDocument doc = JsonDocument.Parse(json);
		JsonElement? nameElement = doc.RootElement.GetByPath("person.name");
		Console.WriteLine(nameElement?.GetString()); // Output: John
	}
}

ModelStateExtension

Description: Provides extension methods for ModelStateDictionary.

Namespace: CodeMatrix.AspNetCore.Utilities.Extensions

Usage:

The ModelStateExtension class provides a method to convert errors in the ModelStateDictionary to a string.

Methods:

ErrorsToString

Description: Converts the errors in the ModelStateDictionary to a string. Returns an empty string if there are no errors.

Signature:

public static string ErrorsToString(this ModelStateDictionary modelState);

Example:

using Microsoft.AspNetCore.Mvc.ModelBinding; 
using CodeMatrix.AspNetCore.Utilities.Extensions;
public class Program { 
	public static void Main() { 
		ModelStateDictionary modelState = new ModelStateDictionary();
		modelState.AddModelError("Name", "Name is required.");
		string errors = modelState.ErrorsToString();
		Console.WriteLine(errors); // Output: Name is required.
		
		// With no errors
		ModelStateDictionary validState = new ModelStateDictionary();
		string noErrorsResult = validState.ErrorsToString(); // Returns empty string instead of null
	}
}

ObjectExtension

Description: Provides extension methods for object.

Namespace: CodeMatrix.AspNetCore.Utilities.Extensions

Usage:

The ObjectExtension class provides methods to serialize objects to JSON and retrieve properties as a dictionary.

Methods:

ToSafeString (object)

Description: Converts the object to a safe string representation.

Signature:

public static string? ToSafeString(this object @this);

Example:

using CodeMatrix.AspNetCore.Utilities.Extensions;

public class Program { 
	public static void Main() { 
		object obj = null;
		string? safeString = obj.ToSafeString();
		Console.WriteLine(safeString); // Output: (null)
	}
}

Serialize

Description: Serializes an object to a JSON string using the default JSON serializer options.

Signature:

public static string Serialize<T>(this T @this);

Example:

using CodeMatrix.AspNetCore.Utilities.Extensions;

public class Program { 
	public static void Main() { 
		var obj = new { Name = "John", Age = 30 };
		string json = obj.Serialize();
		Console.WriteLine(json); // Output: {"Name":"John","Age":30}
	}
}

GetPropertiesAsDictionary

Description: Gets the properties of an object as a dictionary.

Signature:

public static Dictionary<string, object?> GetPropertiesAsDictionary<T>(this T @this);

Example:

using CodeMatrix.AspNetCore.Utilities.Extensions;

public class Program { 
	public static void Main() { 
		var obj = new { Name = "John", Age = 30 };
		var properties = obj.GetPropertiesAsDictionary();
		foreach (var kvp in properties)
		{
			Console.WriteLine($"{kvp.Key}: {kvp.Value}");
		}
		// Output:
		// Name: John
		// Age: 30
	}
}

StreamExtension

Description: Provides extension methods for Stream.

Namespace: CodeMatrix.AspNetCore.Utilities.Extensions

Usage:

The StreamExtension class provides a method to convert a stream to a base64 string.

Methods:

ConvertToBase64

Description: Converts the stream to a base64 string. The stream position is reset to the beginning after conversion.

Signature:

public static string ConvertToBase64(this Stream stream);

Example:

using System.IO; 
using CodeMatrix.AspNetCore.Utilities.Extensions;

public class Program { 
	public static void Main() { 
		using (var stream = new MemoryStream(new byte[] { 1, 2, 3, 4 }))
		{
			string base64 = stream.ConvertToBase64();
			Console.WriteLine(base64); // Output: AQIDBA==
		}
	}
}

StringExtension

Description: Provides extension methods for string manipulation.

Namespace: CodeMatrix.AspNetCore.Utilities.Extensions

Usage:

The StringExtension class provides methods to check for null or empty strings, convert strings, and deserialize JSON strings.

Method: IsNullOrEmpty

Description: Determines whether the specified string is null or empty.

Signature:

public static bool IsNullOrEmpty(this string @this);

Example:

using CodeMatrix.AspNetCore.Utilities.Extensions;

public class Program { 
	public static void Main() { 
		string str = null;
		bool isNullOrEmpty = str.IsNullOrEmpty();
		Console.WriteLine(isNullOrEmpty); // Output: True
	}
}

Method: IsNullOrEmptyToNull

Description: Converts a null or empty string to null.

Signature:

public static string? IsNullOrEmptyToNull(this string value);

Example:

using CodeMatrix.AspNetCore.Utilities.Extensions;

public class Program { 
	public static void Main() { 
		string str = "";
		string? result = str.IsNullOrEmptyToNull();
		Console.WriteLine(result == null); // Output: True
	}
}

Method: ToSafeString (string)

Description: Converts the string to a safe string representation (returns empty string if null).

Signature:

public static string ToSafeString(this string @this);

Example:

using CodeMatrix.AspNetCore.Utilities.Extensions;

public class Program { 
	public static void Main() { 
		string str = null;
		string safeString = str.ToSafeString();
		Console.WriteLine(safeString); // Output: ""
	}
}

Method: ToSafeInt

Description: Converts the string to a safe integer representation.

Signature:

public static int ToSafeInt(this string @this);

Example:

using CodeMatrix.AspNetCore.Utilities.Extensions;

public class Program { 
	public static void Main() { 
		string str = "123";
		int result = str.ToSafeInt();
		Console.WriteLine(result); // Output: 123
	}
}

Method: Replace

Description: Replaces all occurrences of a specified string with a specified replacement value.

Signature:

public static string Replace(this string @this, string oldValue, object replacementValue);

Example:

using CodeMatrix.AspNetCore.Utilities.Extensions;

public class Program { 
	public static void Main() { 
		string str = "Hello, World!";
		string result = str.Replace("World", "C#");
		Console.WriteLine(result); // Output: Hello, C#!
	}
}

Method: RemoveUnicodeChars

Description: Removes Unicode characters from the string.

Signature:

public static string RemoveUnicodeChars(this string @this);

Example:

using CodeMatrix.AspNetCore.Utilities.Extensions;

public class Program { 
	public static void Main() { 
		string str = "Hello \\u0041\\u0042\\u0043!";
		string result = str.RemoveUnicodeChars();
		Console.WriteLine(result); // Output: Hello ABC!
	}
}

Method: SplitProperCase

Description: Splits a PascalCase or camelCase string into separate words with proper casing.

Signature:

public static string SplitProperCase(this string @this);

Example:

using CodeMatrix.AspNetCore.Utilities.Extensions;

public class Program { 
	public static void Main() { 
		string str = "PascalCaseExample";
		string result = str.SplitProperCase();
		Console.WriteLine(result); // Output: Pascal Case Example
	}
}

Method: ToDateTime

Description: Converts the string to a DateTime object using the date-time format - "yyyy-MM-dd HH:mm:ss".

Signature:

public static DateTime ToDateTime(this string @this);

Example:

using CodeMatrix.AspNetCore.Utilities.Extensions;

public class Program { 
	public static void Main() { 
		string str = "2023-10-15 14:30:00";
		DateTime dateTime = str.ToDateTime();
		Console.WriteLine(dateTime); // Output: 10/15/2023 14:30:00
	}
}

Method: ToIndianStandardDateTime (string)

Description: Converts the string to a DateTime object in Indian Standard Time (IST).

Signature:

public static DateTime ToIndianStandardDateTime(this string @this);

Example:

using CodeMatrix.AspNetCore.Utilities.Extensions;

public class Program { 
	public static void Main() { 
		string str = "2023-10-15 14:30:00";
		DateTime istDateTime = str.ToIndianStandardDateTime();
		Console.WriteLine(istDateTime); // Output: IST equivalent of the given time
	}
}

Method: Deserialize

Description: Deserializes the JSON string to the specified type.

Signature:

public static T? Deserialize<T>(this string @this);

Example:

using CodeMatrix.AspNetCore.Utilities.Extensions;
public class Program { 
	public static void Main() { 
		string json = "{\"Name\":\"John\",\"Age\":30}";
		var obj = json.Deserialize<dynamic>();
		Console.WriteLine(obj.Name); // Output: John
	}
}

XmlExtension

Description: Provides extension methods for XML-related operations.

Namespace: CodeMatrix.AspNetCore.Utilities.Extensions

Usage:

The XmlExtension class provides methods to deserialize XML nodes and convert between XDocument and XmlDocument.

Methods:

DeserializeXmlNode

Description: Deserializes the specified XmlNode into an object of type T.

Signature:

public static T? DeserializeXmlNode<T>(this XmlNode @this);

Example:

using System.Xml; 
using CodeMatrix.AspNetCore.Utilities.Extensions;

public class Program { 
	public static void Main() { 
		string xml = "<Person><Name>John</Name><Age>30</Age></Person>";
		XmlDocument doc = new XmlDocument();
		doc.LoadXml(xml);
		var person = doc.DocumentElement.DeserializeXmlNode<dynamic>();
		Console.WriteLine(person.Name); // Output: John
	}
}

ToXmlDocument

Description: Converts the specified XDocument to an XmlDocument.

Signature:

public static XmlDocument ToXmlDocument(this XDocument xDocument);

Example:

using System.Xml; 
using System.Xml.Linq; 
using CodeMatrix.AspNetCore.Utilities.Extensions;

public class Program { 
	public static void Main() { 
		XDocument xDoc = new XDocument(new XElement("Root", new XElement("Child", "Value")));
		XmlDocument xmlDoc = xDoc.ToXmlDocument();
		Console.WriteLine(xmlDoc.OuterXml); // Output: <Root><Child>Value</Child></Root>
	}
}

ToXDocument

Description: Converts the specified XmlDocument to an XDocument.

Signature:

public static XDocument ToXDocument(this XmlDocument xmlDocument);

Example:

using System.Xml; 
using System.Xml.Linq; 
using CodeMatrix.AspNetCore.Utilities.Extensions;

public class Program { 
	public static void Main() { 
		XmlDocument xmlDoc = new XmlDocument();
		xmlDoc.LoadXml("<Root><Child>Value</Child></Root>");
		XDocument xDoc = xmlDoc.ToXDocument();
		Console.WriteLine(xDoc); // Output: <Root><Child>Value</Child></Root>
	}
}

Filters

ModelStateValidationFilter

Description: Filter that validates the model state of an action before execution.

Namespace: CodeMatrix.AspNetCore.Utilities.Filters

Usage:

The ModelStateValidationFilter validates the model state before the action is executed. If the model state is invalid, it returns an OkObjectResult with an ApiResult<string> containing the error messages and prevents the action from executing.

Signature:

public class ModelStateValidationFilter : ActionFilterAttribute
{
	public override void OnActionExecuting(ActionExecutingContext context);
}

Example:

using System;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Filters;
using CodeMatrix.AspNetCore.Utilities.Filters;

public class Program
{
	public static void Main()
	{
		var filter = new ModelStateValidationFilter();
		Console.WriteLine("ModelStateValidationFilter applied.");
	}
}

ModelStateValidationAsyncFilter

Description: Filter that validates the model state before and after the controller action execution.

Namespace: CodeMatrix.AspNetCore.Utilities.Filters

Usage:

The ModelStateValidationAsyncFilter validates the model state asynchronously before the action is executed. If the model state is invalid, it returns an OkObjectResult with an ApiResult<string> containing the error messages and prevents the action from executing.

Signature:

public class ModelStateValidationAsyncFilter : IAsyncActionFilter
{
	public Task OnActionExecutionAsync(ActionExecutingContext context, ActionExecutionDelegate next);
}

Example:

using System;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Filters;
using CodeMatrix.AspNetCore.Utilities.Filters;

public class Program
{
	public static async Task Main()
	{
		var filter = new ModelStateValidationAsyncFilter();
		Console.WriteLine("ModelStateValidationAsyncFilter applied.");
	}
}

Helpers

DbHelpers

Description: Provides helper methods for database operations.

Namespace: CodeMatrix.AspNetCore.Utilities.Helpers

Usage:

The DbHelpers class provides various methods to convert and map data from databases to strongly-typed objects.

Method: ConvertDataTable<T>

Description: Converts a DataTable to a list of objects.

Signature:

public static List<T> ConvertDataTable<T>(DataTable dt) where T : new()

Example:

using System;
using System.Data;
using System.Collections.Generic;
using CodeMatrix.AspNetCore.Utilities.Helpers;

public class Program
{
	public static void Main()
	{
		DataTable dt = new DataTable();
		// Add columns and rows to DataTable
		
		List<MyClass> list = DbHelpers.ConvertDataTable<MyClass>(dt);
		Console.WriteLine($"Converted {list.Count} rows to objects.");
	}
}

Method: ConvertDataTable<T>

Description: Converts a DataTable to a list of objects using a specified mapper type.

Signature:

public static List<T> ConvertDataTable<T>(DataTable dt, Type mapperType) where T : new()

Example:

using System;
using System.Data;
using System.Collections.Generic;
using CodeMatrix.AspNetCore.Utilities.Helpers;

public class Program
{
	public static void Main()
	{
		DataTable dt = new DataTable();
		// Add columns and rows to DataTable
		
		List<MyClass> list = DbHelpers.ConvertDataTable<MyClass>(dt, typeof(MyMapper));
		Console.WriteLine($"Converted {list.Count} rows to objects using custom mapper.");
	}
}

Method: MapToList<T>

Description: Maps a DataReader to a list of objects.

Signature:

public static List<T> MapToList<T>(IDataReader dr) where T : new()

Example:

using System;
using System.Data;
using System.Collections.Generic;
using CodeMatrix.AspNetCore.Utilities.Helpers;

public class Program
{
	public static void Main()
	{
		// Assuming 'dr' is an IDataReader from a database query
		IDataReader dr = GetDataReader();
		
		List<MyClass> list = DbHelpers.MapToList<MyClass>(dr);
		Console.WriteLine($"Mapped {list.Count} rows to objects.");
	}
}

Method: MapToItem<T>

Description: Maps a DataReader to a single object.

Signature:

public static T MapToItem<T>(IDataReader dr) where T : new()

Example:

using System;
using System.Data;
using CodeMatrix.AspNetCore.Utilities.Helpers;

public class Program
{
	public static void Main()
	{
		// Assuming 'dr' is an IDataReader from a database query
		IDataReader dr = GetDataReader();
		
		MyClass item = DbHelpers.MapToItem<MyClass>(dr);
		Console.WriteLine($"Mapped data to a single object.");
	}
}

Method: MapToItemUsingJson<T>

Description: Maps a DataReader to a single object using JSON serialization.

Signature:

public static T MapToItemUsingJson<T>(IDataReader dr)

Example:

using System;
using System.Data;
using CodeMatrix.AspNetCore.Utilities.Helpers;

public class Program
{
	public static void Main()
	{
		// Assuming 'dr' is an IDataReader from a database query
		IDataReader dr = GetDataReader();
		
		MyClass item = DbHelpers.MapToItemUsingJson<MyClass>(dr);
		Console.WriteLine($"Mapped data to a single object using JSON.");
	}
}

Method: GetDbParamAttributeMappings<T>

Description: Gets database parameter mappings from attributes on a type.

Signature:

public static Dictionary<string, string> GetDbParamAttributeMappings<T>()

Example:

using System;
using System.Collections.Generic;
using CodeMatrix.AspNetCore.Utilities.Helpers;
using CodeMatrix.AspNetCore.Utilities.Attributes;

public class MyModel
{
	[DbParam("param_id")]
	public int Id { get; set; }
	
	[DbParam("param_name")]
	public string Name { get; set; }
}

public class Program
{
	public static void Main()
	{
		Dictionary<string, string> mappings = DbHelpers.GetDbParamAttributeMappings<MyModel>();
		foreach (var mapping in mappings)
		{
			Console.WriteLine($"Property: {mapping.Key}, DB Param: {mapping.Value}");
		}
	}
}

Method: ChangeType<T>

Description: Converts a value to the specified type.

Signature:

public static T ChangeType<T>(object value)

Example:

using System;
using CodeMatrix.AspNetCore.Utilities.Helpers;

public class Program
{
	public static void Main()
	{
		object value = "123";
		int intValue = DbHelpers.ChangeType<int>(value);
		Console.WriteLine($"Converted value: {intValue}");
	}
}

Method: ChangeType

Description: Converts a value to the specified type.

Signature:

public static object ChangeType(object value, Type conversionType)

Example:

using System;
using CodeMatrix.AspNetCore.Utilities.Helpers;

public class Program
{
	public static void Main()
	{
		object value = "123";
		object intValue = DbHelpers.ChangeType(value, typeof(int));
		Console.WriteLine($"Converted value: {intValue}");
	}
}

DapperHelper

Description: Provides helper methods for Dapper ORM operations.

Namespace: CodeMatrix.AspNetCore.Utilities.Helpers

DapperHelper Features

Easy-to-use wrapper for Dapper
Support for stored procedures
Parameter mapping from objects
Async operations
Query analytics
Retry policies for transient failures
Multiple result set support

DapperHelper Configuration

The DapperHelper class can be configured with connection strings and other options during initialization.

Example:

using System;
using CodeMatrix.AspNetCore.Utilities.Helpers;

public class Program
{
	public static void Main()
	{
		string connectionString = "Data Source=...;Initial Catalog=...;Integrated Security=True;";
		DapperHelper dapper = new DapperHelper(connectionString);
		Console.WriteLine("DapperHelper initialized.");
	}
}

Parameter Mapping

DapperHelper can map properties from objects to stored procedure parameters automatically.

Example:

using System;
using System.Collections.Generic;
using CodeMatrix.AspNetCore.Utilities.Helpers;
using CodeMatrix.AspNetCore.Utilities.Attributes;

public class CustomerParam
{
	[DbParam("CustomerID")]
	public int Id { get; set; }
	
	[DbParam("CustomerName")]
	public string Name { get; set; }
}

public class Program
{
	public static void Main()
	{
		DapperHelper dapper = new DapperHelper("connection_string");
		
		var param = new CustomerParam { Id = 1, Name = "Test Customer" };
		dapper.ExecuteProcedure<CustomerResult>("sp_GetCustomer", param);
	}
}

Method: ExecuteProcedure<T>

Description: Executes a stored procedure and returns a collection of results.

Signature:

public IEnumerable<T> ExecuteProcedure<T>(string procedureName, object param = null)

Example:

using System;
using System.Collections.Generic;
using CodeMatrix.AspNetCore.Utilities.Helpers;

public class Program
{
	public static void Main()
	{
		DapperHelper dapper = new DapperHelper("connection_string");
		
		var customers = dapper.ExecuteProcedure<Customer>("sp_GetCustomers");
		foreach (var customer in customers)
		{
			Console.WriteLine($"Customer: {customer.Name}");
		}
	}
}

Method: ExecuteProcedureAsync<T>

Description: Asynchronously executes a stored procedure and returns a collection of results.

Signature:

public Task<IEnumerable<T>> ExecuteProcedureAsync<T>(string procedureName, object param = null)

Example:

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using CodeMatrix.AspNetCore.Utilities.Helpers;

public class Program
{
	public static async Task Main()
	{
		DapperHelper dapper = new DapperHelper("connection_string");
		
		var customers = await dapper.ExecuteProcedureAsync<Customer>("sp_GetCustomers");
		foreach (var customer in customers)
		{
			Console.WriteLine($"Customer: {customer.Name}");
		}
	}
}

Method: ExecuteScalar<T>

Description: Executes a stored procedure and returns a single value.

Signature:

public T ExecuteScalar<T>(string procedureName, object param = null)

Example:

using System;
using CodeMatrix.AspNetCore.Utilities.Helpers;

public class Program
{
	public static void Main()
	{
		DapperHelper dapper = new DapperHelper("connection_string");
		
		int count = dapper.ExecuteScalar<int>("sp_GetCustomerCount");
		Console.WriteLine($"Customer count: {count}");
	}
}

Method: ExecuteScalarAsync<T>

Description: Asynchronously executes a stored procedure and returns a single value.

Signature:

public Task<T> ExecuteScalarAsync<T>(string procedureName, object param = null)

Example:

using System;
using System.Threading.Tasks;
using CodeMatrix.AspNetCore.Utilities.Helpers;

public class Program
{
	public static async Task Main()
	{
		DapperHelper dapper = new DapperHelper("connection_string");
		
		int count = await dapper.ExecuteScalarAsync<int>("sp_GetCustomerCount");
		Console.WriteLine($"Customer count: {count}");
	}
}

Method: ExecuteNonQuery

Description: Executes a stored procedure that does not return any results.

Signature:

public void ExecuteNonQuery(string procedureName, object param = null)

Example:

using System;
using CodeMatrix.AspNetCore.Utilities.Helpers;

public class Program
{
	public static void Main()
	{
		DapperHelper dapper = new DapperHelper("connection_string");
		
		dapper.ExecuteNonQuery("sp_UpdateCustomerStatus", new { CustomerID = 1, Status = "Active" });
		Console.WriteLine("Updated customer status.");
	}
}

Method: ExecuteNonQueryAsync

Description: Asynchronously executes a stored procedure that does not return any results.

Signature:

public Task ExecuteNonQueryAsync(string procedureName, object param = null)

Example:

using System;
using System.Threading.Tasks;
using CodeMatrix.AspNetCore.Utilities.Helpers;

public class Program
{
	public static async Task Main()
	{
		DapperHelper dapper = new DapperHelper("connection_string");
		
		await dapper.ExecuteNonQueryAsync("sp_UpdateCustomerStatus", new { CustomerID = 1, Status = "Active" });
		Console.WriteLine("Updated customer status.");
	}
}

Method: BulkInsert<T>

Description: Performs a bulk insert operation.

Signature:

public void BulkInsert<T>(string tableName, IEnumerable<T> data)

Example:

using System;
using System.Collections.Generic;
using CodeMatrix.AspNetCore.Utilities.Helpers;

public class Program
{
	public static void Main()
	{
		DapperHelper dapper = new DapperHelper("connection_string");
		
		List<Customer> customers = new List<Customer>
		{
			new Customer { Name = "Customer 1" },
			new Customer { Name = "Customer 2" }
		};
		
		dapper.BulkInsert("Customers", customers);
		Console.WriteLine("Customers inserted.");
	}
}

Method: BulkInsertAsync<T>

Description: Asynchronously performs a bulk insert operation.

Signature:

public Task BulkInsertAsync<T>(string tableName, IEnumerable<T> data)

Example:

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using CodeMatrix.AspNetCore.Utilities.Helpers;

public class Program
{
	public static async Task Main()
	{
		DapperHelper dapper = new DapperHelper("connection_string");
		
		List<Customer> customers = new List<Customer>
		{
			new Customer { Name = "Customer 1" },
			new Customer { Name = "Customer 2" }
		};
		
		await dapper.BulkInsertAsync("Customers", customers);
		Console.WriteLine("Customers inserted.");
	}
}

Method: ExecuteProcedureMultiple<TFirst, TSecond>

Description: Executes a stored procedure and returns multiple result sets as a tuple.

Signature:

public (IEnumerable<TFirst>, IEnumerable<TSecond>) ExecuteProcedureMultiple<TFirst, TSecond>(string procedureName, object param = null)

Example:

using System;
using System.Collections.Generic;
using CodeMatrix.AspNetCore.Utilities.Helpers;

public class Program
{
	public static void Main()
	{
		DapperHelper dapper = new DapperHelper("connection_string");
		
		var (customers, orders) = dapper.ExecuteProcedureMultiple<Customer, Order>("sp_GetCustomersAndOrders");
		
		Console.WriteLine($"Retrieved {customers.Count()} customers and {orders.Count()} orders.");
	}
}

Method: ExecuteProcedureMultiple<TFirst, TSecond, TThird>

Description: Executes a stored procedure and returns multiple result sets as a tuple with three types.

Signature:

public (IEnumerable<TFirst>, IEnumerable<TSecond>, IEnumerable<TThird>) ExecuteProcedureMultiple<TFirst, TSecond, TThird>(string procedureName, object param = null)

Example:

using System;
using System.Collections.Generic;
using CodeMatrix.AspNetCore.Utilities.Helpers;

public class Program
{
	public static void Main()
	{
		DapperHelper dapper = new DapperHelper("connection_string");
		
		var (customers, orders, products) = dapper.ExecuteProcedureMultiple<Customer, Order, Product>("sp_GetCustomersOrdersProducts");
		
		Console.WriteLine($"Retrieved {customers.Count()} customers, {orders.Count()} orders, and {products.Count()} products.");
	}
}

Method: ExecuteProcedureMultipleAsync<TFirst, TSecond>

Description: Asynchronously executes a stored procedure and returns multiple result sets as a tuple.

Signature:

public Task<(IEnumerable<TFirst>, IEnumerable<TSecond>)> ExecuteProcedureMultipleAsync<TFirst, TSecond>(string procedureName, object param = null)

Example:

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using CodeMatrix.AspNetCore.Utilities.Helpers;

public class Program
{
	public static async Task Main()
	{
		DapperHelper dapper = new DapperHelper("connection_string");
		
		var (customers, orders) = await dapper.ExecuteProcedureMultipleAsync<Customer, Order>("sp_GetCustomersAndOrders");
		
		Console.WriteLine($"Retrieved {customers.Count()} customers and {orders.Count()} orders.");
	}
}

Method: ExecuteProcedureMultipleAsync<TFirst, TSecond, TThird>

Description: Asynchronously executes a stored procedure and returns multiple result sets as a tuple with three types.

Signature:

public Task<(IEnumerable<TFirst>, IEnumerable<TSecond>, IEnumerable<TThird>)> ExecuteProcedureMultipleAsync<TFirst, TSecond, TThird>(string procedureName, object param = null)

Example:

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using CodeMatrix.AspNetCore.Utilities.Helpers;

public class Program
{
	public static async Task Main()
	{
		DapperHelper dapper = new DapperHelper("connection_string");
		
		var (customers, orders, products) = await dapper.ExecuteProcedureMultipleAsync<Customer, Order, Product>("sp_GetCustomersOrdersProducts");
		
		Console.WriteLine($"Retrieved {customers.Count()} customers, {orders.Count()} orders, and {products.Count()} products.");
	}
}

Method: ExecuteProcedureMultipleResult

Description: Executes a stored procedure and returns a GridReader for flexible result set processing.

Signature:

public (Dapper.SqlMapper.GridReader, IDbConnection) ExecuteProcedureMultipleResult(string procedureName, object param = null)

Example:

using System;
using System.Collections.Generic;
using System.Data;
using Dapper;
using CodeMatrix.AspNetCore.Utilities.Helpers;

public class Program
{
	public static void Main()
	{
		DapperHelper dapper = new DapperHelper("connection_string");
		
		var (grid, connection) = dapper.ExecuteProcedureMultipleResult("sp_GetMultipleResults");
		
		try
		{
			var customers = grid.Read<Customer>().ToList();
			var orders = grid.Read<Order>().ToList();
			var products = grid.Read<Product>().ToList();
			
			Console.WriteLine($"Retrieved {customers.Count} customers, {orders.Count} orders, and {products.Count} products.");
		}
		finally
		{
			// Important: Close the connection when done to avoid leaks
			connection.Close();
		}
	}
}

Method: ExecuteProcedureMultipleResultAsync

Description: Asynchronously executes a stored procedure and returns a GridReader for flexible result set processing.

Signature:

public Task<(Dapper.SqlMapper.GridReader, IDbConnection)> ExecuteProcedureMultipleResultAsync(string procedureName, object param = null)

Example:

using System;
using System.Collections.Generic;
using System.Data;
using System.Threading.Tasks;
using Dapper;
using CodeMatrix.AspNetCore.Utilities.Helpers;

public class Program
{
	public static async Task Main()
	{
		DapperHelper dapper = new DapperHelper("connection_string");
		
		var (grid, connection) = await dapper.ExecuteProcedureMultipleResultAsync("sp_GetMultipleResults");
		
		try
		{
			var customers = grid.Read<Customer>().ToList();
			var orders = grid.Read<Order>().ToList();
			var products = grid.Read<Product>().ToList();
			
			Console.WriteLine($"Retrieved {customers.Count} customers, {orders.Count} orders, and {products.Count} products.");
		}
		finally
		{
			// Important: Close the connection when done to avoid leaks
			connection.Close();
		}
	}
}

Query Analytics

DapperHelper provides query analytics to help you understand the performance of your queries.

Example:

using System;
using CodeMatrix.AspNetCore.Utilities.Helpers;

public class Program
{
	public static void Main()
	{
		DapperHelper dapper = new DapperHelper("connection_string");
		dapper.EnableQueryAnalytics = true;
		
		var customers = dapper.ExecuteProcedure<Customer>("sp_GetCustomers");
		
		Console.WriteLine($"Query execution time: {dapper.LastQueryDuration.TotalMilliseconds} ms");
	}
}

Retry Policy

DapperHelper can be configured with retry policies to handle transient failures.

Example:

using System;
using CodeMatrix.AspNetCore.Utilities.Helpers;

public class Program
{
	public static void Main()
	{
		DapperHelper dapper = new DapperHelper("connection_string")
		{
			RetryCount = 3,
			RetryIntervalMilliseconds = 500
		};
		
		try
		{
			var result = dapper.ExecuteProcedure<Customer>("sp_GetCustomer", new { ID = 1 });
			Console.WriteLine("Query executed successfully with retry policy.");
		}
		catch (Exception ex)
		{
			Console.WriteLine($"Query failed after {dapper.RetryCount} attempts: {ex.Message}");
		}
	}




### HttpClientHelper
**Description:** Provides a wrapper around HttpClient with additional features.

**Namespace:** `CodeMatrix.AspNetCore.Utilities.Helpers`

#### HttpClientHelper Configuration
The `HttpClientHelper` can be configured with base address, timeout, and other options.

**Example:**
```csharp
using System;
using CodeMatrix.AspNetCore.Utilities.Helpers;
using CodeMatrix.AspNetCore.Utilities.Options;

public class Program
{
	public static void Main()
	{
		var options = new HttpClientOptions
		{
			BaseAddress = "https://api.example.com",
			DefaultTimeoutMinutes = 2
		};
		
		var httpClientHelper = new HttpClientHelper(options);
		Console.WriteLine("HttpClientHelper configured.");
	}
}

Authentication

HttpClientHelper can handle authentication automatically.

Example:

using System;
using System.Threading.Tasks;
using CodeMatrix.AspNetCore.Utilities.Helpers;
using CodeMatrix.AspNetCore.Utilities.Options;

public class Program
{
	public static async Task Main()
	{
		var options = new HttpClientOptions
		{
			BaseAddress = "https://api.example.com",
			DefaultTimeoutMinutes = 2
		};
		
		var httpClientHelper = new HttpClientHelper(options);
		httpClientHelper.SetBearerToken("your_token_here");
		
		var response = await httpClientHelper.GetAsync<MyResponseType>("https://api.example.com/protected-endpoint");
		Console.WriteLine($"Response received: {response.IsSuccess}");
	}
}

Custom Headers

You can add custom headers to requests easily.

Example:

using System;
using System.Threading.Tasks;
using CodeMatrix.AspNetCore.Utilities.Helpers;
using CodeMatrix.AspNetCore.Utilities.Options;

public class Program
{
	public static async Task Main()
	{
		var options = new HttpClientOptions
		{
			BaseAddress = "https://api.example.com",
			DefaultTimeoutMinutes = 2
		};
		
		var httpClientHelper = new HttpClientHelper(options);
		httpClientHelper.AddDefaultHeader("X-Custom-Header", "HeaderValue");
		
		var response = await httpClientHelper.GetAsync<MyResponseType>("https://api.example.com/endpoint-with-header");
		Console.WriteLine($"Response status: {response.IsSuccess}");
	}
}

JsonOptionsProvider

Description: Provides a centralized way to handle JSON serialization options.

Namespace: CodeMatrix.AspNetCore.Utilities.Helpers

Usage:

The JsonOptionsProvider provides consistent JSON serialization options across an application.

Example:

using System;
using System.Text.Json;
using CodeMatrix.AspNetCore.Utilities.Helpers;

public class Program
{
	public static void Main()
	{
		JsonSerializerOptions options = JsonOptionsProvider.DefaultOptions;
		
		string json = JsonSerializer.Serialize(new { Name = "Test" }, options);
		Console.WriteLine(json);
	}
}

Interfaces

IHttpClientHelper

Description: Interface defining the contract for HTTP client helpers.

Namespace: CodeMatrix.AspNetCore.Utilities.Interfaces

Usage:

The IHttpClientHelper interface defines methods for making HTTP requests. It can be used for dependency injection and testing.

Key Methods:

GetAsync<T>
PostAsync<T>
PutAsync<T>
DeleteAsync<T>

Example:

using System;
using System.Threading.Tasks;
using Microsoft.Extensions.DependencyInjection;
using CodeMatrix.AspNetCore.Utilities.Interfaces;

public class Program
{
	public static async Task Main()
	{
		var serviceProvider = new ServiceCollection()
			.AddHttpClientHelper()
			.BuildServiceProvider();
			
		var httpHelper = serviceProvider.GetRequiredService<IHttpClientHelper>();
		var response = await httpHelper.GetAsync<MyResponseType>("https://api.example.com/endpoint");
		
		Console.WriteLine($"Response received: {response.IsSuccess}");
	}
}

Models

ApiResult<T>

Description: Represents the result of an API operation.

Namespace: CodeMatrix.AspNetCore.Utilities.Models

Usage:

The ApiResult<T> class provides a standardized way to return results from API controllers.

Properties:

IsSuccess (bool)
Message (string)
Data (T)
StatusCode (int)
Exception (Exception)

Example:

using System;
using Microsoft.AspNetCore.Mvc;
using CodeMatrix.AspNetCore.Utilities.Models;

[ApiController]
[Route("api/[controller]")]
public class CustomersController : ControllerBase
{
	[HttpGet]
	public ActionResult<ApiResult<List<Customer>>> Get()
	{
		try
		{
			var customers = GetCustomers();
			return new ApiResult<List<Customer>>
			{
				IsSuccess = true,
				Data = customers,
				Message = "Customers retrieved successfully"
			};
		}
		catch (Exception ex)
		{
			return new ApiResult<List<Customer>>
			{
				IsSuccess = false,
				Message = "Failed to retrieve customers",
				Exception = ex
			};
		}
	}
}

HttpResult<T>

Description: Represents the result of an HTTP operation, extending ApiResult<T> with HTTP status code information.

Namespace: CodeMatrix.AspNetCore.Utilities.Models

Inheritance: Extends ApiResult<T>

Usage:

The HttpResult<T> class is specifically designed for HTTP client operations and includes detailed status code information along with response data.

Properties:

IsSuccessful (bool) - Indicates if the HTTP request was successful
Message (string) - Details about the operation result
Data (T) - The response data from the HTTP operation
StatusCode (int) - The HTTP status code returned by the server

Static Methods:

Success<T>(T data, string message, int statusCode) - Creates a successful result
Error<T>(T data, string message, int statusCode) - Creates an error result
Error<T>(string message) - Creates an error result with empty data

Example with HttpClientHelper:

using System;
using System.Threading.Tasks;
using CodeMatrix.AspNetCore.Utilities.Interfaces;
using CodeMatrix.AspNetCore.Utilities.Models;
using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/[controller]")]
public class ProxyController : ControllerBase
{
	private readonly IHttpClientHelper _httpClient;
	
	public ProxyController(IHttpClientHelper httpClient)
	{
		_httpClient = httpClient;
	}
	
	[HttpGet("fetch-data")]
	public async Task<ActionResult<ApiResult<string>>> FetchData(string url)
	{
		try
		{
			// HttpClientHelper methods now return HttpResult<T>
			HttpResult<string> result = await _httpClient.InvokeGetAsync(
				url, 
				headers: null, 
				timeoutInMinutes: 5
			);
			
			if (result.IsSuccessful)
			{
				return Ok(new ApiResult<string>
				{
					IsSuccessful = true,
					Data = result.Data,
					Message = $"Data fetched successfully (HTTP {result.StatusCode})"
				});
			}
			else
			{
				return Ok(new ApiResult<string>
				{
					IsSuccessful = false,
					Data = result.Data,
					Message = $"Failed to fetch data: {result.Message} (HTTP {result.StatusCode})"
				});
			}
		}
		catch (Exception ex)
		{
			return Ok(new ApiResult<string>
			{
				IsSuccessful = false,
				Message = $"Error occurred: {ex.Message}"
			});
		}
	}
	
	[HttpPost("post-data")]
	public async Task<ActionResult<ApiResult<string>>> PostData(string url, [FromBody] string jsonBody)
	{
		try
		{
			var headers = new Dictionary<string, string>
			{
				{ "X-Custom-Header", "CustomValue" }
			};
			
			HttpResult<string> result = await _httpClient.InvokePostAsync(
				url, 
				jsonBody, 
				headers, 
				timeoutInMinutes: 5
			);
			
			return result.IsSuccessful 
				? Ok(new ApiResult<string>
				{
					IsSuccessful = true,
					Data = result.Data,
					Message = "Post successful"
				})
				: StatusCode(result.StatusCode, new ApiResult<string>
				{
					IsSuccessful = false,
					Data = result.Data,
					Message = result.Message
				});
		}
		catch (Exception ex)
		{
			return StatusCode(500, new ApiResult<string>
			{
				IsSuccessful = false,
				Message = $"Error occurred: {ex.Message}"
			});
		}
	}
	
	[HttpGet("fetch-bytes")]
	public async Task<ActionResult<ApiResult<byte[]>>> FetchBytes(string url)
	{
		try
		{
			HttpResult<byte[]> result = await _httpClient.InvokeGetBytesAsync(
				url, 
				queryParams: "", 
				timeoutInMinutes: 10
			);
			
			if (result.IsSuccessful)
			{
				return Ok(new ApiResult<byte[]>
				{
					IsSuccessful = true,
					Data = result.Data,
					Message = $"Binary data fetched successfully ({result.Data.Length} bytes)"
				});
			}
			else
			{
				return StatusCode(result.StatusCode, new ApiResult<byte[]>
				{
					IsSuccessful = false,
					Message = result.Message
				});
			}
		}
		catch (Exception ex)
		{
			return StatusCode(500, new ApiResult<byte[]>
			{
				IsSuccessful = false,
				Message = $"Error occurred: {ex.Message}"
			});
		}
	}
}

Available HttpClientHelper Methods Returning HttpResult:

All HttpClientHelper methods now return HttpResult<T> for better error handling and response details:

InvokeGetAsync - Returns HttpResult<string> for GET requests
InvokeGetBytesAsync - Returns HttpResult<byte[]> for binary GET requests
InvokePostAsync (JSON) - Returns HttpResult<string> for JSON POST requests
InvokePostAsync (MultipartFormDataContent) - Returns HttpResult<string> for multipart POST requests
InvokePostAsync (byte array) - Returns HttpResult<string> for byte array POST requests
InvokePostBytesAsync - Returns HttpResult<byte[]> for POST requests returning binary data
InvokeXmlPostAsync - Returns HttpResult<string> for XML POST requests
InvokeSendAsync - Returns HttpResult<Stream> for stream-based POST requests

Each method includes:

Comprehensive error handling without throwing exceptions
Detailed HTTP status codes for all responses
Meaningful error messages for failures
Structured response data in the Data property
Success flag (IsSuccessful) for easy result checking

HttpClientOptions

Description: Configuration options for HTTP client behavior including compression, SSL verification, timeouts, and retry policies.

Namespace: CodeMatrix.AspNetCore.Utilities.Options

Properties:

Property	Type	Default	Description
`DefaultTimeoutMinutes`	int	5	Request timeout in minutes. Set to 0 or negative to disable timeout.
`EnableCompression`	bool	true	Automatically decompress GZIP, Deflate, and Brotli responses for better performance.
`VerifySsl`	bool	true	Verify SSL/TLS certificates. ALWAYS true in production. Only set false for dev/test with self-signed certs.
`MaxRetryAttempts`	int	3	Number of retry attempts for transient failures (requires Polly integration).
`RetryDelaySeconds`	int	1	Initial retry delay with exponential backoff (requires Polly integration).
`ClientNames`	List<string>	["Default", "XML"]	Named client configurations registered with IHttpClientFactory.

Example with All Features:

using CodeMatrix.AspNetCore.Utilities.DependencyInjection;
using CodeMatrix.AspNetCore.Utilities.Options;

var services = new ServiceCollection();

services.AddHttpClientHelper(options =>
{
	// Network Configuration
	options.DefaultTimeoutMinutes = 5;      // 5-minute timeout for all requests
	
	// Performance
	options.EnableCompression = true;       // Enable automatic decompression
	
	// Security
	options.VerifySsl = true;               // Always verify SSL in production
	
	// Resilience (when Polly is available)
	options.MaxRetryAttempts = 3;           // Retry transient failures up to 3 times
	options.RetryDelaySeconds = 1;          // Start with 1 second, use exponential backoff
	
	// Registered client names - each gets own HttpClient configuration
	// Default clients include "Default" and "XML"
});

// For development with self-signed certificates only:
if (IsDevelopment)
{
	services.AddHttpClientHelper(options =>
	{
		options.VerifySsl = false;  // ONLY for dev/test environments!
		options.EnableCompression = true;
	});
}

Compression Details:

When EnableCompression = true, the handler automatically decompresses responses
Supported compression algorithms: GZIP, Deflate, Brotli
Improves performance for large responses by reducing bandwidth
Compatible with most modern APIs

SSL Verification Details:

VerifySsl = true (default): Validates server SSL certificates (production recommended)
VerifySsl = false: Accepts all certificates (dev/test only with self-signed certs)
Warning: Disabling SSL verification in production creates security vulnerabilities

Retry Policy Details (Polly integration):

Retries on HTTP 5xx errors (server errors)
Retries on connection failures (HttpRequestException)
Uses exponential backoff: delay = retryDelaySeconds ^ retryAttempt
Example: With 1s delay, retry delays are: 1s, 2s, 4s, 8s...

AppConstants

Description: Provides application-wide constants.

Namespace: CodeMatrix.AspNetCore.Utilities.Models

Usage:

The AppConstants class contains constants used throughout the application.

Example:

using System;
using CodeMatrix.AspNetCore.Utilities.Models;

public class Program
{
	public static void Main()
	{
		Console.WriteLine($"Date format: {AppConstants.DefaultDateFormat}");
	}
}

RegexConstants

Description: Provides commonly used regular expression patterns.

Namespace: CodeMatrix.AspNetCore.Utilities.Models

Usage:

The RegexConstants class contains predefined regular expression patterns for common validation scenarios.

Example:

using System;
using System.Text.RegularExpressions;
using CodeMatrix.AspNetCore.Utilities.Models;

public class Program
{
	public static void Main()
	{
		string email = "test@example.com";
		bool isValid = Regex.IsMatch(email, RegexConstants.EmailPattern);
		
		Console.WriteLine($"Is valid email: {isValid}");
	}
}

DependencyInjection

HttpClientHelperExtensions

Description: Extension methods for registering HttpClientHelper services in the dependency injection container.

Namespace: CodeMatrix.AspNetCore.Utilities.DependencyInjection

Usage:

The HttpClientHelperExtensions class provides methods to register the HttpClientHelper service with the dependency injection container, along with the necessary HttpClient instances.

Key Methods:

AddHttpClientHelper(IServiceCollection services) - Registers the HttpClientHelper with default options.
AddHttpClientHelper(IServiceCollection services, Action<HttpClientOptions> configureOptions) - Registers the HttpClientHelper with custom options.

Example:

using CodeMatrix.AspNetCore.Utilities.DependencyInjection;

// In Program.cs or Startup.cs
public void ConfigureServices(IServiceCollection services)
{
	// Add HttpClientHelper with default options
	services.AddHttpClientHelper();
	
	// Or with custom configuration
	services.AddHttpClientHelper(options => 
	{
		options.BaseAddress = "https://api.example.com";
		options.Timeout = TimeSpan.FromSeconds(30);
		options.DefaultHeaders.Add("X-API-Key", "your-api-key");
	});
}

JsonOptionsExtensions

Description: Extension methods for configuring JSON options in ASP.NET Core applications.

Namespace: CodeMatrix.AspNetCore.Utilities.DependencyInjection

Usage:

The JsonOptionsExtensions class provides methods to configure JSON serialization options for ASP.NET Core applications.

Key Methods:

AddCodeMatrixJsonOptions(IMvcBuilder builder) - Adds CodeMatrix JSON options to the MVC builder.
AddCodeMatrixJsonOptions(IMvcCoreBuilder builder) - Adds CodeMatrix JSON options to the MVC Core builder.

Example:

using CodeMatrix.AspNetCore.Utilities.DependencyInjection;

// In Program.cs or Startup.cs
public void ConfigureServices(IServiceCollection services)
{
	services.AddControllers()
		.AddCodeMatrixJsonOptions();
}

Contributing

Contributions are welcome! If you'd like to contribute to this project, please follow these steps:

Fork the repository
Create a feature branch: git checkout -b feature/your-feature-name
Commit your changes: git commit -am 'Add some feature'
Push to the branch: git push origin feature/your-feature-name
Submit a pull request

Please make sure your code follows the existing style and includes appropriate tests and documentation.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Build Scripts (Local Development)

For local development on Windows systems, this repository includes batch files for building package variants:

Available Scripts

`Build-Packages.bat`

Builds a single package variant.

Usage:

Build-Packages.bat <Variant> <Version>

Examples:

Build-Packages.bat Core 1.0.0
Build-Packages.bat Database 1.0.0
Build-Packages.bat Http 1.0.0
Build-Packages.bat Azure 1.0.0
Build-Packages.bat Full 1.0.0

`Build-All-Variants.bat`

Builds all package variants in sequence for a given version.

Usage:

Build-All-Variants.bat <Version>

Example:

Build-All-Variants.bat 1.0.0

`Validate-Variants.bat`

Validates that all package variants can be built successfully with detailed reporting.

Usage:

Validate-Variants.bat [TestVersion]

Examples:

Validate-Variants.bat
Validate-Variants.bat 0.0.0-test

If no test version is provided, defaults to 0.0.0-validation. Test packages are automatically cleaned up after validation.

Output

All generated NuGet packages are placed in:

CodeMatrix.AspNetCore.Utilities\bin\Release\

Package naming convention:

Core: CodeMatrix.AspNetCore.Utilities.<version>.nupkg
Other variants: CodeMatrix.AspNetCore.Utilities.<Variant>.<version>.nupkg

Requirements

.NET 8.0 SDK or later
Windows command prompt or PowerShell
No PowerShell execution policy restrictions (batch files only)

Version History

Version 1.0.15

Latest stable release
Improved extension method robustness (StreamExtension, StringExtension, ModelStateExtension)
Fixed DateTimeJsonConverter to handle flexible fractional seconds formats
Enhanced null handling across various extension methods
Updated ModelStateValidationFilter and ModelStateValidationAsyncFilter to return standardized ApiResult responses
Fixed memory management in StreamExtension.ConvertToBase64() method

Version 1.0.14

Added support for multiple result sets in DapperHelper
Enhanced documentation with comprehensive examples
Additional features and bug fixes

Version 1.0.13

Performance improvements
Extended helper methods

Version 1.0.12

Bug fixes and stability improvements
Enhanced JsonConverter implementations

Version 1.0.11

Added additional extension methods
Improved error handling

Version 1.0.10

Improved DependencyInjection support
Enhanced HttpClientHelper capabilities

Version 1.0.9

Added more helper methods
Bug fixes for serialization

Version 1.0.8

Extended model validation filters
Added support for more data types

Version 1.0.7

Enhanced Dapper integration
Additional utility functions

Version 1.0.6

Bug fixes and performance improvements
Enhanced XML handling

Version 1.0.5

Added additional extension methods
Improved data conversion utilities

Version 1.0.4

Added features and bug fixes
Extended converter functionality

Version 1.0.3

Improved error handling
Added new extension methods

Version 1.0.2

Enhanced JSON serialization options
Bug fixes for DateTime converters

Version 1.0.1

Added Dapper integration improvements
Fixed issues with HTTP client helper

Version 1.0.0

Initial release
Basic functionality for extensions and helpers

Product	Compatible and additional computed target framework versions.
.NET	net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 is compatible. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 was computed. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed.

Product

.NET

Compatible target framework(s)

Included target framework(s) (in package)

Learn more about Target Frameworks and .NET Standard.

net8.0
- Microsoft.Extensions.Caching.Abstractions (>= 10.0.5)
- Microsoft.Extensions.Http (>= 10.0.5)
- Microsoft.Extensions.Http.Polly (>= 10.0.5)
- Polly (>= 8.6.6)
- System.Text.Json (>= 10.0.5)
net9.0
- Microsoft.Extensions.Caching.Abstractions (>= 10.0.5)
- Microsoft.Extensions.Http (>= 10.0.5)
- Microsoft.Extensions.Http.Polly (>= 10.0.5)
- Polly (>= 8.6.6)
- System.Text.Json (>= 10.0.5)

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version	Downloads	Last Updated
1.0.21	87	5/4/2026
1.0.20	96	4/28/2026
1.0.19	94	4/7/2026
1.0.18	95	4/7/2026
1.0.17	112	4/7/2026
1.0.16	95	4/7/2026
1.0.15	106	3/18/2026
1.0.14	191	10/22/2025
1.0.13	185	10/22/2025

CodeMatrix.AspNetCore.Utilities.Http 1.0.21

CodeMatrix.AspNetCore.Utilities

Description

Installation

Package Variants

🔹 Core Variant (CodeMatrix.AspNetCore.Utilities)

🔹 Database Variant (CodeMatrix.AspNetCore.Utilities.Database)

🔹 Http Variant (CodeMatrix.AspNetCore.Utilities.Http)

🔹 Azure Variant (CodeMatrix.AspNetCore.Utilities.Azure)

🔹 Full Variant (CodeMatrix.AspNetCore.Utilities.Full)

Consumer Project Examples

Example 1: Web API with Minimal Dependencies (Core Variant)

Example 2: Data-Heavy Application (Database Variant)

Example 3: Microservice with HTTP Calls (Http Variant)

Example 4: Azure-Hosted Application (Azure Variant)

Example 5: Complex Application (Full Variant)

Dependency Comparison

Migration Guide

Getting Started

Configuring JSON Options

Setting Up HTTP Client Helper

Target Framework and Dependencies

Table of Contents

Attributes

DbParamAttribute

Converters

BooleanJsonConverter

DateTimeJsonConverter

Example 1: Default Usage (Property Attribute)

Example 2: Using JsonSerializerOptions

Example 3: Using Custom Input Formats

Example 4: Common Format Handling

Flexible Fractional Seconds Handling

Example 5: Combining Custom Formats with Default Formats

DateTimeOffsetJsonConverter

NumberToStringJsonConverter

Extensions

BoolExtension

Method: ToYesNo

Method: ToYesNo (bool?)

CollectionExtension

ToDictionary (IFormCollection)

ToDictionary (NameValueCollection)

DateTimeExtension

ToDateString (DateTime)

ToDateString (DateTime?)

ToDateString (DateTime?, string)

ToShortDateString (DateTime)

ToShortDateString (DateTime?)

ToIndianStandardDateTime (DateTime)

ExceptionExtension

ToApiResult

HostEnvironmentExtension

IsUAT

JsonExtension

GetByName

GetByIndex

GetByPath

ModelStateExtension

ErrorsToString

ObjectExtension

ToSafeString (object)

Serialize

GetPropertiesAsDictionary

StreamExtension

ConvertToBase64

StringExtension

Method: IsNullOrEmpty

Method: IsNullOrEmptyToNull

Method: ToSafeString (string)

Method: ToSafeInt

Method: Replace

Method: RemoveUnicodeChars

Method: SplitProperCase

Method: ToDateTime

Method: ToIndianStandardDateTime (string)

Method: Deserialize

XmlExtension

DeserializeXmlNode

ToXmlDocument

🔹 Core Variant (`CodeMatrix.AspNetCore.Utilities`)

🔹 Database Variant (`CodeMatrix.AspNetCore.Utilities.Database`)

🔹 Http Variant (`CodeMatrix.AspNetCore.Utilities.Http`)

🔹 Azure Variant (`CodeMatrix.AspNetCore.Utilities.Azure`)

🔹 Full Variant (`CodeMatrix.AspNetCore.Utilities.Full`)

`Build-Packages.bat`

`Build-All-Variants.bat`

`Validate-Variants.bat`