Utilities

The CrispyWaffle.Utilities namespace collects small, self-contained building blocks: a chainable query string builder, a lazy value that can be reset and reports load statistics, a dynamic object that serializes to XML or JSON, a phone number value type, and a few contracts for API responses and partial updates.

None of these types need registration. Create them where you need them.

Getting started

using System;
using CrispyWaffle.Utilities;

// Build a query string
var query = new QueryStringBuilder()
    .Add("id", 179)
    .Add("q", "crispy waffle")
    .ToString();                       // "?id=179&q=crispy+waffle"

// Cache an expensive value and reload it on demand
var settings = new LazyResettable<DateTime>(() => DateTime.UtcNow);
var first = settings.Value;            // runs the factory
settings.Reset();
var second = settings.Value;           // runs the factory again

Reference

QueryStringBuilder

public class QueryStringBuilder : NameValueCollection — a chainable builder and parser for URL query strings. Marked [Serializable].

Values are URL-encoded with HttpUtility.UrlEncode when added and decoded by the indexers. Adding a second value to an existing key stores both, comma-separated, and ToString() writes the key once per value.

LazyResettable<T>

public class LazyResettable<T> : ILazyResettable — a lazily created value, like Lazy<T>, that can be discarded with Reset() and recreated on the next access. It counts loads, hits and resets and measures the time spent in the factory. Based on a well-known Stack Overflow answer.

The mode argument controls concurrency:

• PublicationOnly (default): the factory runs outside the lock. Concurrent callers may each run it; the first result stored wins. Every run counts as a load.
• ExecutionAndPublication: the factory runs inside a lock, so only one caller runs it.
• None: no locking. Use it only from a single thread.

Hits counts accesses that find a value already created. The access that creates the value is a load, not a hit.

DynamicSerialization

public class DynamicSerialization : DynamicObject, ISerializable, IXmlSerializable, IEquatable<DynamicSerialization> — a dictionary-backed dynamic object that you fill at run time and serialize as XML or through ISerializable.

The class is marked [Serializable] and [Serializer] (XML format by default), so the serialization helpers can handle it. The key filter (DynamicSerializationOption) changes key names only on output (GetObjectData and WriteXml). Stored keys and GetDictionary() keep the original names.

PhoneNumber

public struct PhoneNumber — a phone number split into country code, region (area) code and local number.

Use ParseBrazilianPhoneNumber from the pt-BR package to build one from text.

ILazyResettable

public interface ILazyResettable — the non-generic contract implemented by LazyResettable<T>, useful for keeping a list of resettable values of different types.

IJsonResponse

public interface IJsonResponse — a minimal shape for API responses.

IUpdateable

public interface IUpdateable — an empty marker interface. Implement it to enable UpdateValues<T> from TypeExtensions, which merges non-default property values from one instance into another.

ErrorResponse

public class ErrorResponse : IJsonResponse — a standard error payload.

ResetLazyStats

public class ResetLazyStats — a snapshot of the counters of a LazyResettable<T>.

DynamicSerializationOption

public enum DynamicSerializationOption — how DynamicSerialization transforms keys on output.

DynamicSerializationException

public class DynamicSerializationException : Exception — thrown by DynamicSerialization.SetMember when an entry cannot be added (null or duplicate key). Marked [Serializable].

Examples

Build a query string from an object

using CrispyWaffle.Attributes;
using CrispyWaffle.Utilities;

var filter = new SearchFilter { Term = "waffle", PageSize = 20, SortBy = "name", Secret = "x" };

var query = new QueryStringBuilder()
    .AddFromType(filter)
    .ToString();                      // "?Term=waffle&Page_size=20&sort=name" (Secret is skipped)

public class SearchFilter
{
    public string Term { get; set; }

    public int PageSize { get; set; }

    [QueryStringBuilderKeyName("sort")]
    public string SortBy { get; set; }

    [QueryStringBuilderIgnore]
    public string Secret { get; set; }
}

Avoid null or empty property values: they go through the empty-value path of Add described in the reference table.

Parse and modify an existing query string

using CrispyWaffle.Utilities;

var builder = new QueryStringBuilder("https://example.com/search?page=1&tag=a");

builder.Add("page", "2", isUnique: true)   // replaces page=1
       .Add("tag", "b");                   // keeps tag=a and adds tag=b

var page = builder["page"];                // "2"
var query = builder.ToString();            // "?page=2&tag=a&tag=b"

Track a resettable cache

using System;
using System.Threading;
using CrispyWaffle.Utilities;

var rates = new LazyResettable<decimal>(LoadRate, LazyThreadSafetyMode.ExecutionAndPublication);
rates.OnReset += (_, _) => Console.WriteLine("Rate cache cleared");

var a = rates.Value;   // load
var b = rates.Value;   // hit
rates.Reset();
var c = rates.Value;   // load

var stats = rates.Stats();
Console.WriteLine($"{stats.Loads} loads, {stats.Hits} hits, {stats.Resets} resets"); // 2 loads, 1 hits, 1 resets

static decimal LoadRate() => 5.25m;

Build a dynamic payload

using CrispyWaffle.Utilities;

dynamic payload = new DynamicSerialization(DynamicSerializationOption.Lowercase);
payload.OrderId = 42;
payload.Status = "Shipped";

var dictionary = ((DynamicSerialization)payload).GetDictionary(); // keys "OrderId", "Status"

When payload is serialized, the keys are written as orderid and status.

See also

• Extension methods for UpdateValues and the query string attribute helpers
• Attributes for QueryStringBuilderKeyName and QueryStringBuilderIgnore
• Serialization
• pt-BR internationalization for parsing Brazilian phone numbers