Bit.Butil 10.6.0-pre-03

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 (or skip the tag entirely with lazy scripts - see Shipping only the JavaScript you use):

<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.

AddBitButilServices is trimming-aware: it discovers the services by reflecting over the Bit.Butil assembly for classes marked [ButilService] rather than naming them in AddScoped<T>() calls. A hard-coded call is a static reference that roots the class, so listing all of them would force every published app to carry all of them; reflecting instead lets the trimmer remove the classes your code never injects, and what it removed is simply not there to register. Injecting a Butil class from code the trimmer removed - or resolving one purely by reflection - therefore fails at runtime rather than at build time. Untrimmed apps (Blazor Server, and the prerendering host of a WebAssembly app) keep registering everything.

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.

Shipping only the JavaScript you use

bit-butil.js covers every API in the package. The C# side of an unused API is trimmed away from a published app (see AddBitButilServices above); the JavaScript side can be tree-shaken too. There are two ways of tree-shaking it, both set in the app's csproj, and both working from the same per-module build of the scripts (one Scripts/*.ts file is one module, BitButil.clipboard for Clipboard and so on).

Publish-time bundle trimming - the default, nothing to add. Keep the script tag. When the app is published trimmed - a Blazor WebAssembly publish is - the package's build logic reads the trimmed Bit.Butil.dll, finds which BitButil.<module>.* identifiers survived (every interop call goes through such a literal, so the trimmed assembly is the exact list of modules the app can still reach) and replaces bit-butil.js with a bundle assembled from only those modules and their dependencies. Fingerprints, integrity hashes and compressed variants are computed from the new content. An app that injects Clipboard, LocalStorage and Window ships about 8 KB of JavaScript instead of the 110 KB bundle. It is on by default only in a Blazor WebAssembly project - a standalone app or PWA - because that is where the assembly being trimmed is the assembly calling the served JavaScript; a server that hosts a WebAssembly client keeps its own, full copy of the bundle (use lazy scripts there). The same property trims the other shape too: wherever the module files are published - a lazy-scripts app, or an app keeping both shapes - only the modules the trimmed assembly can still name are published, and the rest of the modules/ folder is dropped. Nothing can 404 over it: the identifier that would have imported a dropped module is gone from the assembly with it. <BitButilIncludeScriptModules>true</BitButilIncludeScriptModules> in the csproj publishes every module regardless, for an app that reaches them from outside its own interop calls. All of this happens in dotnet publish only: a build - and dotnet run and dotnet watch on top of it - keeps the full bundle and every module, so what you debug is never the trimmed JavaScript. Opt out with false, or opt in elsewhere with true:

<PropertyGroup>
  <BitButilTrimScripts>false</BitButilTrimScripts>
</PropertyGroup>

Lazy scripts. No script tag at all: the first call into an API import()s that API's module (_content/Bit.Butil/modules/clipboard.js for Clipboard), so only the JavaScript for the APIs the app actually calls is ever downloaded - in every hosting model, trimmed or not. Each module file is self-contained and safe to load more than once. Set the property in every project that uses Butil (a Blazor Web App's server and client both) and drop the script tag from the host page:

<PropertyGroup>
  <BitButilLazyScripts>true</BitButilLazyScripts>
</PropertyGroup>

The property also drops the bundle from the published output (and, in the default mode, the module files) and turns the mode on at runtime - through the Bit.Butil.LazyScripts runtime switch and, since runtime configuration does not reach a .NET 8 WebAssembly app, a one-line module initializer compiled into the project that calls BitButil.UseLazyScripts(). BitButilIncludeScriptBundle and BitButilIncludeScriptModules override which shape ends up in the published output when you want both. In a project that also trims (a WebAssembly publish does by default) the modules published are the ones the trimmed assembly can still import; naming BitButilIncludeScriptModules in the csproj publishes all of them.

Prefer to keep it in C#? The registration call takes the same switches:

builder.Services.AddBitButilServices(options =>
{
    options.LazyScripts = true;                  // or false to insist on the bundle
    options.ScriptModulesPath = "/cdn/butil/";   // optional, when the modules are served elsewhere
    options.FastInvoke = true;                   // optional, same as BitButil.UseFastInvoke()
});

That is equivalent to BitButil.UseLazyScripts() / BitButil.UseBundledScripts() (process-wide, last call wins) and needs no script tag either. What it cannot do is change the published output - which is why BitButilLazyScripts is the better switch wherever the csproj is an option. The default (bundle mode) publishes the bundle and drops the module files, so the C# switch on its own leaves the import()s with nothing to fetch; keep them with

<PropertyGroup>
  <BitButilIncludeScriptModules>true</BitButilIncludeScriptModules>
</PropertyGroup>

and the bundle, still published, is simply never loaded (harmless - but a PWA precaches it). Publish-time bundle trimming has no runtime counterpart at all, since it happens inside dotnet publish.

Trade-offs: lazy scripts cost one extra request the first time each module is used, and the modules' first call is necessarily asynchronous (every Butil API already is). The trimmed bundle is one request and needs no thought, but only in the project that publishes trimmed.

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.

That same server hosts an MCP server at /mcp, so an AI agent can work against Butil's real API instead of guessing at it. Point an MCP client at https://localhost:5253/mcp; every tool is also a plain HTTP GET under /api/mcp/... if you just want to look. It offers:

• Search across everything at once (SearchButil) - this guide, the docs pages, every public member, the browser-support matrix and the demo's sources - with the exact follow-up call on each hit. The name a task suggests is rarely the name the web platform chose, which is what this is for.
• The exact API (GetButilApiDetails), reflected out of the shipped assembly: every service, every signature, every default argument, with the XML documentation.
• What an API needs before it works (PlanButilFeature, for one API or the whole set a feature uses): the engines that implement it, whether it wants HTTPS, a permission prompt or a user gesture, what has to be disposed, and how it behaves under prerendering - the mistakes that compile and then do nothing.
• Setup per hosting model (GetButilSetupGuide), as the real files of a working project.
• The docs, this guide and the demo's source as text (GetButilDocsPage, GetButilGuideSection, GetButilSourceFile) - each of them returns the list of what it can hand out when called with no argument, and the docs index doubles as the browser-support matrix.
• Resources (butil://guide/..., butil://api/..., butil://docs/..., butil://support) and prompts for the four common jobs: adding Butil to an app, implementing a feature with it, replacing hand-written JS interop, and debugging a call that silently does nothing.

There are seven tools, and no more: a tool description is paid for in every request of every session, so a listing is not a tool of its own, a single-item lookup is not a tool when one that takes a set already resolves each member, and nothing restates the server's instructions, which the client has had in context since initialize. Start with SearchButil. See McpController.

The site's own /mcp-server page is a working client for it: it handshakes with this server on load, lists its tools, and lets you call one and read both halves of the exchange - the JSON-RPC request, the response, and the text a model would be handed. It is the fastest way to see what a tool actually returns before wiring an agent up to it.

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