Bit.Butil 10.6.0-pre-02

bit Butil

The browser platform, in C#. Butil wraps the Web APIs a Blazor app actually needs - the DOM, storage, media, sensors, crypto, workers - as injectable, strongly-typed, XML-documented services, so you can stop writing IJSRuntime.InvokeVoidAsync("someGlobal.someFunction", ...) and start writing C#.

Works on Blazor WebAssembly, Blazor Server, Blazor Hybrid and under prerendering, on .NET 8, 9 and 10.

Getting started

Install the package:

dotnet add package Bit.Butil

Add its script tag to your host page, before the Blazor script so window.BitButil exists by the time the app boots:

<script src="_content/Bit.Butil/bit-butil.js"></script>
<script src="_framework/blazor.web.js"></script>

Register the services:

using Bit.Butil;

builder.Services.AddBitButilServices();

Then inject whatever you need:

@inject Bit.Butil.Window window
@inject Bit.Butil.LocalStorage localStorage
@inject Bit.Butil.Clipboard clipboard

@code {
    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender is false) return;

        await localStorage.SetItem("last-visit", DateTime.UtcNow.ToString("O"));
        await clipboard.WriteText("copied from C#");
        await window.AddEventListener(ButilEvents.KeyDown, args => { /* ... */ });
    }
}

What's in the box

Every wrapper below is an injectable service in the Bit.Butil namespace. They are registered as scoped, which matches Blazor's one-circuit-or-one-WASM-app-per-user model.

Window & browsing

Screen & diagnostics

DOM & interaction

Storage

Files & data

Network & workers

Device & hardware

Identity & permissions

Media & speech

The patterns worth knowing

Prerendering is safe by default

During static SSR / prerender there is no JS runtime. Rather than throwing, reads return a safe default - "" for strings, [] for arrays, default(T) for everything else - and void calls are no-ops. That means a read in OnInitializedAsync won't crash your prerender pass.

The trade-off: a false from IsSupported() during prerender is indistinguishable from a genuine false. If you branch on a result, do the read in OnAfterRenderAsync instead:

protected override async Task OnAfterRenderAsync(bool firstRender)
{
    if (firstRender is false) return;

    if (await wakeLock.IsSupported())
    {
        await wakeLock.Request();
    }
}

Subscriptions are disposable

Anything that attaches a listener returns a ButilSubscription. Dispose it to detach:

private ButilSubscription? _subscription;

_subscription = await resizeObserver.Observe(_element, entries => { /* ... */ });

// later - idempotent, and safe during teardown:
await _subscription.DisposeAsync();

If you forget, the owning service detaches everything it registered when its scope is torn down. That's a safety net, not a plan.

Handles own hardware

MediaStreamHandle, MediaRecordingHandle, WakeLock's persistent handle and the File System handles all represent something the browser is holding open. Dispose them:

await using var stream = await mediaDevices.GetUserMedia(audio: false, video: true);
await stream!.AttachTo(_videoElement);
// the camera light goes out when the handle is disposed

Gestures and secure contexts

Many APIs only work from inside a user-gesture handler (a click), or only over HTTPS. Butil doesn't hide that - each method's XML docs say which preconditions apply, and calls that the browser refuses come back as false/null rather than as exceptions where dismissal is a normal outcome.

Optional fast invoke

On Blazor WebAssembly, the handful of APIs backed by genuinely synchronous JS functions - LocalStorage, SessionStorage, Cookie, Console, Location - can skip the async marshalling:

BitButil.UseFastInvoke();

Everything wrapping a Promise-returning API keeps running asynchronously regardless, so this can't break those calls. On Blazor Server it's a no-op.

Trimming and AOT

The package is marked IsTrimmable. Types crossing the interop boundary carry [DynamicDependency] annotations, so trimming a published WASM app keeps what the serializer needs. The public FastInvoke* extensions are annotated [RequiresUnreferencedCode] so a trimming consumer gets the warning at their own call site.

Samples and docs

The Bit.Butil.Demo project in this repository is a full documentation site: one page per API, with runnable samples, an API reference table, and a browser-support matrix. Run it to try any of the above in your own browser.

Every public member carries XML documentation with a link to the corresponding MDN page, so IntelliSense is the reference of record.