Ploch.Common Libraries

A comprehensive collection of .NET utility libraries providing extension methods, helpers, and utilities to simplify everyday development tasks and reduce boilerplate code.

Table of Contents

• Overview
• Support the Project
• Installation
• Versioning and Releases
• Core Library (Ploch.Common)
  • String Extensions
  • Collection Extensions
  • Guard Clauses (Parameter Validation)
  • IsIn Extensions
  • Type Extensions (Reflection)
  • Path Utilities
  • Randomizers
• Extended Libraries
• Real-World Examples

Overview

Ploch.Common is a suite of .NET libraries targeting netstandard2.0 and net8.0+, offering:

• Rich Extension Methods for strings, collections, types, and more
• Parameter Validation with fluent Guard APIs
• Reflection Utilities for type inspection and manipulation
• I/O Helpers for path operations
• Testing Support with random data generators
• Dependency Injection extensions
• Serialization abstractions (JSON, XML)
• And much more...

Support the Project

If Ploch.Common saves you time or makes your projects nicer, please consider supporting its development. Every coffee directly funds time spent on maintenance, bug fixes, and new features.

Thank you for keeping open-source maintainers caffeinated.

Installation

# Core library
dotnet add package Ploch.Common

# Additional libraries
dotnet add package Ploch.Common.DependencyInjection
dotnet add package Ploch.Common.Serialization
dotnet add package Ploch.Common.Serialization.SystemTextJson
dotnet add package Ploch.TestingSupport

Versioning and Releases

This project uses Nerdbank.GitVersioning (NBGV) for automatic version computation from version.json and git commit history.

• Stable releases are published to NuGet.org via the Release workflow
• Prerelease packages are published to GitHub Packages on every push to main
• SourceLink is enabled — step into library source code during debugging
• Symbol packages (.snupkg) are published to the NuGet symbol server

Cutting a Release

1. Go to Actions → Release workflow → Run workflow
2. Enter the release version (e.g. 3.0) — the patch version is computed by NBGV
3. Optionally enter the next development version (defaults to minor increment)
4. The workflow builds, tests, publishes to NuGet.org, creates a GitHub Release, and bumps the version

Checking the Current Version Locally

dotnet tool restore
dotnet nbgv get-version

Core Library (Ploch.Common)

String Extensions

Convenient extension methods for common string operations.

Null/Empty Checking

using Ploch.Common;

string? value = GetValue();

// Check if string is null or empty
if (value.IsNullOrEmpty())
{
    // Handle empty string
}

// Check if string is NOT null or empty
if (value.IsNotNullOrEmpty())
{
    ProcessValue(value);
}

// Check for whitespace
if (value.IsNullOrWhiteSpace())
{
    // Handle whitespace-only string
}

// Convert empty strings to null
string? result = "".NullIfEmpty(); // Returns null
string? result2 = "   ".NullIfWhiteSpace(); // Returns null

String Conversion and Encoding

using Ploch.Common;

// Parse to integers
string number = "42";
int value = number.ToInt32(); // Returns 42
long bigValue = number.ToInt64(); // Returns 42L

// Safe conversion with TryConvert
if (number.TryConvertToInt32(out int result))
{
    Console.WriteLine($"Parsed: {result}");
}

// Base64 encoding/decoding
string original = "Hello, World!";
string encoded = original.ToBase64String(); // Encodes to base64
string decoded = encoded.FromBase64String(); // Decodes back

以上為 README 的開頭部分。其餘內容請閱讀原文。 檢視完整 README ↗