DEV Community: Ivan Rossouw

Graceful Degradation Must Fail Closed

Ivan Rossouw — Tue, 11 Aug 2026 06:00:20 +0000

Graceful degradation sounds simple: if one dependency is unavailable, keep the independent parts of the application running.

That is the right goal. The trap is treating degraded mode as one boolean that turns a feature off. In a routed web application, each endpoint sits inside a graph of framework services, middleware, policies, and downstream systems. Removing one dependency does not remove the others.

A recent committed change made that distinction unusually clear.

One extra path segment changed the result

The host had two broad capabilities:

public pages that could render without a database;
a private area backed by a database and an identity store.

The desired degraded state was reasonable. If the database configuration was absent, public pages should remain available and the private capability should report that it was unavailable.

An initial fallback middleware checked the private path prefix and returned a controlled response. A nearby child URL produced the expected result, so the approach appeared sound.

The exact protected route behaved differently. It matched a real endpoint decorated with an authorization requirement. The framework reached endpoint authorization before the fallback could compensate. Because no authentication scheme had been registered in that configuration, the request ended as a bare 500.

The lookalike URL had tested a different pipeline.

Degraded mode is a dependency graph

The public pages had shed their database dependency. The protected endpoint had not shed its dependency on ASP.NET Core's authentication and authorization contracts.

That leads to a useful rule:

If an endpoint remains mapped, keep the framework contracts required to process it valid in every supported configuration.

For a protected route, “valid” does not mean pretending that sign-in can succeed. It means the security pipeline remains coherent and fails closed.

A simplified shape looks like this:

if (identityStoreIsAvailable)
{
    services.AddTheRealIdentityStore();
}
else
{
    services.AddAuthentication("Unavailable")
        .AddCookie("Unavailable");
}

services.AddAuthorization();

Authentication and authorization middleware can then remain unconditional. In the unavailable branch, nobody can become authenticated because there is no identity store behind the fallback scheme. The protected endpoint challenges safely instead of throwing or accidentally opening.

The important idea is not this exact registration. It is the explicit unavailable implementation. Missing infrastructure is represented as a supported state rather than as an incomplete application.

Give each route an honest outcome

Once the security pipeline was coherent, the application could express several outcomes deliberately:

independent public pages continued to return success;
database-dependent access paths returned an honest unavailable response;
an anonymous request in the healthy configuration was challenged normally;
no protected route failed open;
no supported configuration produced an unhandled exception.

This is more precise than asking whether “the site” is up. Parts of the host can have different availability without weakening the security boundary between them.

Liveness and readiness answer different questions

There is an operational trade-off. If public pages are intentionally database-free, a liveness probe can remain green while the private capability is unavailable.

That is not dishonest if the probes are named and monitored correctly:

Liveness: Is the process running and able to serve independent work?
Readiness: Are the dependencies required for the full capability available?

The unavailable state must also be loud in logs. Otherwise graceful degradation can turn into silent degradation: users see only the healthy surface while operators miss a broken private one.

This design adds configuration branches, a fallback scheme, route-specific responses, and monitoring semantics. The return is a smaller failure domain and a security posture that remains fail-closed.

Turn the discovery into a route matrix

The most valuable follow-up is an integration-test matrix built around exact endpoints, not representative-looking strings.

For each supported dependency state, exercise:

an independent public route;
the exact protected route;
a near-miss or unmatched route;
the sign-in entry point;
liveness and readiness.

Assert the intended status or redirect for each cell. Also assert two negative properties across the whole matrix: no 500 responses and no authorization bypass.

The committed change was manually checked across configured and unconfigured states. That was enough to expose the framework-ordering mistake. Encoding the same matrix as integration tests would turn the discovery into a durable contract.

Practical takeaway

When designing graceful degradation, list capabilities first, then trace every mapped route through routing, authentication, authorization, storage, and external services. Decide which dependencies each route may shed and which framework contracts must remain intact.

Finally, test the exact route through the real pipeline. A lookalike URL can make a broken fallback look correct.

Never Let Migration Tooling Guess the Database

Ivan Rossouw — Sun, 09 Aug 2026 07:57:33 +0000

One of the more dangerous database configuration errors is not a failed connection. It is a successful connection to a database nobody deliberately selected.

That is why an EF Core design-time DbContext factory deserves more scrutiny than “CLI plumbing”. It decides how tooling constructs the model outside the application’s normal startup path. If it also searches broadly for connection details, it can grant a migration command ambient authority.

A recent committed cleanup made this concrete for me. One design-time factory still fell back to configuration owned by an application host that no longer owned the module. The runtime architecture had been separated, but the tooling still crossed the old boundary.

The change removed that fallback. The lesson is broader: design-time configuration is a database-safety boundary.

A fallback is an authority decision

Application startup often combines JSON files, environment variables, secret stores, and deployment configuration. That flexibility is useful because the running application has a defined environment and composition root.

The EF Core CLI operates in a different context. It may run from a module directory, a developer workstation, or CI. A design-time factory that walks the repository or borrows another host’s settings can discover a connection string the operator never consciously selected.

The unintended target does not have to be production to cause harm. It might be a shared development database, an integration environment, or a database belonging to another application boundary. The problem is the same: success looks legitimate even though intent was never established.

Convenient fallback logic answers a security-relevant question: “If no target was chosen, which target should the tool receive?” The safest answer is none.

Model construction is not connection authority

Throwing immediately when configuration is absent is safe, but it can be unnecessarily blunt. Several design-time operations need the model and migration assembly, not a live database. Developers should be able to inspect or scaffold migrations without carrying database credentials.

This gives us two distinct capabilities:

Construct the model for offline design-time work.
Open a database connection and potentially change state.

They should not share an implicit permission boundary.

A useful pattern is to let the provider options use an unmistakably unreachable sentinel when no connection is configured. Model-only commands can still create the context. Any operation that opens a connection fails with a recognisable error instead of guessing a real target.

A generic factory shape

The following example is intentionally generic. The sentinel value is provider-specific and belongs in a small, clearly named helper; it should never resemble a real server.

public sealed class DesignTimeFactory
    : IDesignTimeDbContextFactory<AppDbContext>
{
    public AppDbContext CreateDbContext(string[] args)
    {
        var explicitRoot = Environment.GetEnvironmentVariable(
            "MIGRATIONS_CONFIG_PATH");

        var root = string.IsNullOrWhiteSpace(explicitRoot)
            ? Directory.GetCurrentDirectory()
            : explicitRoot;

        var configuration = new ConfigurationBuilder()
            .SetBasePath(root)
            .AddJsonFile(
                "appsettings.DesignTime.json",
                optional: true)
            .AddEnvironmentVariables(prefix: "MIGRATIONS_")
            .Build();

        var configuredConnection = configuration
            .GetConnectionString("Database");

        var connection = string.IsNullOrWhiteSpace(
            configuredConnection)
            ? UnreachableDesignTimeConnection.Value
            : configuredConnection;

        var options = new DbContextOptionsBuilder<AppDbContext>()
            .UseSqlServer(connection)
            .Options;

        return new AppDbContext(options);
    }
}

The useful properties are more important than the exact APIs:

An explicit root controls where design-time files are read.
The current directory is a local, visible fallback.
Environment variables are added last, so matching values override files.
No unrelated application host is searched.
Missing connection authority produces an impossible target, not a plausible default.

Avoid using localhost, a familiar shared server, or an empty value as the sentinel. localhost may contain real data. A familiar name defeats the boundary. An empty value may prevent the provider from constructing options, which blocks the offline work we are trying to preserve.

The sentinel is only a defensive default. It does not replace least-privilege credentials, network controls, deployment review, backups, or a safe migration process.

Test both sides of the boundary

Tests should describe the capability split, not merely prove that the factory returns a context.

Useful checks include:

With no configuration, a model-only command can construct the context.
With no configuration, a connecting command fails against the recognisable sentinel.
With explicit configuration, a connecting command reaches only an isolated disposable database.
Configuration precedence is deterministic and documented.
Narrowing the configuration path does not change the model or hide migration history.

The last check matters because a safety refactor should not accidentally produce schema drift. In the committed change that prompted this lesson, the recorded verification covered the existing test suite, migration discovery, and a model-drift check. This scheduled review did not rerun repository commands, so I treat those as committed evidence rather than fresh execution results.

Make invisible trust visible

There is a real trade-off. Explicit configuration adds ceremony. A missing setting may not fail until a command actually tries to connect. Developers need a short guide explaining which commands work offline and how to opt into database access.

That cost is modest compared with ambiguous success.

Design-time tools sit outside the normal runtime composition root, but they can still hold production-capable privileges. Review their fallbacks as authorisation decisions. Removing one ambient source does not validate every remaining source; it removes one unintended-target path. Keep model work easy, narrow the permitted sources, and make missing configuration conspicuous.

Where does your migration workflow still select authority on the operator’s behalf?

Make Invalid Identifier Formats Unrepresentable

Ivan Rossouw — Sat, 08 Aug 2026 11:28:53 +0000

The dangerous identifier bug is not always malformed input. Sometimes both values are valid, both parse successfully, and both refer to the same conceptual thing. They simply use different textual representations.

That sounds cosmetic until a storage boundary compares them as raw strings.

I recently reviewed a committed .NET refactor built around exactly that failure mode. One boundary stored a compact canonical key. Elsewhere, a runtime identifier was converted with another valid representation. The lookup returned no rows. Then the reader supplied a plausible default, so the application continued without an exception.

The result was not obviously broken software. It was quietly wrong software.

Two valid values can still disagree

A Guid has several standard string formats. A database, cache, external API, or configuration catalogue may choose one of them as its canonical key. If another layer uses a different valid format, parsing both values proves very little. Raw equality still fails.

The risk grows when “not found” is intentionally convenient:

runtime identifier
    -> valid but non-canonical string
    -> exact lookup returns no row
    -> reader supplies defaults
    -> caller treats defaults as configured data

Every step can be locally reasonable. Together they create a silent semantic failure.

That failure direction matters. A thrown exception attracts attention. A believable fallback can survive code review, automated tests, and monitoring because the system remains green.

A helper method is still a convention

The first repair is usually to change one conversion call. That fixes the immediate defect, but it leaves the real contract implicit:

Task<Settings> LoadAsync(string key);

Nothing in this signature tells a caller which representation is required. Any string compiles. A nearby comment or helper improves discoverability, but the compiler still cannot help.

The same mistake can return six months later in a new call site, during a refactor, or inside a test fake that ignores the supplied key.

If representation changes lookup semantics, the representation is part of the type.

Put canonicality at the service seam

A small value type can make the contract explicit:

Task<Settings> LoadAsync(CatalogKey key);

var key = CatalogKey.From(runtimeId);
var settings = await store.LoadAsync(key);

The exact implementation is less important than the responsibilities:

one factory converts the runtime identifier into the canonical form;
one parser validates compact input, normalises case, and rejects hyphenated or malformed input;
equality follows the canonical representation;
service contracts accept the semantic key, not an arbitrary string;
consumers unwrap the value only at the storage boundary.

Now a raw Guid or string cannot cross the seam accidentally. The caller must make the conversion decision explicitly, at a place where reviewers can see it.

This is a useful modular-architecture pattern: translate once at the boundary, then carry a truthful type inside the module.

Make the default value fail loudly

C# value types have one awkward edge: default(T) exists even when no public constructor permits an empty value.

Returning an empty string from an uninitialised key would recreate the original failure. The lookup would miss, the reader could fall back, and the invalid state would again appear healthy.

For a boundary type like this, reading an uninitialised value should fail loudly. If callers genuinely need optionality, represent it explicitly with a nullable key or a result type. Do not let “missing” masquerade as a valid empty key.

This is an important test case because factory-only tests cannot reach the runtime's zero-initialisation path.

Migrate incrementally without claiming total safety

Changing every string-based seam at once may create an unnecessarily large blast radius. The reviewed refactor migrated several related service contracts first and retained an architecture guard for older seams that still accepted raw strings.

That is a pragmatic transition:

introduce the semantic type;
migrate the highest-risk boundary cluster;
test factories, parsing, equality, and the default instance;
keep a focused guard around the remaining convention-based surface;
remove the guard only when the raw-string path truly disappears.

The type protects only APIs that require it. Keeping the guard acknowledges that partial migration honestly.

The trade-off: useful friction

Strong boundary types create work. Signatures change. Call sites need explicit conversions. ORMs may require unwrapping to a local scalar before translating a query. Test fixtures that relied on permissive fakes may need more realistic assertions.

That friction is the point when the alternative is a silent miss.

A raw string optimises for movement. A semantic key optimises for correctness, discoverability, and reviewability. Use it where representation carries business or storage meaning, not for every incidental string in the application.

A practical checklist

Before leaving an identifier as a string, ask:

Can the same identifier have multiple valid representations?
Does the downstream system compare the representation exactly?
Can “not found” become a plausible default rather than an error?
Is the required format visible in the method signature?
Are uninitialised, malformed, and alternative-format paths tested?
Are remaining raw-string seams still guarded during migration?

If several answers make you uncomfortable, the string convention is already a domain concept. Give it a name, give it a type, and make the wrong representation difficult to express.

Test the Wire, Not the Serializer

Ivan Rossouw — Fri, 07 Aug 2026 14:33:11 +0000

Two JSON serializers can each behave correctly and still fail when they meet.

That sounds obvious in hindsight, but it is easy to miss in a .NET solution. An ASP.NET Core server may use System.Text.Json by default while a long-lived typed client, shared library, or older integration still uses Newtonsoft.Json. Both libraries can serialise ordinary objects. Both can pass their own round-trip tests. The failure appears only when one writes the payload and the other reads it.

A recent committed C# fix made the distinction concrete. The private domain details are not important. The reusable lesson is: a same-serializer round trip proves self-consistency, not interoperability.

The mismatch hides at the real boundary

Imagine a response containing an abstract base type with two supported derived shapes:

[JsonPolymorphic(TypeDiscriminatorPropertyName = "kind")]
[JsonDerivedType(typeof(ImmediateRule), "immediate")]
[JsonDerivedType(typeof(WindowRule), "window")]
public abstract record DeliveryRule;

System.Text.Json understands those attributes and writes a discriminator such as "kind": "window". A Newtonsoft.Json consumer does not automatically interpret System.Text.Json's polymorphism metadata. It sees the abstract base type, cannot choose a concrete type, and fails to construct the object.

Nothing is malformed on the wire. The producer followed its contract. The consumer followed a different contract.

This is why an in-process path may work while a REST-backed path fails. The in-process path never serialises. It passes the object directly and quietly bypasses the boundary that is broken.

Treat polymorphism as a wire protocol

Once a payload carries derived types, the discriminator is not an implementation detail. It is protocol data.

The contract needs to answer a few explicit questions:

What property identifies the concrete shape?
Which discriminator values are supported?
Are names case-sensitive?
Which fields are required for each shape?
What happens when the value is missing or unknown?
Must the contract work in one direction or both?

Attributes on a C# type answer those questions only for libraries that understand the attributes. They do not make the protocol universal.

In the change I reviewed, the practical repair was a compatibility converter for the second serializer. It read the discriminator emitted by the server and constructed the correct derived shape. Its write path emitted the same discriminator so payloads could also travel in the reverse direction.

Cross the boundary in the test

The most valuable change was not the converter. It was the direction of the tests.

A weak test looks like this:

var wire = System.Text.Json.JsonSerializer.Serialize(value, options);
var copy = System.Text.Json.JsonSerializer.Deserialize<BaseType>(wire, options);

That is useful, but it asks one library whether it agrees with itself.

An interoperability test should model the deployed path:

var wire = System.Text.Json.JsonSerializer.Serialize(envelope, serverOptions);
var received = Newtonsoft.Json.JsonConvert.DeserializeObject<Envelope>(wire);

If the reverse direction exists, test that separately:

var wire = Newtonsoft.Json.JsonConvert.SerializeObject(value);
var received = System.Text.Json.JsonSerializer.Deserialize<BaseType>(wire, serverOptions);

Then repeat the test for every supported derived shape. A single happy subtype can hide a missing discriminator, a date-format difference, enum handling, nullability, or a field that only exists on another subtype.

Also include a negative test for an unknown discriminator. Silently defaulting to a base shape can be more dangerous than failing, because it turns contract drift into plausible but incomplete data.

The adapter has a cost

An explicit converter duplicates contract knowledge. The base type, each serializer's configuration, the converter, and the tests must evolve together. Adding a subtype is no longer a one-line change.

Standardising the whole system on one serializer can remove that duplication. It may also be a broad migration touching clients, stored payloads, casing, date handling, enum representation, reference loops, and error behaviour. A narrow adapter is often the safer repair when compatibility matters immediately.

There is another implementation trap: a converter attached to a base type can re-enter itself if it delegates deserialisation of the derived type through the same configured serializer. Depending on the library, constructing the derived record explicitly or using a converter-free inner path can avoid recursion. Pin that behaviour with a focused test rather than relying on intuition.

A practical contract-test checklist

Before calling a JSON contract covered, write down:

The actual producer library and configuration.
The actual consumer library and configuration.
Every supported polymorphic shape.
The discriminator and required fields.
Unknown, missing, null, and malformed behaviour.
Every direction the payload travels in production.

The unit of confidence is not "this serializer can round-trip this type." It is "this producer's bytes can be consumed by that reader without losing meaning."

Where are your contract tests still testing each endpoint in isolation instead of crossing the wire between them?

Reconcile Before You Expire: Authority Checks at Irreversible Boundaries

Ivan Rossouw — Thu, 06 Aug 2026 10:53:57 +0000

Expiry looks like housekeeping. A timestamp passes, a background worker finds the stale row, and the system moves it to a terminal state.

That model is safe only when your database is authoritative for the outcome. The moment another system can complete the work, a timeout becomes much weaker evidence. It tells you that your local clock ran out. It does not prove that nothing happened elsewhere.

A recent committed C# change made this distinction concrete. The implementation and names are private, but the lesson is broadly useful: before an expiry worker made an irreversible local transition, it first reconciled with the external authority.

The Failure Hidden Inside a Timer

Consider a generalized hosted operation:

Your application creates an intent with immutable expected values.
An external system accepts the operation and returns a reference.
The user or caller leaves your process.
A callback or browser return normally confirms the result.
Your local intent eventually reaches its expiry time.

The dangerous assumption is step five: “No callback arrived, therefore the external operation did not complete.”

Callbacks are delivery mechanisms, not proof of non-completion. A browser can close. A webhook can be delayed. A network path can fail after the external commit but before your acknowledgement. The local row can remain stale while the external outcome is already final.

If a cleanup worker then marks that row expired, the data looks tidy while the business truth becomes harder to recover.

Authority Is an Architectural Relationship

The central design question is not “Which service runs the expiry job?” It is “Which system owns the fact we are about to assert?”

Your database may be authoritative for your workflow state. The external system may still be authoritative for whether its operation completed. Those are different facts.

That gives us a useful rule:

Before an irreversible transition, reconcile with the system that owns the outcome.

In practical terms, a worker can select expired candidates, find the external reference, locate a verifier for that kind of operation, and ask for the current outcome. A confirmed result should only be accepted when it matches the local intent’s frozen invariants, such as identity and expected value. Then the confirmation must be persisted before cleanup continues.

The expiry worker does not invent new truth. It asks the authority and applies an already-defined verification contract.

Preserve “Uncertain” as a Real State

Distributed workflows rarely have only two honest answers. They usually have three:

Confirmed and matching: advance the workflow and persist the result.
Clearly not completed: follow the normal expiry path.
Unavailable, conflicting, or ambiguous: preserve evidence and route to review.

Collapsing the third answer into “failed” is where reliability problems become data-integrity problems.

Suppose the authority times out during reconciliation. Failing the entire sweep may create a retry storm and block unrelated candidates. Expiring the operation anyway is worse: absence of an answer has been treated as a negative answer.

A safer compromise is failure isolation. Log the verification problem, retain the external reference and relevant audit evidence, move the candidate to a reviewable state, and let the sweep continue. Uncertainty remains visible and recoverable.

This pattern also makes operational ownership clearer. The manual-review queue is not an embarrassment. It is the explicit cost of refusing to manufacture certainty.

The Trade-Off Is Real

Reconciliation adds work:

another network dependency in a scheduled process;
extra latency and provider load;
rate-limit and back-off concerns;
longer retention for ambiguous records;
an operational queue that someone must own;
more state-transition and concurrency tests.

Those costs should be designed, not ignored. Batch candidates. Bound concurrency. Use cancellation and timeouts. Record the last reconciliation attempt. Back off repeated uncertainty. Make confirmation idempotent. Prevent a concurrent callback and the sweep from applying contradictory transitions.

The return is not merely “fewer bugs.” It is a stronger integrity boundary. An automated cleanup task can no longer silently overwrite a result owned elsewhere.

Test the Missed-Acknowledgement Paths

A happy-path expiry test proves very little. The valuable regression tests exercise the boundary:

Completed, but the acknowledgement was missed

The external verifier reports a matching completion. The worker persists it and does not expire the operation.

The authority is unavailable

Verification throws or times out. The sweep continues, but the operation retains its evidence and moves to review rather than a clean terminal failure.

The authority does not confirm completion

The worker follows the documented evidence-preserving policy. Depending on the remaining evidence, that may mean normal expiry or review. The important part is that a single inconclusive query does not erase stronger durable evidence.

I would add two more tests where risk justifies them: a callback racing the sweep, and a repeated reconciliation proving idempotency.

Where Else This Applies

The same authority check appears far beyond one kind of integration:

a deployment controller deleting resources after a local timeout;
a message dispatcher retrying when the broker may already have accepted the message;
a provisioning job rolling back while the cloud control plane is still converging;
a refund workflow closing locally before the financial system settles;
a reservation expiring while the downstream allocation already exists.

Whenever another system can cross the irreversible boundary, your cleanup job needs more than a clock.

A Practical Review Checklist

Before shipping an expiry or cleanup worker, ask:

Which system is authoritative for the outcome?
Can completion occur without our acknowledgement arriving?
What durable reference lets us reconcile later?
Which invariants must match before we accept confirmation?
What state preserves uncertainty without blocking the whole batch?
Are confirmation, retry, and concurrent callbacks idempotent?

Timeouts are useful scheduling signals. They are not universal evidence of failure. At an irreversible boundary, ask the authority, match the facts, and preserve ambiguity.

Where does one of your cleanup jobs currently make a decision that belongs to another system?

A URL Is Only Safe for the Sink That Consumes It

Ivan Rossouw — Wed, 05 Aug 2026 11:55:54 +0000

Safety is not a permanent property of a string. A value can be acceptable in one browser context and dangerous in another.

That sounds obvious when we compare HTML text with executable script. It is easier to miss when both values look like URLs.

A recent committed correction I reviewed had exactly that shape. A shared resolver had been designed for asset sources. In that context, the application intentionally supported a wider set of values, including inline media. The same resolver was then reused for clickable anchors. Its name still sounded reassuring, but the destination had gained more power: the browser could now navigate when a person clicked the value.

The lesson is simple: validate for the sink that consumes the value.

One resolver was doing two different jobs

Consider these two destinations:

<img src="...">
<a href="...">Open document</a>

Both attributes receive a URL-shaped string, but they are not the same contract. An application may deliberately permit a constrained inline image source while refusing that same scheme as a navigation target. An anchor can also hand control to an external origin or a custom application handler.

A helper called something broad such as NormaliseUrl hides this difference. Callers see a normalised string and may infer that it is safe everywhere. The helper has accidentally become a security promise it cannot keep.

Prefer contracts that name the destination: ResolveAssetSource, ResolveAnchorHref, or another equally explicit boundary.

Resolve first, then apply policy

Validation order matters. Relative values may be combined with a trusted base URI, while absolute values can ignore that base entirely. A check performed only on the raw input can therefore approve one shape and produce another after resolution.

The safer sequence is:

Trim and normalise the input.
Resolve it against the expected base when appropriate.
Parse the final result.
Apply the allowlist for the exact destination.
Return a deliberate, non-executable fallback when the policy rejects the scheme.

Here is a simplified, newly written example:

static string SafeAnchorHref(string? raw, Uri origin)
{
    if (string.IsNullOrWhiteSpace(raw))
        return "#";

    var normalised = raw.Trim().Replace('\\', '/');
    if (normalised.StartsWith("//", StringComparison.Ordinal))
        return "#";

    var resolved = ResolveAgainstOrigin(normalised, origin);

    return IsAllowedForAnchor(resolved, origin)
        ? resolved
        : "#";
}

A # fallback prevents external or script-scheme navigation, but it can still affect scroll position or history. Where the interface must truly do nothing, render plain text or omit the link instead.

The exact policy will differ by product. Some systems may need mail links or a carefully controlled app scheme. The important part is that each additional capability is explicit, reviewed, and tested. “Anything URI-shaped” is not a useful allowlist.

A scheme allowlist only controls what the browser may execute or delegate. It does not prove that an HTTP or HTTPS destination is trustworthy; origin policy, redirect handling, download policy, and content controls are separate decisions.

Make rejection boring

Security controls work better when rejected data degrades predictably.

For a document list, that might mean keeping a safely encoded display label but replacing the navigation target with a same-document fragment. Another interface might render plain text instead of an anchor. Either choice is preferable to throwing during rendering or letting the browser interpret an unexpected scheme.

Display text and navigation data should also be separate. Decoding an encoded filename for readability does not mean the decoded string should become the href. The label goes through HTML text encoding; the resolved navigation value goes through the anchor policy.

This separation makes both behaviours easier to reason about.

A new tab is another boundary

Opening external links in a new tab or window adds a second small contract. Set the component’s real target parameter rather than assuming an arbitrary attribute will survive rendering. Pair a blank target with noopener and noreferrer when that matches the product’s privacy policy.

These details are easy to dismiss as markup polish. They control whether the opened page can reach its opener and whether it receives a referrer.

Test boundary shapes, not only happy URLs

The focused tests in the reviewed change were valuable because they described the boundary, not the implementation. A useful anchor-policy suite should include:

mixed-case script-capable schemes;
inline-data, blob, file, intent, and unknown custom schemes;
protocol-relative values;
malformed and blank input;
valid HTTP and HTTPS URLs;
root-relative paths and fragments;
percent-encoded filenames;
the expected target and relationship attributes.

Also test the asset-source policy separately. A security fix for anchors should not silently break a legitimate image path elsewhere.

The trade-off: compatibility for explicit safety

A narrow allowlist can replace old dirty links with a same-document fallback. It can also block a legitimate integration until its scheme is deliberately supported. That is real compatibility work, not a reason to keep the boundary broad.

The alternative is worse: a generic helper quietly expands its promise as it moves into more powerful contexts. Rejection is deterministic, fails closed, and leaves the underlying data repairable. An unsafe navigation path may remain unnoticed until someone supplies the wrong stored value.

My practical rule is now: when data crosses into a browser attribute, name the sink, validate the final resolved value, and test every capability you intend to allow.

Where in your application does a “safe” URL move between contexts with different powers?

Your Blazor Test Is Racing the Renderer

Ivan Rossouw — Tue, 04 Aug 2026 06:12:12 +0000

A flaky component test can look almost insultingly simple: the test finds a button, raises its event, and occasionally observes nothing. The tempting responses are familiar - add a delay, retry the interaction, or blame the component's asynchronous work.

Sometimes the more useful question is: which render did the test actually interact with?

A recent focused test correction highlighted a narrow Blazor lesson. The test located an element and dispatched its event as separate steps outside one renderer-owned action. An asynchronous re-render could occur between those steps. The stored element then belonged to an older render tree, and the test no longer had a reliable path to the current handler.

The correction was small: schedule element lookup and event dispatch together through the renderer, then wait for an observable postcondition. The principle is broader than that one test.

The gap between finding and dispatching

Blazor's renderer owns component rendering and event processing. A component may update after a callback, a completed task, a parameter change, or a service notification. Those updates can replace elements and their associated handlers.

Test code, meanwhile, often reads like ordinary sequential C#:

var save = rendered.Find("[data-action='save']");

// An asynchronous state change may render here.

save.Click();

The selector can be perfectly correct when Find runs. That does not guarantee that the captured wrapper still represents the active element when Click runs.

The vulnerable window may be tiny. It can disappear while debugging, widen under load, or change when unrelated assertions are added. That makes arbitrary delays especially seductive. A delay changes the timing, but it does not define ownership or prove that the current render received the event.

Make the interaction one renderer-owned action

The safer shape is to keep acquisition and dispatch inside a single action scheduled through the renderer:

await rendered.InvokeAsync(() =>
{
    rendered.Find("[data-action='save']").Click();
});

Exact APIs differ between test libraries, but the important unit is the same:

Enter the renderer's dispatch context.
Find the element from the current render.
Raise its event before leaving that action.

Re-querying avoids carrying an element across a possible render boundary. Dispatching through the renderer aligns the test interaction with Blazor's event-processing model.

This is not a call to put the entire test inside one renderer callback. Keep the critical interaction small. Arrange inputs first, wait for any required precondition, then combine only the final lookup and event dispatch.

Wait for behaviour, not elapsed time

Dispatching an event is not the behaviour the user cares about. The useful contract is what becomes observable afterwards.

Depending on the component, that might be:

rendered confirmation or validation text;
a button becoming disabled or enabled;
navigation to an expected route;
one recorded call to a dependency;
a loading indicator appearing and then clearing; or
preserved input after a failed operation.

Use the test library's bounded wait-for-state or wait-for-assertion facility around that outcome:

await rendered.InvokeAsync(() =>
{
    rendered.Find("[data-action='save']").Click();
});

rendered.WaitForAssertion(() =>
{
    Assert.Contains("Saved", rendered.Markup);
});

A bounded wait says, "this state must eventually become true." An arbitrary sleep says only, "pause and hope the machine is fast enough." The first expresses a contract and can fail with useful evidence. The second tends to be both slow and fragile.

The trade-off: more ceremony, clearer intent

This pattern adds ceremony. Repeated interactions may need a small helper, and every test must identify a meaningful postcondition. That costs more than storing an element once and clicking it later.

There is also a risk of over-correction. Wrapping broad portions of a test in the renderer dispatcher can over-serialise the scenario and hide useful concurrency signals. Dispatcher usage should not bypass a real readiness requirement either. If the button should appear only after data loads, first wait for that visible precondition; then find and dispatch against the current tree.

The payoff is precision. The test says which boundary owns the interaction and which behaviour proves completion. Failures become less dependent on machine timing and more closely describe the user-facing contract.

What the evidence does - and does not - show

This lesson comes from reviewing a focused committed correction and the surrounding component flow. The change is consistent with a race between element acquisition, asynchronous rendering, and event dispatch.

I did not run the full suite, repeat the test under stress, or prove that every intermittent component failure has this cause. A passing correction also does not prove the production component is free of concurrency defects. The evidence supports a boundary worth protecting, not a universal diagnosis.

A practical review checklist is:

Can the component re-render between lookup and dispatch?
Are lookup and event dispatch one renderer-scheduled action?
Does the assertion describe an observable outcome?
Is waiting bounded and state-based rather than time-based?
Has repeated execution been used before making a stability claim?

The smallest reliable component tests respect the renderer without making timing itself part of the specification. Where could one of your tests be holding an element across a render boundary?

A Green Scheduler Is Not Proof

Ivan Rossouw — Mon, 03 Aug 2026 05:48:30 +0000

A background-job dashboard usually answers a narrow question: did the scheduled method return, fail, or retry?

That is useful, but it is not the same as knowing whether the intended work completed. The difference matters most when a job catches an internal failure deliberately. Perhaps one phase failed after another phase had already succeeded. Perhaps retrying the entire job would duplicate work or create a retry storm. Returning normally can be the responsible execution decision while still representing a failed business outcome.

If the dashboard only sees the return value, it can be technically accurate and operationally misleading.

The green light that hid a failure

In recent committed work I reviewed, recurring jobs were given their own durable outcome evidence. The change was motivated by a concrete failure shape: a terminal phase could be caught and logged, the method could return, and the scheduler could therefore record success.

The lesson is not that the scheduler lied. It reported what it owned: execution state. The job owned a different fact: whether its useful work reached an acceptable outcome.

Those are two separate contracts:

Execution contract: Was the job invoked? Did it return or throw? Was it retried?
Outcome contract: Did the intended work complete, fail, or deliberately skip? What safe evidence supports that answer?

Trying to squeeze both contracts into one green or red scheduler badge loses information.

Use two independent witnesses

The stronger design keeps scheduler state and job-owned evidence separate, then cross-checks them.

At the last responsible boundary, the job writes a small durable record containing:

a stable job key;
start and completion times;
a semantic outcome;
a short detail suitable for operations.

The monitor reads that record alongside the scheduler's latest state. Neither source gets trusted blindly. Agreement is useful evidence; disagreement is itself a result.

That gives the dashboard three honest answers:

Verified good — fresh successful job evidence has no fresh scheduler failure contradicting it.
Verified bad — evidence reports failure, is missing or stale, the job is not scheduled or running, or the two sources contradict.
Unverified — a monitoring or collection source is unavailable, so no trustworthy cross-check is possible.

The distinction matters. Missing evidence is a failed health check; an unavailable source is unverified. Neither may silently become success. Empty evidence is not positive evidence.

Put evidence around the whole outcome

A generalised C# shape looks like this:

var startedAt = clock.GetUtcNow();

try
{
    var result = await RunWorkAsync();

    if (!result.Acceptable)
    {
        await evidence.TryWriteFailureAsync(startedAt, result.SafeSummary);
        return;
    }

    await evidence.TryWriteSuccessAsync(startedAt, result.SafeSummary);
}
catch (Exception exception)
{
    await evidence.TryWriteFailureAsync(startedAt, SafeSummary(exception));
    throw;
}

This is deliberately broader than wrapping only thrown exceptions. A caught terminal failure still needs failed evidence even when returning is the correct retry policy. A deliberate no-op or skip also needs an explicit, explainable result rather than disappearing into silence.

Keep the detail short and safe. It should help distinguish outcomes without copying personal data, secrets, request payloads, or sensitive identifiers into an operations table.

Evidence writes should be best-effort

There is an uncomfortable trade-off here. If the evidence store is unavailable, should an otherwise healthy job fail and retry?

Usually, no. Observability should not become an outage amplifier.

The committed design I reviewed treated evidence writes as best-effort: log the write failure through an independent path, do not fail the useful work, and let the missing record surface as a failed health check during the next cross-check. Reads, however, must fail honestly. If the monitor cannot inspect its sources, it should say so rather than displaying green.

This creates a useful asymmetry:

the job remains resilient when telemetry storage fails;
the dashboard remains sceptical when proof is absent.

Freshness belongs to the contract

Missing evidence only has meaning relative to cadence. An hourly job and a weekly job cannot share the same stale threshold.

Derive an evidence window from the schedule, then add a small allowance for normal delay, restarts, and queueing. Store the timestamps in UTC. Make the threshold visible so operators know why a result is stale or failed.

Without that rule, a months-old success row can keep a dead job looking healthy forever.

Test the disagreements, not only the happy path

The focused tests in the reviewed change covered more than a successful write. That is the right instinct. At minimum, exercise:

successful completion with fresh evidence;
a deliberate skip with an explanatory detail;
a caught failure that does not escape the job;
an exception that is recorded and then rethrown;
scheduler success with no fresh evidence;
contradictory scheduler and job outcomes;
an unavailable scheduler monitor;
an evidence-store write failure that must not break useful work.

These cases prove that the dashboard can produce good, bad, and unverified answers. A diagnostic that can only turn green is not a diagnostic.

The engineering trade-off

This pattern adds a table, retention, instrumentation, dependency registration, an evaluator, and tests. It is more ceremony than checking the scheduler dashboard.

In return, it separates process health from work outcome, makes missing telemetry visible, and gives incident investigation a falsifiable trail. For high-value recurring work, that is usually a worthwhile exchange.

Start with one important job. Define what success actually means, record it at the boundary, cross-check it against the scheduler, and refuse to colour unknown evidence green.

Which background job in your system would look successful after a caught failure today?

One New State Means a Projection Audit

Ivan Rossouw — Sun, 02 Aug 2026 10:08:44 +0000

The migration was three columns. The behaviour change touched eleven files and introduced sixteen focused integration tests.

That ratio is a useful engineering signal.

A recent committed change added a soft cancellation state to a small operational workflow. Storing the state was straightforward. The real work was deciding what that state meant to every queue, count, aggregate, snapshot, export, transition, and recovery path that already interpreted the record.

The broader lesson is simple: a workflow state is not merely data. It is a contract across every projection and adjacent transition.

A state changes meaning, not only storage

Imagine an operational record that can be active, completed, or cancelled. Adding CancelledAt answers one narrow question: how is cancellation represented?

It does not answer the questions users and downstream systems actually ask:

Should cancelled work remain in the active queue?
Should it count as outstanding work?
Does it contribute to financial or operational totals?
Should history retain it or hide it?
What should an immutable end-of-period snapshot record?
Should a detailed export preserve the row while a summary export excludes it?
Can the state be restored?
What happens if a success event arrives after cancellation?

Each answer changes a read model or a transition. Leaving one answer implicit is how a locally correct filter becomes a system-wide contradiction.

Build a projection matrix before changing code

A small state-impact matrix makes those decisions reviewable:

Consumer	Cancelled record	Reason
Active work queue	Exclude	Nobody should act on it
Follow-up count	Exclude	It is no longer outstanding
Review history	Relocate	Preserve an auditable explanation
Live totals	Exclude	Do not treat it as completed activity
Closed snapshot	Aggregate separately	Preserve historical reconciliation
Detailed export	Include and annotate	Keep the event visible
Summary export	Exclude	Do not inflate completed quantities

The exact answers will differ by domain. The useful pattern is the set of verbs: include, exclude, relocate, annotate, or aggregate separately.

Even “no change” should be an explicit decision. A projection may already exclude the new state because another invariant makes the two conditions mutually exclusive. That is still worth recording. Otherwise a future change can break the hidden relationship without touching the projection.

Transitions belong in the same review

Read models are only half the contract. The state machine also needs rules around entry, exit, and competing events.

For a soft state, useful questions include:

Which states may enter cancellation?
Is repeating the command harmless?
Can an operator restore the record?
Which later events must clear or supersede cancellation?
What audit information survives every transition?

The reviewed work made cancellation idempotent, provided a restore path, rejected one invalid adjacent state, and declared that a late success event should take precedence. Those behaviours were backed by focused tests.

There is an important limit, though. A sequential test—cancel, then process success—proves ordering in that sequence. It does not prove safety when two handlers read and write concurrently. If the race is plausible, enforce the precedence with optimistic concurrency, a conditional update, or another database-level invariant. A comment and a unit test cannot make overlapping writes atomic.

The trade-off: ceremony versus drift

A state matrix, explicit transition rules, and cross-projection tests cost more than adding a Boolean and scattering a few filters. They also create more places that must evolve when the workflow changes again.

That cost is real. Keep the matrix small, centralise shared predicates where the semantics truly match, and avoid inventing a heavyweight state-machine framework for a tiny workflow.

The return is operational consistency. Without the ceremony, an active queue can exclude a record while its badge still counts it. A live total can exclude it while a frozen snapshot includes it. A detailed export can preserve it while a summary quietly treats it as completed. Every query may compile and still tell a different story.

Test crossings, not implementation details

The strongest tests exercise the boundaries between a transition and its consumers:

cancelling removes the record from active and follow-up views;
restoring returns it to the correct view;
repeated cancellation is harmless;
live counts match their corresponding lists;
live totals and historical snapshots apply the same meaning;
detailed and summary exports make their different policies visible;
a later event follows the declared precedence rule.

These tests are more valuable than asserting that a property became non-null. They protect the semantics users rely on.

Integration coverage still has limits. Tests against a lightweight database can validate real query shapes without proving the production migration, provider-specific behaviour, complete UI wiring, or true concurrency. Name those limits so a green suite is evidence, not theatre.

A practical review sequence

When adding a workflow state:

Draw the allowed transitions.
Inventory queues, counters, aggregates, snapshots, exports, notifications, and recovery jobs.
Mark each consumer include, exclude, relocate, annotate, or separate.
Define idempotency and race precedence.
Test each transition-to-projection crossing.
Add database protection where concurrency matters.

The write is usually the smallest part of a state change. Audit the reads, because that is where the system explains what the state means.

Which projection in your system would be easiest to overlook?

The Date Was Visible. The Model Was Null.

Ivan Rossouw — Sat, 01 Aug 2026 06:53:43 +0000

The Date Was Visible. The Model Was Null.

The form showed a selected date. Save said the date was required.

That sounds like a validation bug, but the validator was reporting the truth: the nullable .NET property was still null. The browser and the application had quietly diverged.

A recent committed fix made the underlying lesson unusually clear. A native HTML date input and a component converter were both doing reasonable things, but they did not share the same formatting contract. The control displayed state that the model had never accepted.

The lesson is broader than one component: visible UI state is not proof of bound application state.

One field can have three representations

A date field often crosses three different representations:

The human-facing value rendered by the browser.
The wire value exchanged by the native input.
The typed value stored in the .NET model.

For <input type="date">, the browser may display a familiar local format, but its value contract is an ISO-shaped calendar date such as 2026-08-01. The display can vary; the wire shape does not.

A surrounding Blazor component may have a different default. Its converter can format and parse DateTime? using the current culture's short-date pattern. Depending on culture, that pattern may use slashes, a different field order, or another separator.

Both behaviours are defensible in isolation. Combining them without an explicit adapter creates an accidental protocol.

The failure works in both directions

Consider the browser-to-model direction first.

The user selects a date. The native control emits an ISO value. A culture-aware converter expects the current short-date format instead. Conversion fails, so the nullable property is not updated. The browser can still display the selection it owns, making the next validation message look absurd.

Now reverse the flow.

An edit form loads an existing date from the model. The converter produces a culture-formatted string. The native date input accepts only its ISO value shape, rejects the text, and renders an empty control. Saving from that state can turn a display problem into lost data if the application treats the empty field as an intentional clear.

This is why testing only the validator, mapper, or service misses the defect. Those layers never exercise the disagreement between the browser contract and the component converter.

Give the boundary one owner

The reviewed fix chose a date-picker component that owns both its picker UI and its typed binding contract. That was also the established convention in the surrounding application, which reduced novelty and made the correction smaller.

That is one valid answer, not the only one. If a native date input is important, make the bridge explicit. A custom InputBase<DateOnly?>, an explicit get/set binding adapter, or a converter that deliberately uses the native ISO shape can all work.

The important design question is ownership:

Who formats model state for the control?
Who parses the control value back into the model?
Is the same contract used in both directions?
Where does a conversion failure become visible?

For date-only business concepts, DateOnly can also express intent more accurately than a midnight DateTime. It does not remove the wire-format problem, but it prevents time zones and time-of-day semantics from entering a calendar-only workflow unnecessarily.

Test the binding, not just the strings

A useful regression suite exercises the complete field boundary under representative cultures.

Start with these cases:

A user selection updates the typed model property.
An existing model value renders back into the control.
Clearing an optional date produces null.
A required date cannot look accepted while the model remains empty.
Re-rendering preserves a valid value.

Run both directions under several cultures, including one whose short-date format differs from the native ISO shape. A converter unit test is helpful, but a rendered component test is stronger because it includes binding events and component state. A small browser test is stronger again for behaviour owned by the native control.

The invariant is simple:

displayed date = wire date = model date

The strings do not need to look identical to a human. They do need a deliberate, reversible mapping.

The trade-off is worth naming

Native controls are lightweight, familiar, accessible, and supported by the browser. A component-owned picker adds JavaScript, styling, dependency weight, and another UI abstraction.

The answer is not to avoid native inputs. It is to price the conversion boundary honestly. If the surrounding component cannot speak the native control's value protocol reliably, the apparent simplicity is borrowed from future debugging time.

Similarly, a culture matrix and rendered component tests cost more than a single unit test. Keep them focused on the boundary rather than duplicating every form scenario. A handful of bidirectional contract tests usually provides more confidence than many service tests that never touch the UI protocol.

A practical review checklist

When reviewing a typed form control, ask:

What does the browser display?
What exact value does the control exchange?
What type and null semantics does the model require?
Which component owns conversion in each direction?
Which cultures are exercised?
Can failed conversion leave convincing stale UI behind?

Dates make this boundary easy to see, but the same pattern appears with decimal separators, percentages, currencies, enums, and time zones.

The screen is evidence of what the browser rendered. The model is evidence of what the application accepted. Good binding code—and good tests—prove that the two remain connected.

Where in your UI could a value look valid without ever reaching the model?

A Hidden Button Is Not an Authorisation Boundary

Ivan Rossouw — Fri, 31 Jul 2026 14:16:36 +0000

The most convincing authorisation gap can be a page that looks perfectly locked down.

An action disappears for callers who do not have the required permission. The screen feels safe, the happy path works, and a manual review confirms that the button is hidden. Yet the API behind that button may still accept any authenticated request.

That is the central lesson: UI visibility is a usability rule. Server-side authorisation is the security boundary.

Authentication answers only the first question

In ASP.NET Core, a controller-level Authorize attribute is useful. It establishes that a request must come from an authenticated principal. It does not, by itself, answer whether that principal may perform every operation exposed by the controller.

Those are different questions:

Authentication: who is calling?
Authorisation: may this caller perform this operation on this subject and scope?

The distinction becomes important when an API mixes operations with different risk profiles. Consider a generalised controller that supports:

reading my own record;
reading one record I am permitted to see;
listing an entire collection;
changing a relationship;
exporting a richer dataset.

All five actions may require authentication. They do not necessarily share one authorisation rule.

Why one controller-wide policy can be wrong

A recent committed hardening change illustrated this mixed-purpose shape. Some actions were legitimate self-service. Other actions worked across a collection or produced a higher-sensitivity export.

Moving one strict policy onto the entire controller would have been simple, but it would also have denied the self-service operations. Keeping only the baseline authentication rule would preserve those journeys, but leave the broader operations under-specified.

The design therefore needed operation-level decisions.

Here is a deliberately generic sketch:

[Authorize]
public sealed class RecordsController : ControllerBase
{
    [HttpGet("mine")]
    public Task<IActionResult> Mine() =>
        ReadForCurrentCaller();

    [HttpGet("all")]
    public async Task<IActionResult> All()
    {
        if (!access.CanReadCollection(User))
            return Forbid();

        return Ok(await records.All());
    }

    [HttpGet("export")]
    [Authorize(Policy = "Records.Export")]
    public Task<IActionResult> Export() =>
        ExportAuthorisedDataset();
}

The controller-level attribute still performs useful baseline authentication. The broader read uses a domain guard because legitimate access may be represented through more than one role or capability. The higher-sensitivity operation uses a focused policy that can evolve independently.

This is not a universal template. It is a reminder to make each operation’s rule explicit.

Match the guard to subject, scope, and sensitivity

An authorisation review becomes easier when each action is classified along three dimensions.

1. Subject

Is the caller acting on their own resource, a resource related to them, or somebody else’s resource?

Self-service often needs object-level checks rather than a broad administrative permission.

2. Scope

Does the action return one authorised object, a page of objects, or an entire collection?

A caller who may read one related record does not automatically gain collection-wide visibility. Cardinality changes the boundary.

3. Sensitivity

Does the operation expose a routine projection, change state, or create a richer export?

Two actions over the same entity may deserve different policies when one combines more fields, covers a wider scope, or produces a portable artefact.

This classification is more reliable than deriving API rules from whichever controls happen to be visible on a page.

Test denial and preserved access

The obvious regression test asserts that an authenticated caller without the required entitlement receives a forbidden result. That is necessary, but incomplete.

The same change should also prove that each legitimate access path still succeeds. In a mature system, entitlement may come from a role, a capability claim, object ownership, or a domain relationship. A “secure” change that silently blocks valid work is still a regression.

For a mixed-purpose controller, useful tests include:

the sensitive action carries the intended policy;
an authenticated but unentitled caller is denied;
legitimate role-based access still works;
legitimate capability-based access still works;
baseline authentication has not been removed;
no action has accidentally acquired anonymous access.

Metadata and unit tests are fast and valuable, but they do not exercise the complete middleware pipeline. Add at least one integration test through a real test host for the highest-risk route. That verifies policy registration, authentication scheme selection, and middleware order together.

The trade-off

Action-level authorisation adds attributes, guards, tests, and review surface. It can also become inconsistent if developers must remember the rule for every new action.

A single controller-wide policy is easier to understand, but only when every action truly shares the same access semantics. Splitting self-service and privileged operations into separate controllers can make the boundary clearer, although it may fragment routing and add migration work.

The right choice is the one that makes the security model visible. For an existing mixed-purpose controller, explicit action rules plus a small classification test can be a pragmatic step. For new APIs, grouping operations by authorisation semantics is often cleaner.

A practical takeaway

During the next endpoint review, ignore the page for a moment. Inventory the API actions directly and label each one:

self;
single authorised resource;
bulk collection;
mutation;
export.

Then ask what the server proves before executing each action. Finally, test one caller who must fail and every caller class that must still succeed.

Hide or disable controls to create a clear experience. Put the actual decision where the data or state change leaves the server.

Shared UI Means Shared Contracts, Not Shared Hosts

Ivan Rossouw — Thu, 30 Jul 2026 06:04:54 +0000

A component can compile in a shared assembly and still be impossible to construct in one of the applications that renders it.

That is easy to miss when browser and .NET MAUI hosts reuse the same Blazor pages. The feature appears to exist once, but every host still owns a dependency-injection container, startup path, and lifetime model.

A recent committed fix made this concrete. A shared page gained a required workflow dependency. Native hosts registered it in their common bootstrap path. A browser host rendered the same page through another composition root, where the dependency was unknown. The page failed before it could render.

The lasting lesson was not “remember one more registration.” It was that shared UI creates a contract for every host capable of rendering it.

Sharing an assembly does not share a container

Compile-time reuse asks whether multiple projects can reference a component. Runtime composition asks whether each host can construct it and satisfy the required behaviour.

A native host may call a wrapper bootstrap, while a browser host calls a web-oriented startup path. Both load the same Razor component without building the same service graph.

This creates a useful review rule:

A required injection on a shared component is a required contract on every composition root that can render it.

The host inventory matters. “All native apps use this bootstrap” is not enough if a browser, desktop, test, or preview host renders the page by another route.

Do not repair a missing host capability with optionality

When one host cannot provide a dependency, making it nullable can feel pragmatic. That is reasonable for an optional enhancement such as haptic feedback. It is dangerous when the dependency enforces a workflow invariant.

In the reviewed change, the workflow had to know whether the runtime context remained the same while an operation was in flight. Native applications could change that context at runtime. The browser host could not; its context was fixed for the lifetime of the application.

Optionality would have turned “this host represents stability differently” into “this host may skip the safety check.” Those are not equivalent.

The better question was: what is the smallest capability the workflow genuinely needs?

It needed only three facts:

a revision that identifies the current context;
whether the context is ready for work;
a signal that the context has changed.

It did not need the native host’s full navigation, storage, or UI service. Once the smaller contract was explicit, both hosts could tell the truth.

Fixed and live adapters can satisfy one invariant

The browser implementation could be fixed:

its revision never changes;
it is ready once the application starts;
its change signal never fires.

The native implementation could be live:

its revision comes from the runtime context;
readiness reflects whether a selection exists;
its signal follows genuine context changes.

They behave differently while preserving the same promise: work that begins in one context must not silently commit after that context changes. The abstraction names the smallest invariant every platform can honour instead of erasing platform differences.

Register the contract where the hosts actually enter

The original registration lived in a bootstrap shared by the native applications. It looked central because several hosts called it, but it was not central to every host rendering the page.

The fix moved the shared workflow contract into the two actual composition paths:

the browser path registered the fixed adapter;
the native path registered the live adapter;
both registered the required shared workflow;
the native-only wrapper stopped being the accidental authority.

The duplicated registrations document a real split: same workflow, different host truth. Common registration still suits identical services; host-specific adapters should stay visible where the host chooses them.

Test behaviour and composition

Registration tests are useful because this failure happens before component behaviour can begin.

A focused matrix can cover:

the browser composition root contains the shared workflow and fixed adapter;
the native composition root contains the shared workflow and live adapter;
the old platform-only bootstrap is not a hidden third authority;
the workflow succeeds when a host has a genuinely fixed context;
the workflow rejects or repairs a completion when a live context changes mid-operation.

Descriptor checks catch missing registrations quickly. Behaviour tests prove the adapters preserve the invariant. Neither activates the complete production host. For high-value pages, add a smoke test that builds each host’s real provider and constructs the page boundary; this can expose lifetime or replacement mistakes that descriptor checks miss.

The trade-off

The narrow-contract approach costs an interface, two adapters, explicit registrations, and a wider test matrix.

The alternatives are cheaper only locally:

a broad native service leaks platform concerns into shared workflow code;
an optional dependency can silently disable a safety invariant;
one oversized bootstrap hides which host owns which behaviour;
ad hoc checks drift without a named contract.

I prefer small, intentional duplication at composition boundaries over implicit behavioural differences inside the workflow.

A practical review checklist

When a shared Blazor component gains a required dependency, ask:

Which browser, native, desktop, test, and preview hosts can render it?
Through which composition root does each host enter?
Is the dependency a capability the workflow needs, or a large platform service it happened to receive?
Can every host provide a truthful, non-optional implementation?
Are host differences visible in adapters rather than null branches?
Do tests exercise registration and behaviour for every root?
Would a full-provider smoke test catch lifetime or replacement errors?

Shared UI is not evidence of shared runtime topology. Treat every required dependency as a cross-host design decision, and the composition roots become part of the component’s real API.

Which shared page in your system is quietly assuming it has only one host?