English | 繁體中文
A demonstration — the classic Northwind inventory business case — built on the Polhem framework (consumed purely as NuGet packages) to show how an application is assembled from definitions. It exists to make one argument concrete:
A new screen with full create / read / update / delete, list browsing, and cross-table lookups is a few XML definition files — not UI code, not CRUD code, not SQL.
Master-data forms, master-detail orders with three lookups, framework organization tables, a per-form audit rule editor, and exactly one hand-written business object (the order rules) — everything else is definitions.
- Definition-driven CRUD —
FormSchemais the single source of truth that drives the UI form, the list view, the database table, and the validation surface. - Cross-table lookups with zero code — a relation field plus a field-mapping in XML gives you a pick dialog, the foreign key, and the denormalized display columns (re-derived by a server JOIN on reload).
- Master-detail documents — orders carry a detail grid with per-row product lookup, saved and reloaded as one unit.
- Declared rules, and one business-logic object for the rest — the order's required fields and per-line amount are declared in its
FormSchema; order numbering, status transitions, the at-least-one-line check and the order total are the only C# business logic in the app, in oneOrderBO. The comparison table below shows exactly which behavior is definition, which is framework, and which is application code. - Framework system tables (
st_) alongside business tables (ft_) —Employee/Departmentare framework tables the app reuses and extends;Customer/Product/Orderare business tables the app defines. - Localized captions and a tenant customization layer — the Order form's zh-TW captions come from a language resource, and a customization layer renames two of them for this tenant while inheriting the rest. Both are definition files; neither is code.
Requires the .NET SDK 10.0.400 or later (the analyzers in the Polhem.Definition package need its compiler). The database is SQLite, created and seeded on first run — no setup.
Open the repository, pick Run Polhem.Northwind (Server + Desktop) from the Run & Debug dropdown, and press F5. It builds and launches the JSON-RPC server and the desktop client together.
Two terminals from the repository root:
# 1. Backend (JSON-RPC on http://localhost:5100)
dotnet run --project src/Polhem.Northwind.Server
# 2. Desktop client
dotnet run --project src/Polhem.Northwind.DesktopThen in the app: Connect (the endpoint is pre-filled) → Sign in with one of the two seeded accounts:
| Account | Password | Culture | What you see |
|---|---|---|---|
demo |
demo |
en-US |
English captions and formats |
demo-tw |
demo |
zh-TW |
Traditional Chinese captions (including the tenant's customized ones) and formats |
Both accounts enter the same company and see the same data; the session takes its language from the account (st_user.culture), not from the operating system.
The same UI also runs in the browser via the Avalonia Browser head — the same App, view
models and views compiled to WebAssembly. It needs the wasm-tools workload
(sudo dotnet workload install wasm-tools) and the running server above, then:
# Web client dev server (Avalonia WASM on http://localhost:5200)
dotnet run --project src/Polhem.Northwind.BrowserOpen http://localhost:5200/ and connect / sign in the same way. See
src/Polhem.Northwind.Browser/README.md for the WASM-specific wiring
(localStorage endpoint, async connect, overlay dialogs, publish notes).
The same UI also runs on iOS and Android as Avalonia single-view heads, against the same server
above. Debug is the convenient default below (no signing, fast iteration). Release builds keep
the SDK's default partial trimming, which Polhem supports: Polhem.Definition ships an
ILLink.Descriptors.xml that keeps the definition types XmlSerializer reaches by reflection.
Full trimming and NativeAOT are not supported, and a build configured for them gets the
POLHEM9004 warning. Shipping to a physical iOS device additionally needs an Apple Developer
signing identity. The
screen reflows responsively — single-column forms and card lists on a narrow screen — and on
Android the hardware / gesture back button unwinds record → tab before exiting.
# iOS simulator (needs the ios workload + Xcode; start a simulator first)
dotnet build src/Polhem.Northwind.iOS -t:Run -f net10.0-ios -c Debug
# Android emulator (needs the Android SDK + JDK 17; start an AVD first)
dotnet build src/Polhem.Northwind.Android -t:Run -f net10.0-android -c DebugOn the Android emulator the host machine is reached at 10.0.2.2 (not localhost), so set the
endpoint to http://10.0.2.2:5100/api; the manifest enables cleartext HTTP for development. On the
iOS simulator use http://localhost:5100/api (ATS allows arbitrary loads in dev).
The first server run creates
northwind.dbin the server project folder (src/Polhem.Northwind.Server/, where.gitignorecovers it) and seeds a Northwind subset. Delete that file to reseed from scratch.The desktop and mobile heads remember the endpoint and the API key in the framework's default
FileEndpointStorage: a per-user folder named after the head's entry assembly (for examplePolhem.Northwind.Desktop) under the local application data directory. Where that directory is on each platform is described onFileEndpointStorageinPolhem.UI.Core. The browser head keeps them inlocalStorageinstead.
The same Order form rendered by all four Avalonia heads — same definitions, same controls, only the platform shell differs.
Desktop and Browser (WASM):
| Desktop | Browser |
|---|---|
![]() |
![]() |
iOS and Android:
| iOS | Android | |
|---|---|---|
| Order list | ![]() |
![]() |
| Order detail | ![]() |
![]() |
| Menu | ProgId | Table | Layer | Highlights |
|---|---|---|---|---|
| Categories | Category |
ft_category |
business | plain master, zero code |
| Suppliers | Supplier |
ft_supplier |
business | plain master |
| Customers | Customer |
ft_customer |
business | plain master |
| Shippers | Shipper |
ft_shipper |
business | plain master |
| Products | Product |
ft_product |
business | two lookups (Supplier + Category) |
| Departments | Department |
st_department |
framework system | reused framework table |
| Employees | Employee |
st_employee |
framework system + extension | framework fields + title / hire_date; dept lookup carries the department manager as supervisor |
| Orders | Order |
ft_order + ft_order_detail |
business (master-detail) | three master lookups (Customer / Employee / Shipper) + per-row product lookup; the one OrderBO |
| Audit Rules | AuditRule |
st_audit_rule |
framework system | per-form audit overrides, under Administration; framework business object |
The table prefix records who owns the table, not which database it lives in:
st_— framework / system tables. Shipped by the framework, shared across applications, relied on by framework features (permissions, organization).Employee(st_employee) andDepartment(st_department) are framework tables. The app copies their definitions from the framework defaults into its ownDefine/(the same way a new project is scaffolded), keeps the standard fields, and extends them —Employeeaddstitleandhire_date.ft_— business tables. Defined by this application:Category,Supplier,Customer,Shipper,Product,Order,Order Details.
Order → Employee is the interesting cross-layer edge: a business table (ft_order) points at a framework system table (st_employee) — the salesperson on an order is a framework employee.
The prefix says who owns a table; a separate axis says which database it lives in. A FormSchema's CategoryId selects the database scope, and it has exactly three values:
company— per-company business data: theft_tables and the org tablesst_department/st_employee(an application's employees belong to that company). The router resolves company scope through the session's company to the company database.common— cross-company shared framework tables: users (st_user), sessions, the cache-notify signal, definition storage, companies and API keys. Not application data.log— the audit trail: one table each for logins, data changes, reads, and API / database anomalies. Production deployments usually give this its own database, because it grows on a different curve from business data and is read by different people.
The two axes are orthogonal: st_department / st_employee are framework-owned tables (st_ prefix) that live in the company database, because a company's employees are that company's data. Tying "who owns it" to "where it lives" is what breaks on a multi-company deployment.
All three categories are registered in Define/DbCategorySettings.xml, and the seeder builds every table listed there — which is what makes adding a table pure XML.
This demo is single-company, so all three databases point at the same northwind.db file. The category is what the framework routes on, so moving the audit trail (or one company) to its own database later is a change to DatabaseSettings.xml alone — not one form definition has to move.
Signing in answers two questions, and the framework asks them separately. Login answers who you are; EnterCompany answers which company you are in, and fills the half of the session that cannot be derived without that answer — the customization code, the roles, and the record-scope row ids. The demo has one company, so it enters it automatically right after sign-in; a deployment with several puts a chooser between the two calls and changes nothing else.
Both steps run entirely on framework code. The application substitutes no service and overrides no method:
- Authentication is the framework's own
st_usercheck. The seeder writes thedemoanddemo-twaccounts on first start (and adds either one to an existingnorthwind.dbthat lacks it), with the password hashed throughPasswordHasherat seed time (not a literal hash, which would silently stop matching the first time the hashing parameters change). Comparing an account and a password is the same operation in every deployment, so it belongs to the framework. - Company entry is the framework's own
EnterCompany. The seeder writes the matchingst_companyandst_user_companyrows, and the call then validates the company exists and is enabled, checks the user's access, and snapshots roles and the employee context onto the session.
That st_user row also carries time_zone and culture, so the session takes its zone, and the client its language, from the user rather than from the server or a deployment default.
A single company is not a reason to skip the second step. An earlier version of this demo took that shortcut — it stamped
SessionInfo.CompanyIdin an overriddenLogininstead of callingEnterCompany— and it cost more than it saved, in two ways that were both silent. Company-keyed lookups such as the per-form audit rules below resolve the company throughst_company, so with no row there they returned "no rules" and every rule was ignored. AndEnterCompanypersists the company onto thest_sessionseed, which an application cannot do for itself; without it the company survived only in the cache, so a server restart handed the client back a session that authenticated but could not open a single company-scoped form.
With auditing enabled in SystemSettings.xml, every successful, failed and locked-out sign-in lands in st_log_login automatically, again with no application code: the framework's own Login writes one record on each of those three paths. The demo sets UseBackgroundWriter to false so a record is visible the moment sign-in returns; a production host keeps the default batch writer.
Which forms are audited is a per-form decision, not one switch for everything. SystemSettings.xml sets the deployment-wide defaults — this demo records changes and does not record reads — and st_audit_rule overrides them one form at a time. The seeder writes three rows to make the mechanism visible: Order and Customer turn read logging on against the deployment default and mark their entries sensitive; Category turns change logging off, because reference data churn is noise in an audit trail. Every other form carries no row and simply inherits. The rules live in the company database and are edited through the Audit Rules form under Administration.
The demo's copy of
AuditRule.FormSchema.xmldrops thePermissionModelIdthat the framework ships, because Northwind has no permission infrastructure at all and enforcement is fail-closed — keeping it would make the form impossible to open. A real deployment keeps it and grants the model to an administrator role: anyone who can edit these rules can decide what is and is not recorded.
Northwind is a normalized relational schema; polhem is a sys_rowid (Guid) relation model. The demo borrows Northwind's business case and data, but the keys and relations follow polhem conventions:
| Northwind | polhem convention |
|---|---|
text / int primary key (CustomerID='ALFKI', ProductID=17) |
sys_id (string business code) + sys_rowid (Guid relation key) + sys_no (auto-increment) |
name column (CompanyName, ProductName) |
sys_name |
foreign key (Orders.CustomerID) |
customer_rowid (Guid) + RelationProgId="Customer" + field mappings that fill ref_customer_id / ref_customer_name |
composite-key detail (Order Details: OrderID+ProductID) |
sys_rowid PK + sys_master_rowid (→ Order) + product_rowid (lookup → Product) + quantity / price |
| employees | framework st_employee: framework fields + Northwind data columns; the manager comes from the department, not a ReportsTo self-relation |
This is the whole argument in one table.
| Behavior | Source | Where |
|---|---|---|
| Form layout, field editors, labels | definition | FormLayout, one stored file per form (FormLayoutGenerator drafts it from the FormSchema at design time); labels from the FormSchema |
| List columns and browsing | definition | FormSchema.ListFields |
| Database table + indexes | definition | TableSchema |
| Insert / update / delete dispatch | framework | FormBusinessObject + repository |
| Lookup dialog, foreign key write-back, JOIN reload | definition + framework | relation field + RelationFieldMappings; framework GetLookup |
| Master-detail save as one unit | framework | repository, driven by the multi-table FormSchema |
| Order's required fields and per-line amount | definition | Order.FormSchema.xml: Rules (FormRule) and a ValueExpression field |
| progId to business-object and repository binding | definition | ProgramSettings.xml (the type registry) |
| Navigation menu (grouped form list) | definition | MenuSettings.xml |
| Localized captions and display names | definition | Define/Language/{lang}/{progId}.Language.xml |
| Per-tenant caption overrides | definition | Customize/{customizeId}/Language/…, resolved per key |
| Login / session / encryption | framework | SystemBusinessObject, API pipeline |
| Order number, status transitions, at-least-one-line check, order total | application code | OrderBO (the only business logic in the app) |
The single C# business object, OrderBO, overrides GetNewData and DoBeforeSave to add what a generic form cannot express. Its pure rules are factored into OrderRules and OrderDataSet, kept free of database dependencies and separate from the orchestration.
Its two database queries live in IOrderRepository / OrderRepository, bound to the same registry entry as the business object — one progId, one business object, one repository. That is the style template for a form that needs data access beyond the generated CRUD: extend IDataFormRepository rather than replace it, derive from DataFormRepository, and let the business object ask for it by interface (CreateFormRepository<IOrderRepository>()). Keeping the SQL out of the business object is also what let these two queries route to the order's own company database instead of the one the business object happened to name.
The Order form is captioned twice over. FormSchema carries the English captions inline, so
English needs no resource file at all — a missing key leaves the schema's own text in place.
Define/Language/zh-TW/Order.Language.xml supplies the zh-TW captions, keyed by the same
convention everywhere (Schema.DisplayName, Table.{table}.DisplayName, Field.{field}.Caption).
Sign in as demo-tw to see them: the session's culture comes from that account's st_user row.
Which language a client shows is the signed-in account's culture: Login returns the
st_user.culture value, and ClientInfo.ApplyLoginResult makes it the client's UI culture. The
seeded demo account is en-US (NorthwindCredentials.Culture), so it opens in English; the
seeded demo-tw account is zh-TW (NorthwindCredentials.ZhTwCulture). To see the zh-TW captions
and the tenant's caption overrides below, sign out and sign in as demo-tw.
On top of that sits the customization layer. The demo company names a customization code
(NorthwindCredentials.CustomizeId), the session picks it up at sign-in, and every definition
lookup then consults Customize/{customizeId}/ before the packaged Define/ tree. This tenant
calls its customers 經銷商, so its zh-TW resource declares exactly two keys:
<LanguageItem Key="Field.customer_rowid.Caption" Value="經銷商" />
<LanguageItem Key="Field.ref_customer_name.Caption" Value="經銷商名稱" />Everything else on the form still resolves against the packaged resource — language text is
overridden per key, not per file — so a caption the package adds later reaches this tenant
without touching its customization. Layouts and menus work the opposite way (whole file wins),
because a partial merge of a visual arrangement has no intuitive answer. This tenant uses that too:
Customize/northwind-demo/FormLayout/Order.FormLayout.xml replaces the packaged Order layout and
leaves the salesperson, shipper and freight off the master block.
Two independent things gate the layer, and clearing either returns the demo to a plain packaged
deployment with no other change: the session's customization code, and PathOptions.CustomizePath
in NorthwindBackend. Companies map many-to-one onto
a customization code, so one code shared by many companies is the normal arrangement — the demo
just happens to have one of each.
Assembling all of this is the client's job, not the server's: the APIs serve definitions exactly
as stored, and FormDefinitionLoader fetches both layers, applies the overlay, and hands the view
a localized schema. One switch covers the whole client — ClientInfo.UseDefinitionLoader, on by
default and set explicitly in App.axaml.cs — and the record
form, the list and the lookup dialog all use ClientInfo.DefinitionLoader. With it off,
a view renders the definitions as stored: English captions, and the packaged layout from
Define/FormLayout/ instead of the tenant's.
Northwind has a Region table the demo leaves out — so you can add it yourself. You will add definition files and settings entries only, no code, then restart and get a fully working CRUD screen.
A region is business data, so it goes in the company category (TableSchema/company/), alongside the other ft_ tables.
<?xml version="1.0" encoding="utf-8"?>
<TableSchema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" TableName="ft_region" DisplayName="Region">
<Fields>
<DbField FieldName="sys_no" Caption="Sequence" DbType="AutoIncrement" />
<DbField FieldName="sys_rowid" Caption="Row ID" DbType="Guid" />
<DbField FieldName="sys_id" Caption="Region Code" DbType="String" Length="20" />
<DbField FieldName="sys_name" Caption="Region Name" DbType="String" Length="50" />
</Fields>
<Indexes>
<DbTableIndex Name="pk_{0}" Unique="true" PrimaryKey="true">
<IndexFields><IndexField FieldName="sys_no" /></IndexFields>
</DbTableIndex>
<DbTableIndex Name="rx_{0}" Unique="true">
<IndexFields><IndexField FieldName="sys_rowid" /></IndexFields>
</DbTableIndex>
<DbTableIndex Name="uk_{0}" Unique="true">
<IndexFields><IndexField FieldName="sys_id" /></IndexFields>
</DbTableIndex>
</Indexes>
</TableSchema><?xml version="1.0" encoding="utf-8"?>
<FormSchema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" ProgId="Region" DisplayName="Region" CategoryId="company" ListFields="sys_id,sys_name">
<Tables>
<FormTable TableName="Region" DbTableName="ft_region" DisplayName="Region">
<Fields>
<FormField FieldName="sys_no" Caption="Sequence" DbType="AutoIncrement" Visible="false" />
<FormField FieldName="sys_rowid" Caption="Row ID" DbType="Guid" Visible="false" />
<FormField FieldName="sys_id" Caption="Region Code" DbType="String" />
<FormField FieldName="sys_name" Caption="Region Name" DbType="String" />
</Fields>
</FormTable>
</Tables>
</FormSchema>The file is named after the progId, not the table. The runtime renders this file and fails when it is absent — it does not derive a layout from the FormSchema. FormLayoutGenerator (or Generate FormLayout in the DefineEditor tool) drafts one from the schema at design time; the result is saved and edited like any other definition.
<?xml version="1.0" encoding="utf-8"?>
<FormLayout xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" LayoutId="Region" ProgId="Region" Caption="Region">
<Sections>
<LayoutSection Name="Main" Caption="Region">
<Fields>
<LayoutField FieldName="sys_id" Caption="Region Code" />
<LayoutField FieldName="sys_name" Caption="Region Name" />
</Fields>
</LayoutSection>
</Sections>
</FormLayout><TableItem TableName="ft_region" DisplayName="Region" />This is what makes the seeder build the table on the next start (it builds every table registered here, into the database the category maps to).
<ProgramItem ProgId="Region" DisplayName="Regions" />ProgramSettings.xml is the type registry: it maps a progId to the types bound to it — a business object and a repository. A progId with no entry, or an entry without those attributes, gets the framework default (FormBusinessObject and the default form repository), so Region works without this line; declaring it keeps the registry a complete list of the programs. Here only Order binds its own types, and AuditLog names the framework's audit-log business object.
<MenuEntry Id="region" Caption="Regions" Order="60" ProgId="Region" />Add it inside the master-data folder. Id is the node key and must be unique across the whole menu tree; it is separate from ProgId so the same program can appear in more than one place.
Restart the server (it creates ft_region) and the desktop client. Regions is now in the left menu under Master Data, with working list, new, edit, delete, and a unique-code check from the uk_ index — all from definition edits, no compilation of your own code.
polhem-northwind/
├── Define/ definitions — the source of truth (no project, read by the server)
│ ├── FormSchema/ one form per file
│ ├── FormLayout/ one stored layout per form
│ ├── TableSchema/{common,company,log}/ one folder per category
│ ├── SystemSettings.xml deployment settings (auditing, security keys, defaults)
│ ├── CurrencySettings.xml currencies and their rounding
│ ├── DatabaseSettings.xml the common + company + log databases
│ ├── DbCategorySettings.xml which tables exist, per category (drives schema build)
│ ├── ProgramSettings.xml the type registry (progId to business object + repository)
│ ├── MenuSettings.xml the navigation menu (folders, order, captions)
│ └── Language/{lang}/ localized captions, one file per progId
├── Customize/{customizeId}/ the tenant customization layer (same shape as Define/; holds only what it overrides)
└── src/
├── Polhem.Northwind.Server/ JSON-RPC backend, OrderBO, JSON seed data
├── Polhem.Northwind.UI/ Avalonia shared UI (views, view models, navigation)
├── Polhem.Northwind.Desktop/ desktop entry point (Avalonia.Desktop)
├── Polhem.Northwind.Browser/ web entry point (Avalonia WASM)
├── Polhem.Northwind.iOS/ iOS entry point (Avalonia.iOS)
└── Polhem.Northwind.Android/ Android entry point (Avalonia.Android)





