Polhem.Api.Contracts 1.3.0

Polhem Framework

繁體中文

Polhem Framework is an N-Tier + Clean Architecture + MVVM hybrid designed to accelerate the development of enterprise information systems. It adopts a Definition-Driven Architecture, using FormSchema as the single source of truth to drive UI layout, database schema, and business validation in a unified way.

📌 N-tier means the architecture is divided into more than three logical layers. In Polhem, the system is separated into at least five layers: presentation, API communication, business logic, data access, and database — each with a clearly defined responsibility.

All packages target net10.0.

✨ Features

• Definition-Driven Architecture: FormSchema serves as the single source of truth, automatically deriving UI layout (FormLayout), database schema (TableSchema), and validation rules — define once, sync everywhere.
• N-Tier + Clean Architecture + MVVM: Clear separation of presentation, API, business logic (BO), and data access layers, borrowing the best concepts from each pattern for enterprise information systems.
• Cross-platform compatibility: All packages target net10.0 for modern .NET runtime support.
• Multi-database support: Built-in dialects for SQL Server, PostgreSQL, SQLite, MySQL, and Oracle; host applications register only what they use.
• Modular components: Decoupled libraries for core utilities, data, caching, business logic, and API hosting.
• Rapid development: Reusable base classes and FormSchema-driven CRUD reduce repetitive boilerplate.
• Conventions enforced at build time: Roslyn analyzers ship with the packages and register automatically, turning framework conventions — database scope selection, cross-file definition consistency, wire contract shape — into build diagnostics that name both the cause and the fix. See Analyzer Rules.

📐 Architecture

For an in-depth look at the layered architecture, data flow, and design decisions behind Polhem, see the Architecture Overview.

For guidelines on API Contract and BO Parameter design (Request/Response vs Args/Result), see the API/BO Contract Design Principles. The full catalog of public API methods, with each method's [ApiAccessControl] settings, lives in the API Method Reference.

For calling the JSON-RPC API from a JavaScript / TypeScript frontend (React, Vue, Angular, vanilla — no .NET on the client), see the JSON-RPC Frontend Integration Guide.

For the full developer documentation index, see docs/en/README.md.

📦 Assembly

Each assembly below ships as a NuGet package of the same name. A JSON-RPC server starts with two of them, plus Polhem.JsonRpc.AspNetCore for the HTTP endpoint:

dotnet add package Polhem.Hosting
dotnet add package Polhem.JsonRpc.AspNetCore
dotnet add package Polhem.Db

Getting Started continues from there.

Shared (Frontend / Backend)

Backend

Frontend

Tooling (dotnet tool)

🚀 Quick Start

Want to see Polhem running in 30 seconds?

# Terminal 1 — start the JSON-RPC API host
cd samples/QuickStart.Server
dotnet run

# Terminal 2 — connect and call the Echo BO
cd samples/QuickStart.Console
dotnet run

The console will print System.Ping status and an echoed message returned from a custom BO. See samples/README.md for the full demo list and what each one shows.

Ready to build your own? Getting Started walks through the same thing from an empty folder — packages, DefinePath, DI wiring, your first business object, and calling it from a client.

🌟 Featured demo — Polhem.Northwind

apps/Polhem.Northwind is the flagship demo: the classic Northwind inventory case built almost entirely from definitions (master files, master-detail orders with lookups, exactly one hand-written business object — everything else is XML). The same shared Polhem.Northwind.UI runs on four Avalonia heads — Desktop, Browser (WASM), iOS, and Android — against one JSON-RPC server.

The same Order form rendered by each head — same definitions, same controls, only the platform shell differs:

More screens, the form catalog, and how to run it: apps/Polhem.Northwind/README.md.

💡 Sample Projects

All demos live in-repo under samples/. They're minimal, focused, and evolve alongside the framework. Build them with dotnet build samples/Polhem.Samples.slnx (kept separate from the main Polhem.slnx, so the main CI/build stays unaffected).

Migrating from Bee.NET

Polhem continues the Bee.NET framework (Bee.* packages) under a new name, with no compatibility layer. What an upgrade has to change is in Migrating from Bee.NET.

Design decisions

The reasons behind the design are recorded in the architecture decision records.

Contributing

See CONTRIBUTING.md.

License

MIT. Copyright (c) Polhem contributors.

📬 Contact & Follow

Polhem is maintained by the polhem-dev organisation on GitHub.

• Questions, ideas and show-and-tell: GitHub Discussions
• Bug reports and feature requests: GitHub Issues