Blazor.BrowserAPI

A Blazor library that provides easy access to browser APIs without the need to use any JavaScript. Since JavaScript functionality for Blazor is primarly used for accessing BrowserAPIs, for most applications there will be no need to write any additional JavaScript.
It supports asynchronous communication as well as synchronous (JSRuntime and JSInProcessRuntime).

You can find the test page at blazor-browserapi.blackwhiteyoshi.com.

Available Browser APIs

• Clipboard
• Console
• CookieStorage
• Document
• Download
• FileSystem
• GamepadAPI
• Geolocation
• History
• HTMLDialogElement
• HTMLElement
• HTMLMediaElement (audio/video)
• LocalStorage
• MediaDevices (microphone/camera)
• Navigator
• NetworkInformation
• Permissions
• SensorAPI
• ServiceWorker
• SessionStorage
• Window
• WindowManagement (screen)

Other APIs

• ModuleManager

Get Started

1. Add PackageReference to your .csproj file

<ItemGroup>
  <PackageReference Include="Blazor.BrowserAPI" Version="{latest version}" />
</ItemGroup>

2. Register BrowserAPI in your dependency container

using BrowserAPI;

services.AddBrowserAPI();

JS module

The necessary JS file is fetched automatically the first time. However, if you use a functionality of BrowserAPI synchronous (JSInProcessRuntime) before the download has finished, you get an error like:

JS-module is not loaded yet. To make sure the module is downloaded, you can await IModuleLoader.ModuleDownload.

To ensure the download has finished, you can use the IModuleManager interface.

Browser Support

Not all APIs are supported in all Browsers. This Library does no extra checks if an API is supported and calling an unsupported API may throw an exception. It is your responsibility to check Browser support and handle the results appropriately.

Note:
Blazor-server and Blazor-webassembly act different when mapping JS null/undefined to C# value types: While Blazor-webassembly just maps to default, Blazor-server throws an exception instead.

Namespace BrowserAPI.Implementation

There exists 2 namespaces in this Library: BrowserAPI and BrowserAPI.Implementation. Members inside the BrowserAPI.Implementation namespace should not be used directly and there is no guarantee that the members of a class will be stable. However, the class names itself will be stable, so using them for service provider registration is fine.

How to contribute

Adding a member to an existing BrowserAPI normally includes 5 steps:

1. Adding a function to the corresponding .ts file (in case of a event -> 3 functions)
2. Adding methods to the corresponding .cs and Inprocess.cs files (in case of a event -> Base.cs file)
3. Adding a button to the test page
4. Adding a unit test
5. Adding an entry to .md file

When creating a new BrowserAPI, a new folder at Blazor.BrowserAPI/BrowserAPIs/ should be created and the following files contain a list of all BrowserAPIs and the new BrowserAPI must be added accordingly:

• README.md
• PACKAGE.md
• Main.ts
• AddBrowserAPIExtansion.cs
• IBrowserAPIModule_CircleDI.cs
• IBrowserAPIModule_Jab.cs
• App.razor

Preview

This package is in preview and breaking changes may occur (breaking changes are always mentioned in the Release Notes).
There are more interfaces coming.

Release Notes

• 0.1
  • first version, includes 10 BrowserAPIs: Clipboard, Console, CookieStorage, Dialog, Download, HTMLElement, Language, LocalStorage, ServiceWorker, SessionStorage
• 0.1.1
  • changed SetCookie parameters: expires to seconds and samesite to string
• 0.1.2
  • changed internal classes to public and moved them to namespace BrowserAPI.Implementation
• 0.2.0
  • added IBrowserAPIModule for CircleDI and Jab
• 0.3.0
  • added Geolocation (11 BrowserAPIs)
• 0.4.0
  • breaking change: removed HTMLElementFactory and DialogFactory and added ElementFactory/ElementFactoryInProcess instead
• 0.5.0
  • added HTMLMediaElement (12 BrowserAPIs)
• 0.6.0
  • added MediaDevices (13 BrowserAPIs)
• 0.7.0
  • added SensorAPI (14 BrowserAPIs)
  • changed events to use sync interop if possible
• 0.7.1
  • added .NET 9 and removed obsolete versions .NET 6 and .NET 7
• 0.7.2
  • small breaking change: Geolocation.GetCurrentPosition() -> first parameter successCallback only takes 1 parameter GeolocationCoordinates now and the previous second parameter timestamp is inlcuded in the first parameter
  • added method Geolocation.GetCurrentPositionAsync()
• 0.8.0
  • added FileSystem (15 BrowserAPIs)
• 0.9.0
  • added History (16 BrowserAPIs)
  • small breaking change: OnError in MediaRecorder, Sensor and ServiceWorker has as parameter a JsonElement instead of a string. To get the previous value, just use ToString() on it.
• 0.10.0
  • added GamepadAPI (17 BrowserAPIs)
  • added navigator.languages to the Language API
• 0.11.0
  • added NetworkInformation (18 BrowserAPIs)
• 0.12.0
  • added WindowManagement (19 BrowserAPIs)
  • small breaking changes:
    • changed IGamepadAPI.GetGamepads() from returning IGamepad[] to IGamepad?[], so it aligns with the JS array.
    • changed IServiceWorkerContainer.Register() from returning ValueTask<bool> to ValueTask, an exception is thrown when service workers are not supported.
    • changed IServiceWorkerContainer.DelayUntilReady() to IServiceWorkerContainer.Ready, so it aligns with the JS property.
    • changed IServiceWorkerContainer.OnMessage from Action<string> to Action<JsonElement>
• 0.13.0
  • added Permissions (20 BrowserAPIs)
• 0.14.0
  • added Document (21 BrowserAPIs)
  • added much more members to HTMLElement
  • added video members to HTMLMediaElement
  • small breaking change: renamed IDialog to IHTMLDialogElement
  • small breaking changes: renamed some events to capital letters so it fits more the C# convention naming
• 0.15.0
  • added Window and Navigator, marked BrowserAPI Language as obsolete (22 BrowserAPIs)
  • marked WindowManagement.Open() as obsolete
  • added more events to History and SensorAPI
  • small breaking change: Geolocation.WatchPosition()/Geolocation.ClearWatch() returns/takes a handle that contains the id instead of just the id.
• 0.15.1
  • added TargetFramework net10.0
  • added more TrySyncExtension methods: InvokeConstructor, GetValue, SetValue, TimeSpan overloads