Platforms
The framework is two halves. The core — everything under NE.Standard.UI.* except the Web packages —
knows nothing about HTML, HTTP, SignalR or a browser: it compiles views, runs controllers, keeps the two in sync
through a stream of updates, and hands a platform a description of what to draw. A platform renders that
description, carries the updates to a client and the client's changes back, and implements the handful of
services a controller reaches through its context. Web is the full UI platform that ships today — with
NE.Standard.UI.Desktop hosting that Web stack in a native Windows WebView2 window over an
in-process HTTP/2 loopback server or a remote host — alongside NE.Standard.UI.Client and NE.Standard.UI.Server for
in-process and remote C# clients; this page is the contract a platform builds against.
What the core gives a platform
- A compiled view.
IUIHost.ResolveViewAsyncanswers aUIViewResolution: the route, the navigation request, the session, and aCompiledView— component nodes with their properties, the binding templates and indexes, the events, interactions, validation rules, item templates and dialogs, all addressed by id. A platform walks the nodes and draws each by itsTypeKey; ids are stable for the life of the process, so what it drew can be addressed by every later update. - A runtime per client.
IUIHost.AttachRuntimeAsynccreates or finds theIUIRuntimebehind a route with a controller, keyed by session, address and window (UIRuntimeKey,UIPersistenceOptions.Lifetime). The runtime answers the initial values (BuildInitialChangeSetAsync,BuildInitialCollectionChangesAsync), takes the client's writes (ProcessChangeSetFromUIAsync; a platform's endpoint calls it throughIUIClientEndpoint.ProcessChangeSetAsync), runs commands (ProcessEventAsync), reads item windows (RequestItemWindowAsync), and the core's own scheduler flushes what the controller changed in the meantime (IUIClientEndpoint.FlushAsyncfor a platform that flushes itself). - The page's own life. A live connection resolves through
ResolvePresentedViewAsync, which answersnullwhere the session it presented would have to be issued anew — only the request that opens the view can hand one out — andNamesRuntimeOfsays whether an attach lands on the runtime the connection already holds.ReportClientStatetakes what the page says of itself (shown or hidden, its notification permission); a page's own language, theme or colours switch, once stored, goes toApplySessionChangeAsync(ReachSessionAsyncfrom a page with no runtime), so the session's other pages follow. A platform that renders on the server first lets a kept runtime hear what moved (HearBeforeRenderAsync) and hands out a key a sign-in issued meanwhile (TakeRenderKey) —IUIRenderEndpoint, the part of the host a platform whose client draws the page from the attach never needs. - A stream of updates. Everything the client has to change arrives as a
ServerChangeSetofServerUIUpdates — a value, a collection change, a validation message, a full resync — each naming a component address and a property. A platform applies them to whatever it drew. - Client effects. A command or an interaction can raise a
ClientEffect(focus, scroll, navigate, open a dialog, show a notification, copy to the clipboard, ...).ClientEffectKindslists the built-in names; a platform runs the ones it implements and ignores the rest with a log line — a kind is a request, not a guarantee.DownloadFileEffectis the one shaped by the web — it names a path the browser fetches — and a platform whose download service saves the file itself never raises it. - The words the chrome needs.
UIStringsnames every word the framework draws that no author property sets — a picker's "Today", a notification's "Close" — with English text; the platform asks theITranslatorfor the session's language and draws that. - The theme.
UIThemeis twoUIColorPalettes, aUITypography, aUIThemeShape, and the focus-ring and press-ripple switches — values, not CSS. The web turns them into custom properties; another platform turns them into brushes. - Client-side rules. Filter and sort rules on a plain or virtualized items host run on the client.
UIComparisonEvaluatorin the core is the reference for what an operator answers — text comparison unless the operator is numeric,nullreading as the empty string, a non-number comparing false under every numeric operator — and a platform's client follows it, or the two halves disagree about which row is visible.
What a platform implements
UIStartupBase refuses to start without these three. The first is the platform's own, which the web registers in
WebStartupBase; the other two ship in Core, registered by UIStartupBase unless the platform registered its own first.
A dialog needs nothing of the platform: Context.Dialogs sends its effect through the runtime, over IUIUpdateSink.
| Service | What it does |
|---|---|
IUIUpdateSink |
Pushes a ServerChangeSet to every attached instance of a runtime, and a command's result to the one instance that raised it. |
IUIDownloadStager |
Stages a stream for the client to fetch as a file and answers the DownloadFileEffect that fetches it, which Context.Downloads sends through the runtime — StandardDownloadStager, in Core, does the staging over IUIFileStore; the platform supplies only IUIDownloadAddressProvider.AddressOf(token), turning a staged token into the address the client fetches it from (the web: /_ne/files/{token}). An in-process platform can write the content straight into a save dialog instead, answer no effect, and needs no address at all. |
IUIUploadService |
Answers the files a FileInput selection carries, by selection id and file id, scoped to the session — StandardUploadService, also in Core, over IUIFileStore. |
Optional, and worth having:
IUserSessionResolver— the shipped resolver loads the session the client presented and issues a new id when it presented none; a platform only replaces it to source identity differently. What the platform does own is carrying the id: the web puts it in anHttpOnlycookie named byUISessionOptions.ClientKey(under__Host-over HTTPS); an in-process platform holds it in memory.IUIContentAddressResolver— where the platform serves content anIUIContentProvideranswers by key (an avatar, a chat background);UIContentAddressis the default implementation, a fixed prefix the platform's startup constructs once at registration (new UIContentAddress(WebContentEndpoint.Prefix)on the web) and registers as the singleton. Reachable asUIApplication.Contentand, for a controller,Context.Content.- A theme-persistence helper —
SetThemeEffectboth puts the client into a theme and reports the choice back to the session, so the next render agrees; the session write isUserSessionStoreExtensions.SetThemeModeAsync, a Core helper overIUserSessionStorea platform's theme-switch handler calls (the web:WebUIHub.SetThemeAsync). IUISessionKeyHandover— hands a page the key of the session its sign-in moved to a new id (the web: a one-time token the page trades for its cookie,WebSessionKeys). With none registered, a sign-in still moves the session and its client is left without the key.UIPlatformDefaults— what the platform decides for an option the application left unset: whether missing words are reported, and whether an author's mistake found as a page runs is told to the page's console (the web: both in Development).
And the glue that has no interface, because it is the platform's own shape:
- A connection is a
UIInstance— a transport id, aWindowIdand the navigation request — wrapped with the session into aUIHandle. A window is one top-level surface showing one address (a browser tab, a desktop window); one handle per attached client, and the runtime keeps every attached instance and the update sink sends to all of them. - Resolve, then attach. A page load calls
ResolveViewAsync(which runs the view filters and the route authorization) and thenAttachRuntimeAsync; the runtime'sIsInitializedsays whether the controller'sOnInitializeAsynchas run.DetachRuntimewhen the connection goes; the core keeps the runtime forDisconnectedRetentionso a reconnect finds it. - The phase.
ResolveViewAsynctakes aUIViewRequestPhase:Openfor the request that opens the view and can hand the client a new session id,Attachfor a live connection attaching to it. The web calls both, once each per page load; a platform with one step passesOpen— that is the phase in which a pending session-id rotation (a host principal's sign-in) is carried out, so a platform that never passes it never rotates.SignInAsyncmoves the session at once and hands the new key to the platform'sIUISessionKeyHandover(above). - Two-way values. A platform decides which of its controls write back and sends a
ClientChangeSetofClientValueUIUpdates; the core accepts a value only for a property declared writable (UIBindingCapabilities.TargetToSource) and coerces it to the property's type (RecursiveValueCoercion). - Items. A static list is rendered by the platform from the compiled template; a bound list arrives as
collection inserts and is rendered from the same template on the client. Every item is keyed by its
Id, and an address inside a template carries the keys of the enclosing rows as dynamic parameters — the walk that resolves a template against an item isItemContextin the core (NE.Standard.UI.Compiled), which the web's renderers call and its client mirrors inbinding-template-evaluator.ts, held to one shared corpus of cases so the two cannot drift. - A dialog's own dismissal is a client-raised event.
UIDialog.OnCloseregisters a command on the dialog's content component under the reserved event nameclose; a platform raises it only when the viewer dismisses the dialog (Escape, the backdrop) and never when the server closes it itself, or a controller cannot tell the two apart. - A bound value written as a URL must be checked before it reaches the client. An
href, an imagesrcor a backgroundurl()built from a bound value is ajavascript:/non-image-data:injection surface on both the render path and the live-patch path; the web checks both through one shared helper (WebUrlSafety) rather than trusting the render path and forgetting the patch path or vice versa, and judges an address as the browser's URL parser will read it —/\host, or//hostbehind a control character or a tab, is another site. A second platform needs the equivalent check on whatever it treats as "safe to write as a link or an image source." - Chrome a component's picker enforces is advisory only.
FileInput.MaxFileSize(the web writesdata-ui-file-max-size) and any similar picker-side limit are the client refusing early for a better experience; the real limit is still enforced wherever the bytes are received, since a client can simply not send the attribute a picker chrome reads. UITheme.PressRippleandUITheme.OverlayScrollbarsare looks a theme may switch off, not mechanisms a platform must implement. The web reads it at render (data-ui-press-rippleon the root) and answers it with a client engine; a platform that draws presses another way is free to ignore the flag.
Where the seam is drawn
Contracts/andCore/reference nothing above them and no web package;Web.AbstractionsreferencesShell, neverCore, so a render add-on does not drag the engine in.- A platform reaches the host through
IUIHostand the application throughUIApplication, both public;UIHostitself is internal on purpose. Nothing a platform needs is internal: the web slice builds on the core with noInternalsVisibleTo, through the seams a second platform uses — the members above, and the helpers that keep two platforms counting alike:UIAllowanceCharge(what an upload or a staged value counts against the session's allowance, reserved before its bytes are taken),StoredUserSessionResolver.ApplyClaims(the host's principal over a session a side endpoint reads underUIIdentitySource.Claims) andUIApplicationStorage(the application's own folder under the temp folder, for a platform's caches). - The wire is JSON only where a wire exists. The converters on
UIComponentId,UIProperty,ServerUIUpdateandClientEffectlive with the types so every channel agrees; an in-process platform never serializes and never touches them.