WebExtensions.Net
A package for consuming WebExtensions API in a browser extension.
These API classes are generated based on the Mozilla documentation for WebExtensions API.
How to use this package
Important for v0.*.*:
This package is still in pre-release stage so the versioning does not comply with semantic versioning. Feature and bug fix increments the patch version and breaking change increments the minor version. So be sure to check the release note before upgrading between minor version.
This package can be consumed in two methods.
With Blazor (Recommended)
Create a browser extension using Blazor. Refer to the package Blazor.BrowserExtension to get started.
Without Blazor
Create a standard browser extension using JavaScript and load the WebAssembly manually. The .Net source code can be compiled into wasm using Mono.
- Install
WebExtensions.Net(if you intend to use the API without dependency injection) orWebExtensions.Net.Extensions.DependencyInjectionfrom Nuget. - Import the
JsBind.Netscripts with<script src="_content/JsBind.Net/JsBindNet.js"></script>. If your project does not support Razor Class Library contents, add the property<LinkJsBindAssets>true</LinkJsBindAssets>to your project. - Import the WebExtensions polyfill by Mozilla for cross browser compatibility. This polyfill helps to convert the callback based Chrome extensions API to a Promise based API for asynchronous functions.
- Consume the WebExtensions API by creating an instance of
WebExtensionsApias shown below.
using JsBind.Net;
using JsBind.Net.Configurations;
using WebExtensions.Net;
...
var options = new JsBindOptionsConfigurator()
.UseInProcessJsRuntime()
.Options;
// iJsRuntime is an instance of MonoWebAssemblyJSRuntime
var jsRuntimeAdapter = new JsRuntimeAdapter(iJsRuntime, options);
var webExtensionsApi = new WebExtensionsApi(jsRuntimeAdapter);
// Use the WebExtensions API
var manifest = await webExtensionsApi.Runtime.GetManifest();Debugging and testing
For the purpose of debugging and testing outside of the browser extension environment, there is a MockJsRuntimeAdapter class under the WebExtensions.Net.Mock namespace.
Initialize an instance of the mock API with:
using WebExtensions.Net;
using WebExtensions.Net.Mock;
...
var jsRuntimeAdapter = new MockJsRuntimeAdapter();
var webExtensionsApi = new WebExtensionsApi(jsRuntimeAdapter);To configure the behaviour of the mock API, you may use any combination of the following:
MockResolvers.Configure(configure =>
{
// configure a method without any argument
configure.Api.Method<string>(api => api.Runtime.GetId).Returns(() => "MyExtensionId");
// or
configure.Api.Method<string>(api => api.Runtime.GetId).ReturnsForAnyArgs("MyExtensionId");
// configure a method with one argument
configure.Api.Method<string, string>(api => api.Runtime.GetURL).Returns(path => builder.HostEnvironment.BaseAddress + path);
// configure a method that returns the same object regardless of the arguments
configure.Api.Method<string, CreateNotificationOptions, string>(api => api.Notifications.Create).ReturnsForAnyArgs("NotificationId");
// configure an action to be invoked when an API is called
configure.Api.Method<int?>(api => api.Tabs.GoForward).Invokes(tabId => { /* Do something with tabId */ });
// configure a method on an object reference
using var emptyJson = JsonDocument.Parse("{}");
configure.ObjectReference(DefaultMockObjects.LocalStorage).Method<StorageAreaGetKeys, JsonElement>(storage => storage.Get).ReturnsForAnyArgs(emptyJson.RootElement.Clone());
// configure an action to be invoked when a method on an object reference is called
configure.ObjectReference(DefaultMockObjects.LocalStorage).Method(storage => storage.Clear).Invokes(() => { /* Do something */ });
// configure a generic delegate to handle all the API calls
bool apiHandler(string targetPath, object[] arguments, out object result)
{
if (targetPath == "runtime.id")
{
result = "MyExtensionId";
return true;
}
result = null;
return false;
}
configure.ApiHandler(apiHandler);
// configure a generic delegate to handle all the invocations to object references
bool objectReferenceHandler(object objectReference, string targetPath, object[] arguments, out object result)
{
if (objectReference == DefaultMockObjects.LocalStorage && targetPath == "get")
{
using var emptyJson = JsonDocument.Parse("{}");
result = emptyJson.RootElement.Clone();
return true;
}
result = null;
return false;
}
configure.ObjectReferenceHandler(objectReferenceHandler);
});Note: The sequence of mock registration matters.
Overall the more specific method Returns and ReturnsForAnyArgs is prioritized over the generic delegate ApiHandler and ObjectReferenceHandler.
If there exists registration that handles the same API or object reference call, the last registered handler will be used.
For example:
MockResolvers.Configure(configure =>
{
// when api.Runtime.GetId is called it will return "MyExtensionId2"
configure.Api.Method<string>(api => api.Runtime.GetId).Returns(() => "MyExtensionId1");
configure.Api.Method<string>(api => api.Runtime.GetId).Returns(() => "MyExtensionId2");
});MockResolvers.Configure(configure =>
{
// when api.Runtime.GetId is called it will return "MyExtensionId1", even though the generic API handler is registered last, the more specific method registration is prioritized.
configure.Api.Method<string>(api => api.Runtime.GetId).Returns(() => "MyExtensionId1");
bool apiHandler(string targetPath, object[] arguments, out object result)
{
if (targetPath == "runtime.id")
{
result = "MyExtensionId2";
return true;
}
result = null;
return false;
}
configure.ApiHandler(apiHandler);
});