IMobileBridge
Namespace: BlazorNative.Core
The .NET-side bridge contract between app code and the native host.
Resolve it from DI and call it; the host supplies the implementation
(NativeShellBridge on-device, DevHostBridge in a harness).
public interface IMobileBridge
Remarks:
API-additions policy (consume-only contract). This interface is a contract you call, not one you implement. Members are added to it as capabilities land — one small group per capability — and such an addition is declared non-breaking, because every supported consumer is a caller and a caller is unaffected by a wider interface.
The corollary is the part that binds: implementing this interface
outside BlazorNative is unsupported. A new member will break an external
implementer at compile time, in a minor version, with no major bump and no
deprecation window. If you need a stand-in for tests, use
DevHostBridge or the narrow BlazorNative.Device façades
(IGeolocation, INotifications, IBiometrics,
ISecureStorage, ICamera) — those are sized to be mocked; this is
not. The alternative policy — shipping virtual default implementations so
additions stay source-compatible for implementers — was considered and rejected:
it would put method bodies in a package whose entire purpose is to hold none.
See docs/plans/2026-07-21-phase-11.3-api-tiers.md (tier: STABLE).
Properties
PlatformInfo
Platform info as a raw JSON string (the WASM-era sync shape). Prefer IMobileBridge.GetPlatformInfoAsync(CancellationToken) for the typed form.
string PlatformInfo { get; }
Property Value
Methods
NavigateAsync(String, CancellationToken)
Navigates the host to route.
ValueTask NavigateAsync(string route, CancellationToken ct = null)
Parameters
route String
Returns
GetCurrentRouteAsync(CancellationToken)
Returns the host's current route.
ValueTask<string> GetCurrentRouteAsync(CancellationToken ct = null)
Parameters
Returns
ReadStorageAsync(String, CancellationToken)
Reads a plain (unencrypted) key/value entry — SharedPreferences on Android, UserDefaults on iOS. Null if the key is absent. For secrets use IMobileBridge.GetSecretAsync(String, CancellationToken).
ValueTask<string?> ReadStorageAsync(string key, CancellationToken ct = null)
Parameters
key String
Returns
WriteStorageAsync(String, String, CancellationToken)
Writes a plain (unencrypted) key/value entry.
ValueTask WriteStorageAsync(string key, string value, CancellationToken ct = null)
Parameters
key String
value String
Returns
DeleteStorageAsync(String, CancellationToken)
Deletes a plain key/value entry (a no-op if absent).
ValueTask DeleteStorageAsync(string key, CancellationToken ct = null)
Parameters
key String
Returns
FetchAsync(BridgeHttpRequest, CancellationToken)
Performs an HTTP request through the host, which owns TLS, proxying
and permissions. Prefer the HttpClient registered by
AddBlazorNativeHttp(), which routes through this.
ValueTask<BridgeHttpResponse> FetchAsync(BridgeHttpRequest request, CancellationToken ct = null)
Parameters
request BridgeHttpRequest
Returns
Remarks:
The response is delivered once, complete: the host buffers the whole body and completes the call with a single BridgeHttpResponse whose BridgeHttpResponse.Body is UTF-8 text. There is no incremental delivery path, so streaming protocols (SSE, chunked-read, long-poll) degrade to polling and binary bodies are unsupported.
ClipboardReadAsync(CancellationToken)
Reads the system clipboard's text (empty if none). A host that predates this slot raises NotSupportedException.
ValueTask<string> ClipboardReadAsync(CancellationToken ct = null)
Parameters
Returns
ClipboardWriteAsync(String, CancellationToken)
Writes text to the system clipboard.
ValueTask ClipboardWriteAsync(string text, CancellationToken ct = null)
Parameters
text String
Returns
ShareAsync(String, CancellationToken)
Presents the OS share sheet with text.
ValueTask ShareAsync(string text, CancellationToken ct = null)
Parameters
text String
Returns
GetCurrentPositionAsync(CancellationToken)
Requests-then-fetches the current position in one call: the whole permission dance runs host-side, and the terminal outcome is always a GeolocationResult — a denial is DATA, never an exception or a hang. The token abandons a never-completing call (e.g. the app killed during the prompt) as a cancel, never a leak.
ValueTask<GeolocationResult> GetCurrentPositionAsync(CancellationToken ct = null)
Parameters
Returns
CheckGeolocationPermissionAsync(CancellationToken)
Reads the current geolocation permission WITHOUT prompting — for a UI that wants to show state before offering to locate.
ValueTask<GeolocationStatus> CheckGeolocationPermissionAsync(CancellationToken ct = null)
Parameters
Returns
ScheduleNotificationAsync(NotificationSpec, CancellationToken)
Schedules a local notification to fire at NotificationSpec.When. The outcome is a NotificationStatus — a denial is DATA, never a throw.
ValueTask<NotificationStatus> ScheduleNotificationAsync(NotificationSpec spec, CancellationToken ct = null)
Parameters
spec NotificationSpec
Returns
ShowNotificationAsync(NotificationSpec, CancellationToken)
Shows a local notification immediately.
ValueTask<NotificationStatus> ShowNotificationAsync(NotificationSpec spec, CancellationToken ct = null)
Parameters
spec NotificationSpec
Returns
CancelNotificationAsync(Int32, CancellationToken)
Cancels a scheduled/shown notification by its NotificationSpec.Id.
ValueTask<NotificationStatus> CancelNotificationAsync(int id, CancellationToken ct = null)
Parameters
id Int32
Returns
RequestNotificationPermissionAsync(CancellationToken)
Requests notification permission (may prompt).
ValueTask<NotificationStatus> RequestNotificationPermissionAsync(CancellationToken ct = null)
Parameters
Returns
CheckNotificationPermissionAsync(CancellationToken)
Reads notification permission WITHOUT prompting.
ValueTask<NotificationStatus> CheckNotificationPermissionAsync(CancellationToken ct = null)
Parameters
Returns
AuthenticateAsync(String, CancellationToken)
Shows an OS biometric prompt with reason and returns
a BiometricStatus — failure / cancellation / lockout / no-hardware
are all DATA, never a throw.
ValueTask<BiometricStatus> AuthenticateAsync(string reason, CancellationToken ct = null)
Parameters
reason String
Returns
IsBiometricAvailableAsync(CancellationToken)
Checks biometric availability WITHOUT prompting;
BiometricStatus.Authenticated means "present + enrolled + ready".
ValueTask<BiometricStatus> IsBiometricAvailableAsync(CancellationToken ct = null)
Parameters
Returns
SetSecretAsync(String, String, Boolean, CancellationToken)
Writes an encrypted-at-rest secret. When requireAuth
is true the secret is bound to biometric auth at the OS-key level, so it can only
be read back by IMobileBridge.GetSecretWithAuthAsync(String, String, CancellationToken). Values over
SecretResult.MaxValueBytes are rejected with a status, never crash.
ValueTask<SecureStorageStatus> SetSecretAsync(string key, string value, bool requireAuth, CancellationToken ct = null)
Parameters
key String
value String
requireAuth Boolean
Returns
ValueTask<SecureStorageStatus>
GetSecretAsync(String, CancellationToken)
Reads a secret that is NOT auth-bound. The value rides
SecretResult.Value only on SecureStorageStatus.Ok.
ValueTask<SecretResult> GetSecretAsync(string key, CancellationToken ct = null)
Parameters
key String
Returns
GetSecretWithAuthAsync(String, String, CancellationToken)
Reads an auth-bound secret, presenting a biometric prompt with
reason. The OS itself refuses the plaintext without a fresh auth.
ValueTask<SecretResult> GetSecretWithAuthAsync(string key, string reason, CancellationToken ct = null)
Parameters
key String
reason String
Returns
DeleteSecretAsync(String, CancellationToken)
Deletes a secret (a no-op if absent).
ValueTask<SecureStorageStatus> DeleteSecretAsync(string key, CancellationToken ct = null)
Parameters
key String
Returns
ValueTask<SecureStorageStatus>
CapturePhotoAsync(CaptureOptions, CancellationToken)
Captures a photo through the system camera. The image crosses back as
a file:// PATH in PhotoResult (the bytes stay on disk), which
is a valid BnImage.Src. A cancel / denied / no-camera outcome is a
CameraStatus value, never a throw. Use options to
bound the file size; the app owns the temp file after return.
ValueTask<PhotoResult> CapturePhotoAsync(CaptureOptions options, CancellationToken ct = null)
Parameters
options CaptureOptions
Returns
CheckCameraAvailabilityAsync(CancellationToken)
Checks camera availability WITHOUT prompting or launching the UI;
CameraStatus.Captured means "present + usable",
CameraStatus.Unavailable means no camera.
ValueTask<CameraStatus> CheckCameraAvailabilityAsync(CancellationToken ct = null)
Parameters
Returns
GetPlatformInfoAsync(CancellationToken)
Returns typed PlatformInfo for the running platform.
ValueTask<PlatformInfo> GetPlatformInfoAsync(CancellationToken ct = null)
Parameters
Returns
Events
NativeEvents
Raised when the native host pushes an event into .NET — a lifecycle callback, a notification tap-through, and the like.
event Action<NativeEvent> NativeEvents;