netcore.utilities

A collection of helpful utilities for working with .NET + projects. These items are used by the IowaComputerGurus Team to aid in unit testing and other common tasks

NuGet Package Information

ICG.NetCore.Utilities

SonarCloud Analysis

Usage

Installation

Install from NuGet

Install-Package ICG.NetCore.Utilities

Register Dependencies

Inside of of your project's Startup.cs within the RegisterServices method add this line of code.

services.UseIcgNetCoreUtilities();

Included C# Objects and Services

Provider Interfaces (for Testability)

Object	Purpose
IDirectoryProvider	Provides a shim around the System.IO.Directory object to allow for unit testing.
IGuidProvider	Provides a shim around the System.Guid object to allow for unit testing of Guid operations.
IFileProvider	Provides a shim around the System.IO.File object to allow for unit testing of file related operations.
IPathProvider	Provides a shim around the System.IO.Path object to allow for unit testing of path related operations
ITimeProvider	Provides a shim around the System.DateTime object to allow for unit testing of date operations
ITimeSpanProvider	Provides a shim around the System.TimeSpan object to allow for unit testing/injection of TimeSpan operations

Services

Service	Purpose
IUrlSlugGenerator	Provides a service that will take input and generate a url friendly slug from the content
IAesEncryptionService	Provides a service that will encrypt and decrypt provided strings using AES symmetric encryption with configured key and IV
IAesDerivedKeyEncryptionService	Provides a service that will encrypt and decrypt provided strings using AES encryption with derived keys from passphrase and salt
IDatabaseEnvironmentModelFactory	Factory to create DatabaseEnvironmentModel objects from connection strings for display purposes

Extension Methods

Extension Class	Purpose
QueryableExtensions	Extension methods for IQueryable to simplify conditional filtering, ordering, paging, and distinct selection
EnumExtensions	Extension methods for Enum types to help display formatted enum values with Display attributes
IdentityExtensions	Extension methods for IIdentity objects to extract claim values

Constants

Class	Purpose
Timezones	Helper constants for standard US timezone values

Detailed Documentation

QueryableExtensions

Extension methods for IQueryable<T> that provide conditional querying capabilities.

Available Methods:

• WhereIf - Conditionally applies a filter to the query

  var results = dbContext.Users
      .WhereIf(filterByActive, u => u.IsActive)
      .WhereIf(!string.IsNullOrEmpty(searchTerm), u => u.Name.Contains(searchTerm));
  ````

• OrderByIf - Conditionally applies ascending order to the query

  var results = dbContext.Users
      .OrderByIf(sortByName, u => u.Name);

• OrderByDescendingIf - Conditionally applies descending order to the query

  var results = dbContext.Users
      .OrderByDescendingIf(sortByNewest, u => u.CreatedDate);

• GetPage - Returns a specific page of results (1-based page numbers)

  var results = dbContext.Users
      .OrderBy(u => u.Name)
      .GetPage(pageNumber: 2, pageSize: 10);

• DistinctBy - Returns distinct elements by a specified key selector

  var uniqueUsers = dbContext.Users
      .DistinctBy(u => u.Email);

EnumExtensions

Extension methods for working with Enum types and their Display attributes.

Available Methods:

• GetDisplayNameOrStringValue - Returns the Display Name attribute value or the enum's string value

  public enum Status
  {
      [Display(Name = "Active User")]
      Active,
      Inactive
  }
  
  var displayName = Status.Active.GetDisplayNameOrStringValue(); // "Active User"
  var defaultName = Status.Inactive.GetDisplayNameOrStringValue(); // "Inactive"

• GetDisplayName - Gets the Display Name attribute value (throws if not found)

  var displayName = Status.Active.GetDisplayName(); // "Active User"

• HasDisplayName - Checks if an enum value has a Display attribute

  var hasDisplay = Status.Active.HasDisplayName(); // true
  var hasDisplay = Status.Inactive.HasDisplayName(); // false

IdentityExtensions

Extension methods for working with IIdentity and claims.

Available Methods:

• GetClaimValue - Extracts the value of a specific claim type from a ClaimsIdentity

  // In a Razor view or controller
  var firstName = User.Identity.GetClaimValue("Profile:FirstName");
  var email = User.Identity.GetClaimValue(ClaimTypes.Email);

AesEncryptionService

Service for AES symmetric encryption with pre-configured key and IV values.

Configuration: Add the following to your appsettings.json, Environment Variables, or any other configuration source to your application

"AesEncryptionServiceOptions": {
  "IV" : "VALUE",
  "Key" : "Value"
}

Usage:

public class MyService
{
    private readonly IAesEncryptionService _encryptionService;
    
    public MyService(IAesEncryptionService encryptionService)
    {
        _encryptionService = encryptionService;
    }
    
    public void EncryptData()
    {
        var encrypted = _encryptionService.Encrypt("sensitive data");
        var decrypted = _encryptionService.Decrypt(encrypted);
    }
}

AesDerivedKeyEncryptionService

Service for AES encryption using derived keys from a passphrase and salt (using Rfc2898DeriveBytes).

Configuration:

"AesDerivedKeyEncryptionServiceOptions" : {
  "Passphrase": "YourPassphrase"
}

Usage:

public class MyService
{
    private readonly IAesDerivedKeyEncryptionService _encryptionService;
    
    public MyService(IAesDerivedKeyEncryptionService encryptionService)
    {
        _encryptionService = encryptionService;
    }
    
    public void EncryptData()
    {
        var salt = "unique-salt-value";
        var encrypted = _encryptionService.Encrypt("sensitive data", salt);
        var decrypted = _encryptionService.Decrypt(encrypted, salt);
    }
}

DatabaseEnvironmentModelFactory

Factory for creating DatabaseEnvironmentModel objects from connection strings.

Usage:

public class MyService
{
    private readonly IDatabaseEnvironmentModelFactory _factory;
    
    public MyService(IDatabaseEnvironmentModelFactory factory)
    {
        _factory = factory;
    }
    
    public void DisplayDbInfo()
    {
        var connectionString = "Server=myserver;Database=mydb;...";
        var model = _factory.CreateFromConnectionString("MyDatabase", connectionString);
        
        Console.WriteLine($"Server: {model.ServerName}");
        Console.WriteLine($"Database: {model.DatabaseName}");
    }
}

Timezones

Static class containing constants for standard US timezone values.

Available Constants:

• Timezones.AlaskanStandardTime
• Timezones.AtlanticStandardTime
• Timezones.CentralStandardTime
• Timezones.EasternStandardTime
• Timezones.HawaiianStandardTime
• Timezones.PacificStandardTime
• Timezones.MountainStandardTime

Usage:

var centralTime = TimeZoneInfo.FindSystemTimeZoneById(Timezones.CentralStandardTime);
var convertedTime = TimeZoneInfo.ConvertTime(DateTime.UtcNow, centralTime);

Additional Information

For more detailed information, please refer to the XML documentation comments in the source code. All public APIs are fully documented with parameter descriptions, return values, and usage examples.