PowerCSharp

Enhanced C# extension methods and utilities for .NET developers

PowerCSharp is a comprehensive library of extension methods, utilities, and helper classes designed to enhance your C# development experience. Built by a senior C# architect with 20+ years of experience, this library provides practical, well-tested solutions for common programming challenges.

PowerCSharp v2.0.0 — Features Framework Release

What's New in v2.0.0:

• Features Framework: Brand-new PowerCSharp.Features engine — hybrid auto-scan + explicit module discovery, composite flag resolution (config → env vars → overrides), DI orchestration, opt-in diagnostics endpoint
• Built-in Features: PowerCSharp.BuiltInFeatures bundle — runtime-flag-toggled ASP.NET Core capabilities (CORS), toggled via PowerFeatures:<Key>:Enabled
• Cache Feature Family: PowerCSharp.Feature.Cache (module + options), PowerCSharp.Feature.Cache.Abstractions (contracts + NoOp, netstandard2.0 + net8.0), PowerCSharp.Feature.Cache.BitFaster (BitFaster-backed LRU), PowerCSharp.Feature.Cache.Disk (disk-backed LRU with cross-process locking)
• EditorConfig: Comprehensive coding standards applied across the entire codebase
• Directory Extensions: TrySafeDelete and related safe I/O helpers
• Code Quality: Nullable annotations, member ordering, and namespace cleanup throughout

📦 Packages

PowerCSharp is organized into focused, independently versioned packages.

Core Libraries (v2.0.0)

• PowerCSharp.Core - Core foundation and base classes, including centralized interfaces and models
• PowerCSharp.Extensions - Cross-platform extension methods for collections, HTTP, LINQ, JSON, XML, objects, types, streams, and strings
• PowerCSharp.Extensions.AspNetCore - ASP.NET Core specific extensions for configuration and web utilities
• PowerCSharp.Utilities - Utility classes for validation, file operations, and mathematics
• PowerCSharp.Helpers - Specialized helpers for JSON, cryptography, and environment operations
• PowerCSharp.Compatibility - .NET Framework compatibility layer (net462/net472/net48)

Features Framework (v1.0.0)

• PowerCSharp.Features.Abstractions - Contracts only: IFeatureModule, IFeatureFlagProvider, FeatureOptionsBase, FeatureDescriptor. Zero third-party dependencies.
• PowerCSharp.Features - The engine: assembly discovery, composite flag resolution, DI orchestration, feature registry, and diagnostics. Entry points: AddPowerFeatures() / UsePowerFeatures().
• PowerCSharp.BuiltInFeatures - Bundle of lightweight, runtime-toggled ASP.NET Core capabilities (CORS). Toggle via PowerFeatures:<Key>:Enabled.

Cache Feature Family (v1.3.0)

• PowerCSharp.Feature.Cache.Abstractions - Cache contracts (ICacheService, IDiskCacheService, metadata types) and NoOp safe-off implementations. Targets netstandard2.0 + net8.0.
• PowerCSharp.Feature.Cache - Cache feature module, options, and AddCacheFeature() wiring. Pair with a provider package.
• PowerCSharp.Feature.Cache.BitFaster - BitFaster-backed in-memory LRU cache. Isolates BitFaster.Caching dependency.
• PowerCSharp.Feature.Cache.Disk - Disk-backed LRU cache with atomic writes, cross-process file-lock coordination, and background cleanup.

🏗️ Architecture

PowerCSharp follows a clean architectural pattern with centralized interfaces in PowerCSharp.Core:

• All interfaces are located in PowerCSharp.Core.Interfaces namespace
• All models are located in PowerCSharp.Core.Models namespace
• Clear separation of concerns with proper dependency management
• Consistent namespace organization across the entire ecosystem
• Modular design allowing selective package installation
• Dependency-free core for maximum compatibility

🚀 Installation

Core libraries

dotnet add package PowerCSharp.Core
dotnet add package PowerCSharp.Extensions
dotnet add package PowerCSharp.Extensions.AspNetCore
dotnet add package PowerCSharp.Utilities
dotnet add package PowerCSharp.Helpers
dotnet add package PowerCSharp.Compatibility

Features framework

dotnet add package PowerCSharp.Features.Abstractions
dotnet add package PowerCSharp.Features
dotnet add package PowerCSharp.BuiltInFeatures

Cache feature (pick a provider)

dotnet add package PowerCSharp.Feature.Cache
dotnet add package PowerCSharp.Feature.Cache.BitFaster   # in-memory LRU (BitFaster)
dotnet add package PowerCSharp.Feature.Cache.Disk        # disk-backed LRU

💡 Usage Examples

String Extensions (PowerCSharp.Extensions)

using PowerCSharp.Extensions;

string text = "hello world";
bool isEmpty = text.IsNullOrWhiteSpace(); // false
string title = text.ToTitleCase(); // "Hello World"
string safe = text.SafeSubstring(0, 5); // "hello"

// Additional string utilities
string camel = "HelloWorld".ToCamelCase(); // "helloWorld"
string firstLower = text.FirstCharToLowerCase(); // "hello world"
string mid = text.Mid(6); // "world"
string normalized = "User Name".NormalizeKey(); // "userName"
string ascii = "café".AsAscii(); // "caf"
bool isValid = "https://example.com".IsValidUrl(); // true

Collection Extensions (PowerCSharp.Extensions)

using PowerCSharp.Extensions;

var numbers = new List<int> { 1, 2, 3, 4, 5 };
bool isEmpty = numbers.IsNullOrEmpty(); // false
var first = numbers.FirstOrDefaultSafe(-1); // 1
var page = numbers.Page(1, 2); // [1, 2]

// New collection utilities
var list = new List<string> { "keep", "remove", "keep", "remove" };
int removed = list.RemoveAll(x => x == "remove"); // 2

DateTime Extensions (PowerCSharp.Extensions)

using PowerCSharp.Extensions;

var date = DateTime.Now;
int age = date.GetAge();
bool isWeekend = date.IsWeekend();
var firstDay = date.FirstDayOfMonth();
var lastDay = date.LastDayOfMonth();

HTTP & Network Extensions (PowerCSharp.Extensions.AspNetCore)

using PowerCSharp.Extensions.AspNetCore;
using System.Net;

// HTTP Status Code utilities
HttpStatusCode status = HttpStatusCode.OK;
bool success = status.IsSuccessful(); // true
bool clientError = status.IsClientError(); // false
bool serverError = status.IsServerError(); // false
bool isRedirect = status.IsRedirect(); // false

// URI manipulation
Uri uri = new Uri("https://example.com");
Uri withParam = uri.AddParameter("search", "test"); // https://example.com?search=test

// HTTP Request cloning
using var request = new HttpRequestMessage(HttpMethod.Get, "https://api.example.com");
var clonedRequest = request.Clone();
var clonedAsync = await request.CloneAsync();

Configuration Extensions (PowerCSharp.Extensions.AspNetCore)

using PowerCSharp.Extensions.AspNetCore;
using Microsoft.Extensions.Configuration;

var configuration = new ConfigurationBuilder().Build();
var options = configuration.GetOptions<MyAppOptions>("MyApp"); // Reads from "MyApp" section

Features Framework (PowerCSharp.Features + PowerCSharp.BuiltInFeatures)

// Program.cs
builder.Services.AddPowerFeatures(builder.Configuration, options =>
{
    options.AddBuiltInFeatures();          // opt-in the built-in bundle (CORS, etc.)
    options.ScanAssemblies(              // opt-in pluggable feature assemblies
        typeof(CacheFeatureModule).Assembly);
    options.Override("Cache", true);     // optional code-level override
    options.EnableDiagnosticsEndpoint(); // GET /power-features — off by default
});

var app = builder.Build();
app.UsePowerFeatures();

// appsettings.json
{
  "PowerFeatures": {
    "Cors": { "Enabled": true, "AllowedOrigins": [ "https://example.com" ] },
    "Cache": { "Enabled": true, "Provider": "BitFaster", "Capacity": 1000 }
  }
}

Flag resolution order (highest precedence first): explicit code override → custom IFeatureFlagProvider → environment variables (POWERFEATURES__<KEY>__ENABLED) → appsettings → feature default.

Cache Feature (PowerCSharp.Feature.Cache + provider)

// Resolves to the active provider (BitFaster or Disk) or NoOp if disabled.
var cache = app.Services.GetRequiredService<ICacheService>();

await cache.SetAsync("key", myObject, TimeSpan.FromMinutes(5));
var result = await cache.GetAsync<MyObject>("key");

if (result.Hit)
    Console.WriteLine(result.Value);

LINQ & Dynamic Query Extensions (PowerCSharp.Extensions)

using PowerCSharp.Extensions;

// Dynamic expression parsing
string expression = "Age > 18 && Name.Contains('John')";
var predicate = expression.GetExpressionDelegate<Person>();

// Dynamic ordering
string orderExpression = "Name DESC, Age ASC";
var orderDelegates = orderExpression.GetOrderDelegates<Person>();

// Dynamic filtering and ordering
var filterProvider = new DynamicFilterProvider<Person>();
var orderProvider = new DynamicOrderProvider<Person>();
var filtered = people.Filter(filterProvider);
var ordered = people.Order(orderProvider);

JSON & XML Extensions (PowerCSharp.Extensions)

using PowerCSharp.Extensions;
using System.Text.Json;

// JSON element access
JsonElement element = JsonDocument.Parse("{\"name\":\"John\"}").RootElement;
var name = element.Get("name"); // JsonElement with value "John"
var firstItem = element.Get(0); // For arrays

// Case-insensitive JSON access
bool found = element.TryGetPropertyCaseInsensitive("NAME", out var value);

// XML flattening
using System.Xml.Linq;
XElement xml = XElement.Parse("<root><child>value</child></root>");
var dict = xml.Flatten(); // Dictionary with XML structure

Object & Type Extensions (PowerCSharp.Extensions)

using PowerCSharp.Extensions;

// Object utilities
string text = "test";
text.ThrowOnNull(); // Throws if null

bool isTrue = "true".TryGetBool(out bool result); // result = true, isTrue = true
bool isFalse = "0".TryGetBool(out result); // result = false, isFalse = true

// Generic operations
var person = new Person { Name = "John", Age = 30 };
var copy = new Person();
person.CopyPropertiesTo(copy); // Copies matching properties

// Type operations
bool isDefault = default(int).IsDefault(); // true
string typeName = typeof(List<string>).GetGenericTypeName(); // "List<String>"

// Concrete type resolution
Type concreteType = typeof(IMyInterface).GetConcreteType();

Stream Extensions (PowerCSharp.Extensions)

using PowerCSharp.Extensions;

using var originalStream = new MemoryStream(Encoding.UTF8.GetBytes("test data"));
using var destinationStream = new MemoryStream();

await originalStream.CloneAsync(destinationStream);
// destinationStream now contains the same data as originalStream

Object Hash Extensions (PowerCSharp.Extensions)

using PowerCSharp.Extensions;

var person = new { Name = "John", Age = 30, Email = "john@example.com" };
string hash = person.ComputeHash(); // "A1B2C3D4E5F67890" (16-char hex string)

// Handles complex objects with nested properties
var complexObj = new Order 
{ 
    Id = 123, 
    Customer = new Customer { Name = "Alice" }, 
    Items = new List<Item> { new Item { Name = "Product1" } }
};
string orderHash = complexObj.ComputeHash(); // Consistent hash for caching/identification

Secure Path Extensions (PowerCSharp.Extensions)

using PowerCSharp.Extensions;

string basePath = "/var/www/uploads";
string userFile = "../../etc/passwd"; // Malicious attempt

// This will throw SecurityException due to directory traversal attempt
string safePath = PathExtensions.CombineAndValidate(basePath, userFile);

// Safe usage with valid relative paths
string validPath = PathExtensions.CombineAndValidate(basePath, "images/photo.jpg");
// Returns: "/var/www/uploads/images/photo.jpg"

// Multiple path segments
string multiPath = PathExtensions.CombineAndValidate(basePath, "documents", "2023", "report.pdf");
// Returns: "/var/www/uploads/documents/2023/report.pdf"

Validation Utilities (PowerCSharp.Utilities)

using PowerCSharp.Utilities;

bool isValidEmail = ValidationHelper.IsValidEmail("user@example.com");
bool isNumeric = ValidationHelper.IsNumeric("12345");
bool isValidUrl = ValidationHelper.IsValidUrl("https://example.com");

File Utilities (PowerCSharp.Utilities)

using PowerCSharp.Utilities;

string content = FileHelper.SafeReadAllText("file.txt");
bool success = FileHelper.SafeWriteAllText("output.txt", "Hello World");
string size = FileHelper.GetFileSize(1024 * 1024); // "1 MB"

JSON Helpers (PowerCSharp.Helpers)

using PowerCSharp.Helpers;

var obj = new { Name = "John", Age = 30 };
string json = JsonHelper.SafeSerialize(obj);
var deserialized = JsonHelper.SafeDeserialize<MyClass>(json);
string pretty = JsonHelper.PrettyPrint(json);

Crypto Helpers (PowerCSharp.Helpers)

using PowerCSharp.Helpers;

string sha256 = CryptoHelper.ComputeSHA256("password");
string md5 = CryptoHelper.ComputeMD5("data");
string random = CryptoHelper.GenerateRandomString(10);

🎯 Target Frameworks

• Modern .NET: .NET 8.0 — core libraries, Features engine, BuiltInFeatures, Cache feature modules
• .NET Standard 2.0 + .NET 8.0: PowerCSharp.Features.Abstractions, PowerCSharp.Feature.Cache.Abstractions, PowerCSharp.Feature.Cache.BitFaster — usable from .NET Framework and .NET Core
• .NET Framework: 4.6.2, 4.7.2, 4.8 — via PowerCSharp.Compatibility
• ASP.NET Core: .NET 8.0 — PowerCSharp.Extensions.AspNetCore, Features engine, BuiltInFeatures

🧪 Testing

All PowerCSharp packages include comprehensive unit tests. Run tests with:

dotnet test

📚 Documentation

Package-Specific Documentation

Core libraries

• PowerCSharp.Core - Core interfaces and architecture
• PowerCSharp.Extensions - Cross-platform extension methods reference
• PowerCSharp.Extensions.AspNetCore - ASP.NET Core specific extensions
• PowerCSharp.Utilities - Utility classes guide
• PowerCSharp.Helpers - Specialized helpers reference
• PowerCSharp.Compatibility - .NET Framework compatibility layer

Features framework

• PowerCSharp.Features.Abstractions - Contracts reference
• PowerCSharp.Features - Engine integration guide
• PowerCSharp.BuiltInFeatures - Built-in bundle guide

Cache feature family

• PowerCSharp.Feature.Cache.Abstractions - Cache contracts reference
• PowerCSharp.Feature.Cache - Cache module guide
• PowerCSharp.Feature.Cache.BitFaster - BitFaster provider guide
• PowerCSharp.Feature.Cache.Disk - Disk provider guide

Detailed API Documentation

• PowerCSharp.Core API - Complete core API reference
• PowerCSharp.Extensions API - Cross-platform extensions documentation
• PowerCSharp.Extensions.AspNetCore API - ASP.NET Core extensions API
• PowerCSharp.Utilities API - Utilities API reference
• PowerCSharp.Helpers API - Helpers API documentation
• PowerCSharp.Compatibility API - .NET Framework compatibility API
• Extensions API Reference - Complete extensions catalog
• Features Architecture - Features system design
• Features Authoring Guide - How to build a new feature
• Features Flag Reference - Flag schema and provider precedence
• Cache Feature API - Cache family API reference

Development Documentation

• Examples and Samples - Working code examples
• Contributing Guide - How to contribute
• Security Policy - Security information
• Code of Conduct - Community guidelines
• Changelog - Version history
• Workflow Documentation - Development workflow

🤝 Contributing

Contributions are welcome! Please read our Contributing Guidelines for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

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

🙏 Acknowledgments

• Built with passion by Mario Arce
• Inspired by 20+ years of C# development experience
• Community feedback and contributions

📞 Support

• 🐛 Report Issues
• 💡 Feature Requests
• 📧 Email Support

---

PowerCSharp - Making C# development more powerful, one extension at a time! 🚀