Interface INavigationRestore

Namespace

Nalu

Assembly

Nalu.Maui.Navigation.dll

Navigation-state snapshot & restore (opt-in via builder.UseNaluNavigationRestore(...)): after an app restart the engine replays the last captured navigation — root selection, pushed stack and the intents that materialized those pages — landing the user exactly where they were. Restore replays navigation; it never serializes page UI state.

public interface INavigationRestore

Remarks

Capture is automatic: every successful navigation records the current stack, and each page's entering intent is serialized at navigation time. A page is restorable when it was navigated to without an intent, or with an intent whose type is registered via AddIntent<T>(string?); a page reached with an unregistered intent (or one that fails to serialize) ends the restorable stack at that page, and nothing above it restores. Non-serializable intent properties are excluded with JsonIgnoreAttribute and rehydrated on restore via IIntentHydrator<TIntent>.

Replay happens at engine startup, AFTER the configured initial page's first OnAppearingAsync completes — an app's initialization root always runs first. While a restore is pending, navigations not issued by the replay are ignored (returning false and raising the NavigationIgnored lifecycle event): each replay step is enqueued through the dispatcher, so auto-navigations dispatched by intermediate restored pages deterministically drain inside the suppression window. The window lifts just before the LAST restored destination — the page the user actually was on keeps its right to auto-navigate. An initialization flow that must redirect elsewhere (e.g. authentication) calls TryStopRestoreAsync() first.

The service is always injectable and INERT when restore is not enabled — shared and library pages can call it unconditionally. The per-page methods deduce the page they act on: the page whose lifecycle callback is running, or the current top page otherwise.

Methods

ForgetAsync()

Removes the current page from the restoration stack: a restore lands on the page below it (pages above cannot restore either — their context builds on this one). Typical use: entity-creation flows and wizard pages that must never resurrect, calling this from OnEnteringAsync. The exclusion lasts until the page pops. The snapshot is re-captured and persisted before the returned task completes.

Task ForgetAsync()

Returns

Task

RestoreWithIntentAsync(object)

Sets or replaces the intent replayed for the current page on restore — e.g. swapping a "create draft" intent for a "saved entity id" intent once state materializes, or re-opting-in a page whose original intent was not restorable. The intent type must be registered via AddIntent<T>(string?); it is serialized immediately (failures throw at this call site), and the snapshot is re-captured and persisted before the returned task completes.

Task RestoreWithIntentAsync(object intent)

Parameters

intent object

The intent to deliver to this page when it is restored.

Returns

Task

TryStopRestoreAsync()

Stops a pending (or in-flight) restore: the persisted snapshot is discarded, the replay stops after the current navigation, and the navigation-suppression window is lifted. Returns true when there was a restore to stop. Call this from an initialization flow that must navigate elsewhere (e.g. to a login page) instead of letting the replay land the user back in the app.

Task<bool> TryStopRestoreAsync()

Returns

Task<bool>