A comprehensive networking library providing essential utilities for working with HTTP, URLs, sockets, multicast, email, and retry policies in .NET applications.
Overview
Ecng.Net is a core networking helper library that simplifies common networking tasks including URL manipulation, HTTP client operations, socket management, multicast operations, email handling, and network path validation. The library is built on .NET Standard 2.0 and supports modern .NET versions including .NET 6.0 and .NET 10.0.
Installation
Add a reference to the Ecng.Net project or NuGet package in your application.
Key Features
URL Manipulation: Advanced URL parsing and query string management
HTTP Utilities: Headers, authentication schemas, and client extensions
Socket Operations: Enhanced socket methods including multicast support
Network Helpers: IP address validation, endpoint utilities, and path detection
Email Utilities: Email validation and mail message helpers
Retry Policies: Configurable retry logic with exponential backoff
OAuth Support: OAuth token management interfaces
Core Components
1. URL and Query String Management
The Url and QueryString classes provide powerful URL manipulation capabilities with fluent APIs.
Basic URL Usage
using Ecng.Net;
// Create a URL
var url = new Url("https://api.example.com/data");
// Create URL with base and relative parts
var apiUrl = new Url("https://api.example.com", "/v1/users");
// Clone URL with modifications
var modifiedUrl = url.Clone();
modifiedUrl.Encode = UrlEncodes.Upper; // Use uppercase encoding
Query String Operations
// Working with query strings
var url = new Url("https://api.example.com/search?q=test");
// Access query string
var queryString = url.QueryString;
// Add parameters
queryString.Append("page", 1)
.Append("limit", 50)
.Append("sort", "date");
// Get values
int page = queryString.GetValue<int>("page");
string sort = queryString.TryGetValue<string>("sort", "default");
// Check if parameter exists
if (queryString.Contains("q"))
{
string query = queryString.GetValue<string>("q");
}
// Remove parameters
queryString.Remove("sort");
// Clear all parameters
queryString.Clear();
// Iterate over parameters
foreach (var kvp in queryString)
{
Console.WriteLine($"{kvp.Key} = {kvp.Value}");
}
// Get raw query string
string rawQuery = queryString.Raw; // Returns "page=1&limit=50"
URL Encoding Options
var url = new Url("https://example.com/api");
// Control encoding behavior
url.Encode = UrlEncodes.None; // No encoding
url.Encode = UrlEncodes.Lower; // Lowercase encoding (default)
url.Encode = UrlEncodes.Upper; // Uppercase encoding
// Keep default page in URL
url.KeepDefaultPage = true;
2. Network Helper Extensions
The NetworkHelper class provides numerous extension methods for common networking tasks.
Endpoint Operations
using System.Net;
using Ecng.Net;
// Check if endpoint is local
var endpoint = new IPEndPoint(IPAddress.Loopback, 8080);
bool isLocal = endpoint.IsLocal(); // true
var dnsEndpoint = new DnsEndPoint("localhost", 8080);
bool isDnsLocal = dnsEndpoint.IsLocal(); // true
// Check if endpoint IP is local
bool isLocalIp = endpoint.IsLocalIpAddress();
// Check if IP is loopback
IPAddress address = IPAddress.Parse("127.0.0.1");
bool isLoopback = address.IsLoopback(); // true
TCP Client Extensions
using System.Net.Sockets;
using Ecng.Net;
var client = new TcpClient();
var endpoint = new DnsEndPoint("api.example.com", 443);
// Async connection with cancellation token
await client.ConnectAsync(endpoint, cancellationToken);
SSL/TLS Stream Creation
using System.IO;
using System.Net.Security;
using System.Security.Authentication;
using Ecng.Net;
Stream networkStream = client.GetStream();
// Convert to SSL stream
var sslStream = networkStream.ToSsl(
sslProtocol: SslProtocols.Tls12 | SslProtocols.Tls13,
checkCertificateRevocation: true,
validateRemoteCertificates: true,
targetHost: "api.example.com",
sslCertificate: null, // Optional client certificate path
sslCertificatePassword: null
);
using Ecng.Net;
// Convert dictionary to query string
var parameters = new Dictionary<string, string>
{
["api_key"] = "12345",
["format"] = "json"
};
string queryString = parameters.ToQueryString(); // "api_key=12345&format=json"
// With URL encoding
var sensitiveParams = new Dictionary<string, string>
{
["email"] = "user@example.com",
["redirect"] = "https://example.com/callback"
};
string encoded = sensitiveParams.ToQueryString(encodeValue: true);
// Using tuples
var tupleParams = new[]
{
("name", "John Doe"),
("age", "30")
};
string fromTuples = tupleParams.ToQueryString(); // "name=John Doe&age=30"
3. Multicast Operations
The library provides enhanced multicast support for UDP sockets.
Basic Multicast
using System.Net;
using System.Net.Sockets;
using Ecng.Net;
var socket = new Socket(AddressFamily.InterNetwork, SocketType.Dgram, ProtocolType.Udp);
var multicastAddress = IPAddress.Parse("239.255.0.1");
// Join multicast group
socket.JoinMulticast(multicastAddress);
// Leave multicast group
socket.LeaveMulticast(multicastAddress);
Source-Specific Multicast
using Ecng.Net;
// Configure source-specific multicast
var multicastConfig = new MulticastSourceAddress
{
GroupAddress = IPAddress.Parse("239.255.0.1"),
SourceAddress = IPAddress.Parse("192.168.1.100"),
Port = 5000,
IsEnabled = true
};
// Join with source filter
socket.JoinMulticast(multicastConfig);
// Leave source-specific multicast
socket.LeaveMulticast(multicastConfig);
4. HTTP Client Extensions
Convenient extensions for working with HttpClient.
User Agent Configuration
using System.Net.Http;
using Ecng.Net;
var httpClient = new HttpClient();
// Apply Chrome user agent
httpClient.ApplyChromeAgent();
// Sets: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36...
Bearer Token Authentication
using System.Security;
using Ecng.Net;
var httpClient = new HttpClient();
var token = new SecureString();
// ... populate token
// Set bearer authentication
httpClient.SetBearer(token);
// Adds header: Authorization: Bearer {token}
Helper methods for formatting authentication headers.
using System.Security;
using Ecng.Net;
// Bearer authentication
var bearerToken = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";
string authHeader = AuthSchemas.Bearer.FormatAuth(bearerToken);
// Returns: "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
// Basic authentication
var credentials = "username:password".UTF8().Base64();
string basicAuth = AuthSchemas.Basic.FormatAuth(credentials);
// Returns: "Basic dXNlcm5hbWU6cGFzc3dvcmQ="
// With SecureString
var secureToken = new SecureString();
// ... populate secure token
string secureAuth = AuthSchemas.Bearer.FormatAuth(secureToken);
6. OAuth Support
Interfaces for implementing OAuth authentication flows.
using Ecng.Net;
// Implement OAuth provider
public class MyOAuthProvider : IOAuthProvider
{
public async Task<IOAuthToken> RequestToken(
long socialId,
bool isDemo,
CancellationToken cancellationToken)
{
// Request token from OAuth server
var token = await GetOAuthTokenAsync(socialId, isDemo);
return new OAuthToken
{
Value = token.AccessToken,
Expires = DateTime.UtcNow.AddSeconds(token.ExpiresIn)
};
}
}
// OAuth token implementation
public class OAuthToken : IOAuthToken
{
public string Value { get; set; }
public DateTime? Expires { get; set; }
}
7. Retry Policy with Exponential Backoff
Configure and execute retry logic for network operations.
using System.Net.Sockets;
using Ecng.Net;
// Configure retry policy
var retryPolicy = new RetryPolicyInfo
{
ReadMaxCount = 5, // Max retry attempts for reads
WriteMaxCount = 3, // Max retry attempts for writes
InitialDelay = TimeSpan.FromSeconds(1), // Initial delay
MaxDelay = TimeSpan.FromSeconds(30) // Maximum delay cap
};
// Configure which socket errors to retry
retryPolicy.Track.Clear();
retryPolicy.Track.Add(SocketError.TimedOut);
retryPolicy.Track.Add(SocketError.HostNotFound);
retryPolicy.Track.Add(SocketError.ConnectionRefused);
// Execute with retry logic
var result = await retryPolicy.TryRepeat(
async (ct) =>
{
// Your async operation
return await httpClient.GetStringAsync("https://api.example.com/data", ct);
},
maxCount: retryPolicy.ReadMaxCount,
cancellationToken
);
// Retry delays use exponential backoff with jitter:
// Attempt 1: ~1s + jitter
// Attempt 2: ~2s + jitter
// Attempt 3: ~4s + jitter
// Attempt 4: ~8s + jitter
// Attempt 5: ~16s + jitter (capped at MaxDelay)
Manual Delay Calculation
var policy = new RetryPolicyInfo();
// Calculate delay for specific attempt
TimeSpan delay1 = policy.GetDelay(1); // ~1 second + jitter
TimeSpan delay2 = policy.GetDelay(2); // ~2 seconds + jitter
TimeSpan delay3 = policy.GetDelay(3); // ~4 seconds + jitter
8. Email Utilities
Helpers for working with email messages and SMTP.
Email Validation
using Ecng.Net;
// Validate email format
bool isValid = "user@example.com".IsEmailValid(); // true
bool isInvalid = "invalid.email".IsEmailValid(); // false
Email Message Extensions
using System.Net.Mail;
using Ecng.Net;
var message = new MailMessage
{
From = new MailAddress("sender@example.com"),
Subject = "Test Email",
Body = "Plain text body"
};
message.To.Add("recipient@example.com");
// Add HTML body
message.AddHtml("<html><body><h1>Hello!</h1></body></html>");
// Add plain text alternative
message.AddPlain("Hello in plain text!");
// Attach files
using var fileStream = File.OpenRead("document.pdf");
message.Attach("document.pdf", fileStream);
// Send asynchronously (Note: Method is marked obsolete, use SmtpClient.SendMailAsync directly)
await message.SendAsync(cancellationToken);
Creating Attachments
using System.IO;
using System.Net.Mail;
using System.Net.Mime;
using Ecng.Net;
// Create attachment from stream
using var stream = new MemoryStream(fileBytes);
var attachment = MailHelper.ToAttachment("report.pdf", stream);
// Create attachment with custom encoding
var customAttachment = MailHelper.CreateAttachment(
stream,
"report.pdf",
TransferEncoding.Base64
);
// Attach to message
message.Attachments.Add(attachment);
9. HTTP Status Code Utilities
Extract and work with HTTP status codes from exceptions.
using System.Net;
using System.Net.Http;
using Ecng.Net;
try
{
await httpClient.GetAsync("https://api.example.com/resource");
}
catch (HttpRequestException ex)
{
// Try to extract status code
HttpStatusCode? statusCode = ex.TryGetStatusCode();
if (statusCode == HttpStatusCode.NotFound)
{
Console.WriteLine("Resource not found");
}
else if (statusCode == HttpStatusCode.Unauthorized)
{
Console.WriteLine("Authentication required");
}
}
// Create custom HTTP exceptions
var notFoundException = HttpStatusCode.NotFound.CreateHttpRequestException(
"The requested resource was not found"
);
var unauthorizedException = HttpStatusCode.Unauthorized.CreateHttpRequestException(
"Invalid API key"
);
// Customize status code phrases for better detection
NetworkHelper.SetStatusCodePhrase(HttpStatusCode.TooManyRequests, "rate limit");
10. Socket Error Handling
Extract socket errors from exceptions.
using System.Net.Sockets;
using Ecng.Net;
try
{
// Network operation
await socket.ConnectAsync(endpoint);
}
catch (Exception ex)
{
// Extract socket error from exception chain
SocketError? socketError = ex.TryGetSocketError();
if (socketError == SocketError.TimedOut)
{
Console.WriteLine("Connection timed out");
}
else if (socketError == SocketError.ConnectionRefused)
{
Console.WriteLine("Connection refused by server");
}
}
11. IP Address and Subnet Operations
Work with IP addresses and subnet calculations.
using System.Net;
using Ecng.Net;
var ipAddress = IPAddress.Parse("192.168.1.100");
// Check if IP is in subnet
bool isInSubnet = ipAddress.IsInSubnet("192.168.1.0/24"); // true
bool notInSubnet = ipAddress.IsInSubnet("10.0.0.0/8"); // false
// Works with IPv6
var ipv6 = IPAddress.Parse("2001:db8::1");
bool isInV6Subnet = ipv6.IsInSubnet("2001:db8::/32"); // true
12. Network Path Detection
Detect various types of network paths and addresses.