Uno MVUX
MVUX is the state-management pattern Uno Platform projects use instead of hand-written MVVM. A partial record Model exposes feeds and states; a source generator produces the bindable ViewModel. Generic agents get MVUX wrong in a handful of predictable ways (calling the deprecated Update alias, mutating a read-only feed, skipping key equality, dropping partial or the Model suffix). This skill exists to stop those mistakes and to route you to the detailed reference for the task at hand.
Check the project's pattern first
Look at <UnoFeatures> in the app's project file before writing any presentation code.
MVUXis listed, or the project has*Modelrecords: use this skill.Mvvmis listed, or ViewModels derive fromObservableObjector use[ObservableProperty]/[RelayCommand](CommunityToolkit.Mvvm): the app is MVVM. Keep writing CommunityToolkit.Mvvm ViewModels; do not addMVUX, convert ViewModels to Models, or mix the two in one app unless the user asks for a migration. The rest of this skill does not apply.- A new app with no pattern chosen: MVUX is the default unless the user asks for MVVM.
Workflow
- Find the task in the topic map below and read the matching
references/*.mdfile before writing code. Each reference is short and self-contained. - The reference answers the common case; the docs pages it names are for what it leaves out. Then search with
uno_platform_docs_search(...)and fetch only the section you need:uno_platform_docs_fetch(sourcePath="…", anchor="…"), both values from a search result. A whole page is 2,000 to 6,000 tokens that stay in context for the rest of the session. Never pass a URL,.htmllink, or hand-built path. - Apply the critical rules below. They are the mistakes that compile-fail or silently break UI, so check the generated code (in
obj/from the last build; with the app running, the Hot Reload status reports a Model that fails to compile) against them before finishing.
Topic map
| Task | Read | Key APIs |
|---|---|---|
| Explain MVUX, compare with MVVM, add MVUX to a project | references/overview.md |
<UnoFeatures>MVUX</UnoFeatures>, *Model → *ViewModel |
| Design entities and Models | references/records.md |
partial record, IKeyEquatable<T>, [Key], with |
| Load a single async value from a service or API | references/feed-basics.md |
IFeed<T>, Feed.Async, Select, Where, Signal |
| Load a collection | references/listfeed.md |
IListFeed<T>, ListFeed.Async, IImmutableList<T> |
| Show a feed in XAML with loading, error, and empty UI | references/feedview.md |
mvux:FeedView, {Binding Data}, Refresh |
| Two-way bind user input, hold editable state | references/state-basics.md |
IState<T>, State.Value, UpdateAsync, ForEach |
| Add, remove, or edit items in a list | references/liststate.md |
IListState<T>, AddAsync, RemoveAllAsync, UpdateAllAsync, UpdateItemAsync |
| Bind a Button or other control to a Model method | references/commands.md |
public methods → IAsyncCommand, [ImplicitCommands] |
| Track the selected item or items of a list | references/selection.md |
.Selection(state), IState<T>, IState<IImmutableList<T>> |
| Infinite scroll or page-by-page loading | references/pagination.md |
ListFeed.PaginatedAsync, PageRequest |
| Keep several pages in sync after create/update/delete | references/messaging.md |
IMessenger, EntityMessage<T>, .Observe(messenger, e => e.Id) |
Critical rules
These come up in nearly every MVUX task. Each reference repeats the ones it needs, but read them once here.
- Models are
partial recordtypes with aModelsuffix (MainModel,ProductsModel).partial recordis the convention; the generator gates onpartialplus theModelsuffix, so apartial classalso generates. The generator emitsMainViewModel; that generated type is what the page'sDataContextreceives. Services are injected through the record's constructor parameters. - Entities are records. MVUX relies on immutability and value equality. Use
withexpressions to produce modified copies. - Feeds are read-only, states are writable.
IFeed<T>andIListFeed<T>have noUpdate/Add/Remove; calling them is a compile error. If code must mutate, the property must beIState<T>orIListState<T>(convert withListState.FromFeed(this, feed)). - The mutation method is
UpdateAsync, and it must be awaited.Update(updater, ct)still exists onIState<T>andIListState<T>, but it is hidden (EditorBrowsable(Never)), documented as deprecated, and needs the token. Its[Obsolete]is compiled only into Debug builds of the library, so Release packages accept it without a warning and the official template's MAUI-embedding sample (--sample --maui-embedding) still writesawait Count.Update(x => ++x, ct). Preferawait state.UpdateAsync(current => ...). On a list, edit one item withUpdateAllAsync(predicate, updater)orUpdateItemAsync(item, updater); the hiddenUpdateAsync(predicate, updater, ct)overload also still compiles, and the single-delegateUpdateAsynconIListState<T>receives the wholeIImmutableList<T>. - Updaters are pure. Derive the new value only from the
currentargument. Do not capture fields or perform side effects inside the lambda; MVUX applies it against a cached value and a non-pure updater gives unstable results. Astaticlocal function is the safest form. - List item types need key equality. Any record used in
IListFeed<T>orIListState<T>must implementUno.Extensions.Equality.IKeyEquatable<T>, which is auto-generated for apartial recordwith anIdorKeyproperty, or via[Key](assembly-wide names via[assembly: ImplicitKeys(...)]). Without it, value equality still matches unchanged items, but an edited record becomes a remove plus an add (selection and animation continuity are lost), and theUpdateAsync(T item)/UpdateItemAsyncoverloads do not compile at all (CS0311, or CS0453 forUpdateItemAsyncbecause overload resolution falls to its struct overload: they are constrainedwhere T : IKeyEquatable<T>). Never invent a substitute interface such asIHasKey<T>. - Bind the Model surface with
{Binding}, notx:Bind. The templates, the docs, and Chefs all use{Binding}.x:Bindneeds a typed property on the page for the generated ViewModel, and record-typed states are exposed as a generatedBindable<Name>ViewModelclass with a private setter (opt out with[Value]; simple-typed states are plain properties). On Uno.Sdk 7.0.0-dev.77 any TwoWayx:Bindto a generated ViewModel member fails at build (UXAML0001Unable to find member, even for anintstate), and a public page property typed as the generated ViewModel fails with CS0400. FeedViewbinds the feed, templates bindData.Source="{Binding MyFeed}"on theFeedView; inside its value template use{Binding Data.Property}.FeedViewalready exposesRefresh; do not create a refresh command. The value template can bind{Binding Refresh}, butErrorTemplateandProgressTemplatereceive the exception and the progress flag as their DataContext, so a retry button there needsCommand="{Binding Refresh, ElementName=<feedViewName>}".- Any public method on the Model becomes a command. A parameter receives a snapshot of a feed when its name matches an
IFeed<T>/IState<T>property case-insensitively and its type is exactlyT(exactlyIImmutableList<T>for a list feed); a name match with any other type silently becomes theCommandParameter. A method becomes a command only with 0 or 1 non-feed parameters and 0 or 1CancellationToken. Opt out with[ImplicitCommands(false)]. - Service methods take a
CancellationTokenand returnValueTask<T>(ValueTask<IImmutableList<T>>for lists).Feed.Async/ListFeed.Asynctake anAsyncFunc<T>(ValueTask<T>(CancellationToken)), so such a method group passes directly; aTask<T>method needs a lambda:Feed.Async(async ct => await Service.GetAsync(ct)).
Related skills
uno-navigationfor moving between pages and passing entities; MVUX Models are registered withViewMap/DataViewMapthere.uno-toolkit(references/itemsrepeater-extensions.md) when a paginated or selectable list is rendered withItemsRepeaterinstead ofListView.uno-testingto verify loading, error, and value states of aFeedViewin a running app.