Select Page

An architecture decision record (ADR) explains why a service uses a particular design and when that choice should be revisited. For a C# service, connect one decision to a small executable check: state the contract, record the alternatives, and retain evidence that distinguishes them.

This tutorial documents resource-key identity. In the example service, FILE and file must identify different resources, while registering FILE twice must preserve the first owner. You will write a proposed ADR and test the dictionary behavior it depends on. The service and its requirements are illustrative; the console program below was compiled and run on .NET 10.

Choose a decision that changes a contract

Key identity affects which resource a client can access, so changing it can require a compatibility review. The decision is larger than a preference about dictionary syntax. Keep the ADR focused on this identity rule; leave unrelated choices such as hosting and logging for other records.

Record the problem, alternatives, selected approach, tradeoffs, confidence and status. Keep detailed design material elsewhere and link it when needed. Microsoft recommends recording decisions that shape the system or are costly to reverse. Microsoft’s ADR guidance describes this scope and record structure.

Write the proposed record

Save the following example as docs/decisions/0007-resource-key-identity.md beside the service code. The path and numbering are conventions for this example. Keep it proposed until the cross-layer checks listed in the record are complete.

# ADR-0007: Preserve case in resource-key identity
Status: Proposed (illustrative service decision)
Date: 2026-11-09
Scope: Application-level comparison of resource keys

Context
Clients supply opaque resource keys. The contract permits FILE and file
as separate keys. Re-registering FILE must not change its existing owner.
Changing identity rules could merge resources that clients consider distinct.

Options
1. Ordinal, case-sensitive comparison: preserves the stated identity contract.
2. Ordinal, case-insensitive comparison: convenient for manual entry, but
   collapses FILE and file and violates the current contract.
3. Require lowercase keys: simplifies allowed spelling, but would require
   a client migration and an explicit collision policy for existing keys.

Decision
Use StringComparer.Ordinal in the in-memory resource-key dictionary.
Reject an exact duplicate with TryAdd; preserve its existing owner.
Keep casing significant in the service's documented resource-key contract.

Consequences
Clients must retain exact spelling. Human-friendly search, if needed, must
be designed separately from identity. Other layers must be checked for
compatible behavior before this decision is accepted for the whole service.

Evidence and confidence
Program.cs detects the case-insensitive alternative as a contract failure.
The ordinal implementation passes the two-key and duplicate-owner assertions
under en-US and tr-TR on .NET 10. High confidence for this dictionary behavior;
service-wide consistency remains unverified.

Acceptance and reconsideration
Before acceptance, review client compatibility and test HTTP input handling,
persistence equality/uniqueness rules, and every other resource-key lookup.
Reconsider if clients need case-insensitive identity. Record collision and
migration rules in a new ADR that supersedes this one if it was accepted.

The alternatives explain the cost of a different choice. Case-insensitive identity could be a valid contract for another service, but it conflicts with this example’s existing requirement. Lowercase-only input would require an explicit migration decision. The confidence statement separates the tested component from the service behaviors still awaiting evidence.

Test the claim that supports the decision

Use a .NET 10 console project and replace its entire Program.cs with the program below. It uses only the base class library, with no test-framework package. If collections are new to you, first read the C# generic collections tutorial.

For symbolic identifiers, Microsoft recommends explicit ordinal comparison rather than linguistic comparison. Whether case matters remains your contract choice; this example chooses StringComparer.Ordinal. See Microsoft’s string-comparison guidance. The duplicate assertion also checks the documented behavior of Dictionary.TryAdd: an existing key returns false without replacing its value.

using System;
using System.Collections.Generic;
using System.Globalization;

static void Require(bool condition, string message)
{
    if (!condition) throw new InvalidOperationException(message);
}

static void VerifyContract(IEqualityComparer<string> comparer)
{
    var owners = new Dictionary<string, string>(comparer);
    Require(owners.TryAdd("FILE", "Alice"), "First key must be accepted.");
    Require(owners.TryAdd("file", "Bob"), "Case-distinct key must be accepted.");
    Require(!owners.TryAdd("FILE", "Mallory"), "Exact duplicate must be rejected.");
    Require(owners["FILE"] == "Alice", "Duplicate must not replace the owner.");
    Require(owners["file"] == "Bob", "Case-distinct key must keep its owner.");
    Require(owners.Count == 2, "Exactly two resources must remain.");
}

bool detected = false;
try
{
    VerifyContract(StringComparer.OrdinalIgnoreCase);
}
catch (InvalidOperationException error)
    when (error.Message == "Case-distinct key must be accepted.")
{
    detected = true;
}
Require(detected, "Negative control must fail the case-sensitive contract.");
Console.WriteLine("negative control: case-distinct key rejected (expected contract failure)");

CultureInfo original = CultureInfo.CurrentCulture;
try
{
    foreach (string name in new[] { "en-US", "tr-TR" })
    {
        CultureInfo.CurrentCulture = CultureInfo.GetCultureInfo(name);
        VerifyContract(StringComparer.Ordinal);
        Console.WriteLine($"{name}: case-sensitive contract passed");
    }
}
finally
{
    CultureInfo.CurrentCulture = original;
}
Console.WriteLine("All assertions passed.");

Run the project with:

dotnet run

Expected output:

negative control: case-distinct key rejected (expected contract failure)
en-US: case-sensitive contract passed
tr-TR: case-sensitive contract passed
All assertions passed.

The negative control deliberately supplies OrdinalIgnoreCase to the same assertions. Its second registration fails, and the harness catches only the expected assertion message. An unrelated exception still fails the program. If that alternative unexpectedly passes, the final negative-control assertion throws instead. This checks that the test can distinguish the two policies.

The passing cases each create a fresh dictionary, insert two case-distinct keys, reject an exact duplicate and check both owners and the final count. The culture change is restored in a finally block. No files, network calls or external service state need cleanup. Compilation and exact output were verified in a pinned .NET 10 SDK container with networking disabled and compiler warnings treated as errors.

Keep the evidence within its limits

These assertions establish behavior for the supplied keys in one in-memory dictionary. Two cultures are a useful regression check, not exhaustive coverage of every identifier or locale. The program does not validate key syntax or exercise an ASP.NET endpoint, database, concurrent access, authorization or restart behavior. It is a component-level check, not a service integration test.

Before accepting the ADR for a real service, trace a resource key through request parsing, application lookups and persistence. Add integration checks that register and retrieve both spellings through that actual path, then attempt an exact duplicate and verify the original owner. Inspect storage equality and uniqueness rules as part of that work. A passing dictionary test cannot establish those results. For more on that boundary, see designing C# tests around observable behavior.

Preserve the decision history

Review the proposed ADR with the people responsible for the client contract and storage behavior. Attach the passing test result and any remaining limitations before acceptance. Once accepted, preserve the record. If the decision changes, add a superseding ADR and connect the records in a decision index, following Microsoft’s append-only ADR guidance.

A later case-insensitive contract needs a collision policy, a migration plan and fresh evidence. Keep those reasons in the new record so a future maintainer can understand both decisions.

Share This