<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Jeff on Medium]]></title>
        <description><![CDATA[Stories by Jeff on Medium]]></description>
        <link>https://medium.com/@jeff377?source=rss-6d011dcf2f94------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/0*wkbdEfkEnK54b3XO</url>
            <title>Stories by Jeff on Medium</title>
            <link>https://medium.com/@jeff377?source=rss-6d011dcf2f94------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Mon, 16 Nov 2026 14:58:54 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@jeff377/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[From Paper Forms to Data-Entry Forms]]></title>
            <link>https://medium.com/@jeff377/from-paper-forms-to-data-entry-forms-440e9f8287f9?source=rss-6d011dcf2f94------2</link>
            <guid isPermaLink="false">https://medium.com/p/440e9f8287f9</guid>
            <category><![CDATA[software-architecture]]></category>
            <category><![CDATA[erp]]></category>
            <category><![CDATA[dotnet]]></category>
            <category><![CDATA[artificial-intelligence]]></category>
            <dc:creator><![CDATA[Jeff]]></dc:creator>
            <pubDate>Mon, 16 Nov 2026 14:28:11 GMT</pubDate>
            <atom:updated>2026-11-16T14:28:11.595Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*XgWuJYEFinYMfQfW.png" /></figure><iframe src="https://cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.youtube.com%2Fembed%2Fhkt_KAwcVro%3Ffeature%3Doembed&amp;display_name=YouTube&amp;url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3Dhkt_KAwcVro&amp;image=https%3A%2F%2Fi.ytimg.com%2Fvi%2Fhkt_KAwcVro%2Fhqdefault.jpg&amp;type=text%2Fhtml&amp;schema=youtube" width="854" height="480" frameborder="0" scrolling="no"><a href="https://medium.com/media/67d430681318910657c6203231d2d249/href">https://medium.com/media/67d430681318910657c6203231d2d249/href</a></iframe><ul><li><a href="https://youtu.be/hkt_KAwcVro">English version</a>, 3:39</li><li><a href="https://youtu.be/ULkowf0RFhA">Chinese version</a>, 3:06</li></ul><p>The video was recorded with Polhem 1.15.0.</p><p>Most of the forms a company uses already exist as a PDF or a Word file, or at least as a sheet of paper you can take a photo of. To enter data through them in a system, though, you usually have to define them all over again: which fields the header has, what the line items look like, which fields pick an employee or a vendor, how the total is calculated. With many forms, that alone takes a good amount of time.</p><p>Polhem 1.15.0 adds Import Form from Documents to DefineEditor (Polhem’s definition file editor). You give the document to an AI model, and it drafts the form. In a conversation, you answer its questions and ask for changes in your own words. Once the draft is settled, you create the definitions and upgrade the database, and the form is ready for data entry. The sections below follow the video step by step.</p><h3>1️⃣ The form in the demo: a supply requisition</h3><p>The video uses EEOC Form 123, a supply requisition PDF published by the US government. I picked it because it has everything a paper form usually has:</p><ul><li>A header: the requesting office, a contact, a delivery address and a suggested vendor</li><li>A table of line items: one item per row, with quantity, unit, unit price and amount</li><li>Check boxes</li><li>Signature and approval boxes</li></ul><h3>2️⃣ Importing: you confirm before anything is sent</h3><p>In DefineEditor, open the definition folder, choose File → Import Form from Documents…, and pick the documents. PDFs, Word documents and PNG or JPEG photos are all accepted. If the front and back of a form were photographed separately, select both.</p><p>Before anything is sent, a dialog lists the files that go to the AI model and the organization that pays for this request. Company forms may contain personal data, so agree only when you are allowed to share them. Without your agreement, nothing leaves your computer.</p><h3>3️⃣ The first draft: a header and its line items</h3><p>Once the documents are sent, the conversation window opens. The AI model reads the PDF and builds the draft step by step with tools the editor provides. Each step shows up in the conversation as it happens: which table it created, which field it set up, which existing form it matched.</p><p>A first draft usually has:</p><ul><li>A master table and a detail table</li><li>Field captions in English and Chinese, with data types and lengths</li><li>Drop-down choices where the document gives a fixed set of options</li><li>Relations: fields that pick a person, a department or a vendor are matched to the forms already in your definition folder</li><li>Totals: a read-only field on the master table that adds up the line items with Sum(…)</li></ul><p>On the right side of the window is a preview that draws the form from the draft. Scroll down and the detail table appears under the header. Next to it, the Fields tab lists every field together with the text it was read from in the document, and the Questions tab lists what is still open.</p><h3>4️⃣ Adjusting it in plain words</h3><p>Where the document is unclear, the AI model asks. Each question is a card with a few answers to click, and the one it suggests is marked. You can answer one by one, or use Use the Suggestions. The video takes the suggestions but changes one answer: Suggested Vendor is linked to the Supplier form instead of staying a text field.</p><p>Then the changes are typed in as a normal message. The video asks for four at once:</p><ul><li>Remove the signature boxes, since the approval workflow handles them in the system</li><li>Turn the unit into a drop-down</li><li>Make the total add up the line items</li><li>Widen the justification box so it takes the whole row</li></ul><p>After making the changes, the AI model explains each one, and points out the items the draft already handled. The preview updates after every change. One more round of answers, the draft is marked ready, and only then is Create Definitions enabled.</p><p>The AI model only proposes the draft. Whether it can become definitions is checked by DefineEditor itself. A computed field such as the total is parsed by the framework’s expression evaluator before the draft can be ready. If something is wrong, it stays on the Questions tab, and the definitions cannot be created until it is fixed.</p><h3>5️⃣ Creating the definitions and upgrading the database</h3><p>After Create Definitions, the rest is the same as an Excel import: it lists the files it will write, and writes them only after you confirm. DefineEditor then offers to upgrade the database, and in the video this creates two tables, one for the master and one for the line items.</p><p>What comes out are ordinary Polhem definition files, no different from a form created by hand or imported from Excel. You can still rearrange the fields later in the FormLayout editor (the form layout editor).</p><h3>6️⃣ Entering data on the website</h3><p>Finally, the video opens the Blazor site of the Northwind sample, where the requisition is already on the menu. The related fields, such as the offices, the people and the vendor, all pick from existing records. Add two line items and the total updates as you type. After saving, the record is opened again in read-only mode.</p><p>From one PDF to a form people can enter data into, without writing a line of code.</p><h3>7️⃣ Cost, time and limits</h3><p>Each message calls the AI model’s paid API one or more times, and the organization shown before sending pays for it. You need API credit and a credential set up first; <a href="https://github.com/polhem-dev/polhem/blob/main/docs/en/guides/document-form-drafting.md">the guide</a> explains how. The guide measured eight synthetic forms (printed, handwritten and photographed) at about US$0.25 and 80 seconds per form, with one or two replies. The actual cost depends on the length of the document and on how many questions the AI model needs to ask.</p><p>Current limits:</p><ul><li>One conversation drafts one form.</li><li>A total can only add up all of the line items. Averages, or sums over only some of the lines, cannot be expressed.</li><li>Business logic that definitions cannot express still has to be written as code, as with any other form.</li></ul><h3>✅ Wrapping up</h3><p>What this feature saves is the time spent describing a form all over again. The AI model writes the draft, but which fields to keep, which form a field relates to and how the total is calculated are all decided by you in the conversation.</p><p>If a form has a complex layout or needs a lot of custom logic, the draft is only a starting point, and there is still plenty to adjust afterward. If the fields are clear and the form is mostly used for data entry, this is a much faster way to start. The best way to find out whether it fits your forms is to try it on one you already have.</p><h3>Further reading</h3><ul><li><a href="https://github.com/polhem-dev/polhem/blob/main/docs/en/guides/document-form-drafting.md">Drafting Forms from Documents</a>: the credential setup, every part of the conversation window, and the limits</li><li><a href="https://github.com/polhem-dev/polhem">Polhem</a>: source code, documentation and samples</li></ul><p>📘 Original HackMD notes, in Traditional Chinese: <a href="https://hackmd.io/@jeff377/polhem-doc-to-form">https://hackmd.io/@jeff377/polhem-doc-to-form</a></p><p>📢 Reposting welcome, please credit the source.<br>📬 Follow my technical notes and hands-on experience:</p><p>Facebook: <a href="https://www.facebook.com/profile.php?id=61574839666569">https://www.facebook.com/profile.php?id=61574839666569</a><br>HackMD: <a href="https://hackmd.io/@jeff377">https://hackmd.io/@jeff377</a><br>GitHub: <a href="https://github.com/jeff377">https://github.com/jeff377</a><br>NuGet: <a href="https://www.nuget.org/profiles/jeff377">https://www.nuget.org/profiles/jeff377</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=440e9f8287f9" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Form Relations vs Table Relations: What’s the Difference?]]></title>
            <link>https://medium.com/@jeff377/form-relations-vs-table-relations-whats-the-difference-d7d6bab42fb9?source=rss-6d011dcf2f94------2</link>
            <guid isPermaLink="false">https://medium.com/p/d7d6bab42fb9</guid>
            <category><![CDATA[erp]]></category>
            <category><![CDATA[dotnet]]></category>
            <category><![CDATA[blazor]]></category>
            <category><![CDATA[software-architecture]]></category>
            <dc:creator><![CDATA[Jeff]]></dc:creator>
            <pubDate>Fri, 06 Nov 2026 15:32:38 GMT</pubDate>
            <atom:updated>2026-11-06T15:32:38.979Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*wlcrQfpAQ1016Fni.png" /></figure><iframe src="https://cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.youtube.com%2Fembed%2FxY_ZlEAAcoE%3Ffeature%3Doembed&amp;display_name=YouTube&amp;url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DxY_ZlEAAcoE&amp;image=https%3A%2F%2Fi.ytimg.com%2Fvi%2FxY_ZlEAAcoE%2Fhqdefault.jpg&amp;type=text%2Fhtml&amp;schema=youtube" width="854" height="480" frameborder="0" scrolling="no"><a href="https://medium.com/media/4a9bc5371c048d7f610c943f6caabdf5/href">https://medium.com/media/4a9bc5371c048d7f610c943f6caabdf5/href</a></iframe><p>The video is about 4 minutes long, with English narration and English or Traditional Chinese subtitles on YouTube. It was recorded with Polhem 1.12.1.</p><p>The previous two posts walked through the whole flow: importing definitions from Excel, then running them on the desktop, the web and phones. This one is about a single topic: how relations between forms are designed. The demo continues with the Northwind project from the Blazor Server video (<a href="https://medium.com/@jeff377/the-same-definitions-on-blazor-server-what-has-to-change-d262eb732c87">https://medium.com/@jeff377/the-same-definitions-on-blazor-server-what-has-to-change-d262eb732c87</a>) and adds an employee and a department to the order.</p><h3>1️⃣ One sentence from the user</h3><p>Ask a user what an order needs, and you often hear a sentence like this:</p><blockquote><em>Pick the salesperson, and their department comes along. If they move to another department later, this order stays with the old one.</em></blockquote><p>That sentence is the whole requirement. The first half is about the action: pick a person, and the related data comes with them. The second half is about where the record belongs: the order keeps the department at the time it was made, and does not follow the employee’s later moves.</p><h3>2️⃣ The traditional way: translate the sentence into tables</h3><p>In a typical system, a developer first translates the sentence into tables and foreign keys: orders.employee_id points to employees, and employees.dept_id points to departments. Then three things have to be written:</p><ul><li>The query: the list shows the employee and department names, so it needs a join</li><li>The lookup window: so the user can pick an employee</li><li>The handling after a pick: code that copies the code, name and department into the order once an employee is chosen</li></ul><p>The second half, “stays with the old department”, needs its own thought too. The department has to be stored on the order. If it is joined through the employee every time, the old orders change department as soon as the employee moves.</p><p>All of this is done again on every screen that uses the employee. The requirement is one sentence, but the implementation is spread across SQL, screens and code, and reading the original requirement back out of the code later is not easy.</p><h3>3️⃣ The Polhem way: forms refer to forms</h3><p>In Polhem, relations are defined on the form (FormSchema, the definition file that describes which fields a form has). A relation says “this form refers to that form”, not “this table’s foreign key points to that table’s primary key”. What the field says is: when this record is picked, bring back these fields. That is the same thing the user said.</p><p>The video first opens DefineEditor (Polhem’s definition file editor) to look at two existing forms:</p><ul><li>The Employee form’s department field refers to the Department form and brings back the department’s code, name and manager</li><li>The Department form’s manager field refers back to the Employee form</li></ul><p>Each form only describes the next level it refers to directly. When a form needs a field from further down, the framework follows the chain and builds the multi-level joins itself, so whoever writes the definition only has to think one level at a time.</p><h3>4️⃣ Writing the sentence on the order</h3><p>Next, the video opens the Order form in DefineEditor, adds an employee field, and points it at the Employee form. The relation dialog has already ticked the employee’s code and name, which are ordinary display fields.</p><p>For “their department comes along”, the employee’s department fields are ticked too and written into the order’s own department fields, marked LookupOnly (applied only when picking): they are filled in when an employee is picked, then saved along with the order.</p><p>The department field itself is read-only, because it always comes from the employee and users cannot pick it on their own. It still refers to the Department form, so the order can show the department name and be searched by department.</p><p>After saving, the Order definition looks roughly like this:</p><pre>&lt;FormField FieldName=&quot;employee_rowid&quot; Caption=&quot;Employee&quot; DbType=&quot;Guid&quot;<br>           RelationProgId=&quot;Employee&quot; ValueChangeCallback=&quot;true&quot;&gt;<br>  &lt;RelationFieldMappings&gt;<br>    &lt;FieldMapping SourceField=&quot;sys_id&quot;        DestinationField=&quot;ref_employee_id&quot; /&gt;<br>    &lt;FieldMapping SourceField=&quot;sys_name&quot;      DestinationField=&quot;ref_employee_name&quot; /&gt;<br>    &lt;FieldMapping SourceField=&quot;dept_rowid&quot;    DestinationField=&quot;dept_rowid&quot;    LookupOnly=&quot;true&quot; /&gt;<br>    &lt;FieldMapping SourceField=&quot;ref_dept_id&quot;   DestinationField=&quot;ref_dept_id&quot;   LookupOnly=&quot;true&quot; /&gt;<br>    &lt;FieldMapping SourceField=&quot;ref_dept_name&quot; DestinationField=&quot;ref_dept_name&quot; LookupOnly=&quot;true&quot; /&gt;<br>  &lt;/RelationFieldMappings&gt;<br>&lt;/FormField&gt;<br>&lt;FormField FieldName=&quot;dept_rowid&quot; Caption=&quot;Department&quot; DbType=&quot;Guid&quot;<br>           RelationProgId=&quot;Department&quot; ReadOnly=&quot;true&quot;&gt;<br>  &lt;RelationFieldMappings&gt;<br>    &lt;FieldMapping SourceField=&quot;sys_id&quot;   DestinationField=&quot;ref_dept_id&quot; /&gt;<br>    &lt;FieldMapping SourceField=&quot;sys_name&quot; DestinationField=&quot;ref_dept_name&quot; /&gt;<br>  &lt;/RelationFieldMappings&gt;<br>&lt;/FormField&gt;</pre><p>It reads like the user’s sentence: the order belongs to this employee, and to their department. A few things are worth a second look:</p><ul><li>RelationProgId=”Employee” points to the Employee form, not the employees table.</li><li>The three LookupOnly mappings only write values into the order when an employee is picked. They take no part in the joins at query time. The order’s department is read back through its own dept_rowid and the relation below it, so it is the department stored on the order, not the employee’s current one. That distinction is what makes the second half, “stays with the old department”, work.</li><li>ValueChangeCallback was ticked by the dialog automatically. The lookup window only returns the employee’s code and name, not the department, so after a pick the server reads the employee’s full record and fills the department in.</li></ul><h3>5️⃣ Sync and upgrade: no SQL, no code</h3><p>Once the definition is done, Sync in DefineEditor (synchronizing the table definition and the form layout) adds the new fields to the table definition and the layout. Then Upgrade Database adds the columns to the order table. No SQL and no code are written along the way.</p><p>Opening the order’s layout in the web preview shows the employee on the form, with the read-only department next to it.</p><h3>6️⃣ Trying it in the Blazor Server site</h3><p>Finally, the video tries it in the Blazor Server site:</p><ol><li>A new order now has an employee and a read-only department.</li><li>Pick the employee Nancy Davolio, and the department Sales East comes in with her.</li><li>Save. In the list, the order’s employee is Nancy and its department is Sales East.</li><li>In the employee form, move Nancy to Sales West.</li><li>Open the earlier order. Its department is still Sales East, the department she was in when it was made.</li><li>Create another order and pick Nancy. This time Sales West comes in.</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*GD3x3cubEXczUYbV.png" /></figure><p>Both halves of the user’s sentence show their results here.</p><h3>7️⃣ Scope</h3><p>This approach covers the everyday work on forms: creating, querying and editing records. Reports, statistics and batch jobs need SQL of any shape, and that is still written by hand in business objects. Relations have limits too: a join is always a single-column equality (foreign key to primary key), the target is a physical table, and subqueries and composite keys are not supported. The “When to Use / Not Use” and “Limitations and Design Tradeoffs” sections of the documentation (<a href="https://github.com/polhem-dev/polhem/blob/main/docs/en/definitions/formschema-data-access.md">https://github.com/polhem-dev/polhem/blob/main/docs/en/definitions/formschema-data-access.md</a>) list them.</p><h3>✅ Wrapping up</h3><p>With table relations, a developer translates the user’s words into joins, lookup windows and code that copies fields. With form relations, the user’s words are written directly as the definition. The benefit is that the requirement and the implementation line up: open the Order definition later, and you can read “pick an employee, bring back the department, keep the department with the order” straight from it, and every screen that uses it behaves the same way.</p><p>This is the approach I chose for Polhem, and it suits business systems with many forms whose fields and relations change often. If your system is mostly reports and complex queries, or you already manage your data model with an ORM, you may not need to switch. Judge it against your own project.</p><p>To try it yourself, install the templates with dotnet new install Polhem.Templates, then create a project with dotnet new polhem-blazor-server. The documentation and samples are on GitHub (<a href="https://github.com/polhem-dev/polhem">https://github.com/polhem-dev/polhem</a>).</p><h3>Further reading</h3><ul><li>FormSchema-Driven Database Access (<a href="https://github.com/polhem-dev/polhem/blob/main/docs/en/definitions/formschema-data-access.md">https://github.com/polhem-dev/polhem/blob/main/docs/en/definitions/formschema-data-access.md</a>): the formal description of form-level relations, LookupOnly and ValueChangeCallback</li><li>The Same Definitions on Blazor Server: What Has to Change? (<a href="https://medium.com/@jeff377/the-same-definitions-on-blazor-server-what-has-to-change-d262eb732c87">https://medium.com/@jeff377/the-same-definitions-on-blazor-server-what-has-to-change-d262eb732c87</a>): where the Northwind project in this video comes from</li></ul><p>📘 Original HackMD notes, in Traditional Chinese: <a href="https://hackmd.io/@jeff377/polhem-form-relations">https://hackmd.io/@jeff377/polhem-form-relations</a></p><p>📢 Reposting welcome, please credit the source.<br>📬 Follow my technical notes and hands-on experience:</p><p>Facebook: <a href="https://www.facebook.com/profile.php?id=61574839666569">https://www.facebook.com/profile.php?id=61574839666569</a><br>HackMD: <a href="https://hackmd.io/@jeff377">https://hackmd.io/@jeff377</a><br>GitHub: <a href="https://github.com/jeff377">https://github.com/jeff377</a><br>NuGet: <a href="https://www.nuget.org/profiles/jeff377">https://www.nuget.org/profiles/jeff377</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d7d6bab42fb9" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[OAuth2 + OIDC Sign-In Across Platforms: One .NET Library for Every Provider]]></title>
            <link>https://medium.com/@jeff377/oauth2-oidc-sign-in-across-platforms-one-net-library-for-every-provider-987035419294?source=rss-6d011dcf2f94------2</link>
            <guid isPermaLink="false">https://medium.com/p/987035419294</guid>
            <category><![CDATA[csharp]]></category>
            <category><![CDATA[openid-connect]]></category>
            <category><![CDATA[aspnetcore]]></category>
            <category><![CDATA[dotnet]]></category>
            <category><![CDATA[oauth2]]></category>
            <dc:creator><![CDATA[Jeff]]></dc:creator>
            <pubDate>Fri, 06 Nov 2026 00:54:52 GMT</pubDate>
            <atom:updated>2026-11-06T00:54:52.795Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*rHa9ved-PkjfV8VF.png" /></figure><p>Polhem.OAuth2 (<a href="https://github.com/polhem-dev/polhem-oauth2">https://github.com/polhem-dev/polhem-oauth2</a>) now supports OpenID Connect, the sign-in standard built on top of OAuth2. Versions 1.4.0 and 1.5.0 added:</p><ul><li>Apple accounts</li><li>GitHub accounts</li><li>Custom OpenID Connect providers, such as Keycloak, GitLab and AWS Cognito</li><li>Desktop apps signing in through a back end</li><li>One rule for apps with a back end: the back end does the sign-in</li></ul><p>The previous post, One OAuth2 Library for Every Kind of .NET App (<a href="https://medium.com/@jeff377/one-oauth2-library-for-every-kind-of-net-app-678c3e03bb93">https://medium.com/@jeff377/one-oauth2-library-for-every-kind-of-net-app-678c3e03bb93</a>), introduced the library. It lets desktop apps, .NET MAUI, ASP.NET Core and older Web Forms sites add third-party sign-in the same way, and at the time it supported Google, Facebook, LINE, Microsoft Entra ID, Auth0 and Okta. This post covers what is new.</p><h3>1️⃣ Supported platforms and accounts</h3><p>First, the kinds of applications supported as of 1.5.0:</p><ul><li>Desktop and console apps: open the system browser and receive the callback on 127.0.0.1 on the local machine. Works on Windows, macOS and Linux. They can talk to the provider directly, or go through a back end when there is one.</li><li>.NET MAUI apps on Android, iOS and Mac Catalyst: sign in through WebAuthenticator, either directly with the provider or through your own back end.</li><li>ASP.NET Core websites.</li><li>Web Forms and MVC sites on ASP.NET (System.Web).</li><li>Other server frameworks: the core OAuth2Client splits sign-in into two steps, creating the authorization URL and completing the sign-in, and does not depend on any HTTP framework.</li></ul><p>There are three packages:</p><ul><li>Polhem.OAuth2 (netstandard2.0, net8.0, net10.0): the providers; desktop, console and .NET MAUI apps; other server frameworks</li><li>Polhem.OAuth2.AspNetCore (net10.0): ASP.NET Core</li><li>Polhem.OAuth2.AspNet (net472): Web Forms and MVC on System.Web</li></ul><p>The supported accounts, and how each one works in desktop and console apps and in .NET MAUI. All of them work on websites:</p><ul><li>Google (OAuth2 + OIDC): desktop directly or through the back end; .NET MAUI directly on iOS and Mac Catalyst, through the back end on Android</li><li>Facebook (OAuth2): desktop and .NET MAUI, directly or through the back end</li><li>LINE (OAuth2, email taken from the ID token): desktop directly or through the back end; .NET MAUI directly on iOS and Mac Catalyst, through the back end on Android</li><li>Microsoft Entra ID, Auth0 and Okta (OAuth2 + OIDC): desktop and .NET MAUI, directly or through the back end</li><li>GitHub (OAuth2, new in 1.4.0): desktop directly or through the back end; .NET MAUI only through the back end</li><li>Apple (OAuth2 + OIDC, new in 1.4.0): desktop and .NET MAUI only through the back end</li><li>Other OpenID Connect providers (OAuth2 + OIDC, new in 1.4.0), such as Keycloak and GitLab: desktop directly if the provider allows sign-in without a client secret, otherwise through the back end; .NET MAUI directly or through the back end</li></ul><p>An “OAuth2 + OIDC” provider also returns an ID token, a signed document that says who the user is and which application it was issued to. The library checks it, or reads the user from it. An “OAuth2” provider has its user data fetched from its own API instead.</p><p>Whichever provider you use, the result has the same shape: the user ID, name and email, plus the access, refresh and ID tokens.</p><p>“Through the back end” is the approach from the previous post: the app signs in through its own ASP.NET Core back end, the provider’s tokens stay on the back end, and the app only gets a one-time code to exchange for the user’s information. Starting with 1.5.0, desktop apps can sign in this way too. Section 5 has the details.</p><p>GitHub and Apple can only go through the back end on mobile because both require a client secret, the password the provider issues to an application, every time a code is exchanged for tokens. An app installed on a phone can be taken apart, and a client secret inside it can be extracted, so the secret has to stay on the back end, which signs in on the app’s behalf. Apple adds one more restriction: after sign-in it only redirects to an https URL with a domain name, never to the 127.0.0.1 address a desktop app listens on, so desktop apps have to go through the back end as well.</p><h3>2️⃣ Any OpenID Connect provider</h3><p>Keycloak, GitLab, AWS Cognito and Authentik all follow OpenID Connect, and they mostly differ only in their endpoint URLs. Writing a class for each one is not worth it. So 1.4.0 added a generic OidcOAuth2Options, which reads the endpoints from the provider’s discovery document (the configuration that OpenID Connect places at /.well-known/openid-configuration):</p><pre>var keycloak = await OidcOAuth2Options.FromDiscoveryAsync(&quot;https://sso.example.com/realms/example&quot;);<br>keycloak.ProviderName = &quot;Keycloak&quot;;<br>keycloak.ClientId = &quot;your-client-id&quot;;<br>keycloak.ClientSecret = &quot;your-client-secret&quot;;<br>keycloak.RedirectUri = &quot;https://localhost:7032/auth/callback&quot;;<br>builder.Services.AddOAuth2Client(&quot;Keycloak&quot;, keycloak);</pre><p>Once you have the options, they work like any other provider, and the controller from the previous post does not change. A few design considerations:</p><ul><li>Discovery is read once, at startup. Reading the document is asynchronous, so it is a separate factory method, and the options themselves stay synchronous. That way the configuration is checked when the client is created, instead of failing the first time a user clicks sign in.</li><li>ProviderName has no default. Users are identified by provider name plus user ID, and two providers can issue the same ID to different people. With a default name, an application that adds a second provider and forgets to name it would treat users from both as the same person.</li><li>The discovery document is checked when it is read: the issuer must equal the URL passed in, the endpoints must be https, and if the document lists supported PKCE methods, S256 must be among them.</li><li>A provider without a userinfo endpoint still works. The user is read from the ID token instead.</li></ul><p>Keycloak 26.4 and GitLab.com have both been signed in to with real accounts. For Google and Okta, the users returned through the generic options are the same as through their dedicated options.</p><p>When a website connects to several providers, watch out for mix-up attacks: a malicious or compromised provider steers the user to sign in at another provider, then tries to get the authorization code from that sign-in. What stops it is the client secret and PKCE the other provider requires when exchanging the code, so the code is useless in the attacker’s hands. So, where the provider allows it, give every website client a client secret, keep PKCE on (the default), and only connect to providers you trust.</p><h3>3️⃣ Sign in with Apple</h3><p>Apple is also an OpenID Connect provider, but its client secret is not a fixed string. It is a JWT signed with the private key file (.p8) that Apple gives you. The library signs it for you and re-signs it before it expires, so you only hand it the private key:</p><pre>builder.Services.AddOAuth2Client(&quot;Apple&quot;, new AppleOAuth2Options<br>{<br>    ClientId = &quot;com.example.web&quot;,           // Services ID<br>    TeamId = &quot;your-team-id&quot;,<br>    KeyId = &quot;your-key-id&quot;,<br>    PrivateKey = File.ReadAllText(keyPath),  // contents of the .p8 file; keep it out of source control<br>    RedirectUri = &quot;https://www.example.com/auth/callback&quot;<br>});</pre><p>A few things to keep in mind:</p><ul><li>The callback URL must be https with a domain name. During development, use a public URL such as a tunnel.</li><li>Apple returns to the callback URL with a form POST, so the callback endpoint has to accept both GET and POST.</li><li>The user’s name is only given once, the first time the user authorizes your app, so store it then.</li><li>Desktop and mobile apps have to sign in through the back end.</li></ul><p>How to write the callback endpoint and what to register in Apple’s developer portal are covered in the repo’s Sign in with Apple document (<a href="https://github.com/polhem-dev/polhem-oauth2/blob/main/docs/en/providers/apple.md">https://github.com/polhem-dev/polhem-oauth2/blob/main/docs/en/providers/apple.md</a>).</p><h3>4️⃣ GitHub</h3><p>GitHub user sign-in is OAuth2 only, without OpenID Connect, so it has its own GitHubOAuth2Options. It works with both GitHub Apps and OAuth Apps.</p><ul><li>UserId is the numeric account ID. A user’s login changes when they rename their account, and the old name can even be registered by someone else, but the numeric ID never changes.</li><li>If the user has no public email, the library looks up their primary, verified email. If there is none, the email is null and sign-in still succeeds.</li><li>When GitHub exchanges a code for tokens, some errors come back with HTTP 200. The library treats these as failures and includes GitHub’s error code, rather than just reporting that there was no access token.</li></ul><p>GitHub requires the client secret on every exchange, so a desktop app that signs in directly has to carry the secret inside the app. With a back end, signing in through it avoids that. A .NET MAUI app can only sign in through the back end.</p><h3>5️⃣ With a back end, the back end signs in</h3><p>An app without its own back end signs in directly and uses the result itself. An app with a back end is different: the back end needs to know who signed in, so it can map them to its own account and issue a session.</p><p>The obvious approach is for the front end to sign in to the provider and hand the access token to the back end, which calls the provider’s userinfo endpoint with it. That is not safe enough. Every other application the user has signed in to also holds a valid token for this user. If one of those applications sends that token to your back end, the userinfo endpoint returns the same user, and the application can sign in to your back end as that user. This is called token substitution.</p><p>In 1.4.0, GetUserInfoAsync(accessToken) dealt with this: it first asked the provider who the token was issued to, and returned the user only if it was your own client ID. 1.5.0 removed it and replaced it with one rule: when there is a back end, the back end always does the sign-in, whatever the provider, OpenID Connect providers included.</p><ul><li>Web: the back end runs the web sign-in and gives the browser a cookie session</li><li>.NET MAUI on Android, iOS and Mac Catalyst: through the back end with WebAuthenticator</li><li>Desktop and console apps, and .NET MAUI on Windows: through the back end with LoopbackRelayClient, new in 1.5.0</li></ul><p>This way the back end confirms the user with the provider itself and does not have to trust anything the front end sends. The provider’s tokens and the client secret also stay on the back end.</p><p>The relay works roughly like this:</p><ol><li>The app generates a PKCE code verifier and opens the back end’s sign-in URL in the system browser, passing its own callback URL and the code challenge.</li><li>The back end redirects the browser to the provider’s authorization URL using its own web client, so nothing extra has to be registered with the provider for the app.</li><li>After the user signs in, the provider redirects back to the back end, which exchanges the code for tokens and the user’s information.</li><li>The back end stores the user’s information under a one-time code and redirects to the app’s callback URL.</li><li>The app sends the code and the verifier to the back end and gets the user back. Even if another program intercepts the code, it is useless without the verifier.</li></ol><p>In a desktop app:</p><pre>var client = new LoopbackRelayClient(&quot;http://127.0.0.1:0/callback&quot;);<br>RelaySignInResult result = await client.SignInAsync((redirectUri, codeChallenge) =&gt; new Uri(<br>    $&quot;https://api.example.com/auth/app/GitHub?redirect_uri={Uri.EscapeDataString(redirectUri.AbsoluteUri)}&amp;code_challenge={codeChallenge}&quot;));</pre><pre>if (result.IsSuccess)<br>{<br>    // Send result.Code and result.CodeVerifier to the back end, which issues its own session.<br>}</pre><p>On the back end, register the loopback callback URL without a port, and the desktop app can listen on any free port each time:</p><pre>builder.Services.AddOAuth2AppRelay(options =&gt;<br>{<br>    options.AppRedirectUris.Add(&quot;com.example.app:/relay&quot;);    // mobile app<br>    options.AppRedirectUris.Add(&quot;http://127.0.0.1/callback&quot;); // desktop app, any port<br>});</pre><ul><li>Only 127.0.0.1 and [::1] are accepted, not localhost, because localhost can resolve to another address.</li><li>Any web page in the browser can send requests to a loopback address, so LoopbackRelayClient adds a state to the callback URL and only accepts a redirect that carries it.</li><li>Other programs on the machine can also listen on loopback ports. If your app can always use the same port, register it with that port.</li><li>The URL that starts sign-in and the endpoint that redeems the code are a contract between your app and your own back end. The library does not prescribe their form.</li></ul><p>GitHub and Facebook do not issue ID tokens, so an app with a back end used to have no option but to send the access token from the front end. Both have now been signed in to with real accounts through the back-end relay, and the console sample runs exactly this flow with — back-end.</p><h3>6️⃣ Before you upgrade</h3><p>1.4.0 and 1.5.0 have three breaking changes between them. The two in 1.4.0 are both for security, and they affect apps that use Google, Auth0, Okta or Microsoft Entra ID.</p><p>The ID token returned by sign-in is now checked. It must be issued to this client (its audience includes the client ID), and its subject must match the user’s information. For Google and Auth0, the issuer is checked as well. These are the checks the OpenID Connect Core specification requires. What gets blocked is a token issued to another client, or one whose user does not match, both of which used to pass. As long as ClientId is set correctly, your app does not need to change. After the checks were added, all four providers were signed in to again with real accounts, and none were wrongly rejected.</p><p>Unverified emails are no longer returned. When the provider marks email_verified as false, UserInfo.Email is null. If an app maps sign-ins to existing accounts by email, someone could take over an account with an email they never verified, and this change is there to stop that. Identify users by provider name plus UserId instead.</p><p>1.5.0 removes access token verification. GetUserInfoAsync(accessToken) and AcceptedClientIds are gone, and code that uses them will no longer compile. To migrate, move sign-in to the back end, as described in section 5.</p><h3>✅ Wrapping up</h3><p>Install or upgrade the core package:</p><pre>dotnet add package Polhem.OAuth2</pre><p>The “Supported accounts” table in the README (<a href="https://github.com/polhem-dev/polhem-oauth2">https://github.com/polhem-dev/polhem-oauth2</a>) links to a document for each provider, covering what to register with the provider and the results of real sign-in tests.</p><p>The trade-offs behind generic OpenID Connect, Apple, and back-end sign-in are recorded in the repo as ADR-008, ADR-009 and ADR-011. An ADR (Architecture Decision Record) is a document that records a design decision and the reasons for it.</p><p>The scope of the library is the same as in the previous post: it handles signing in and getting the user’s information and tokens, and does not manage accounts or permissions after sign-in. If you only have a website, ASP.NET Core’s built-in authentication is enough, and you may not need to switch. The library fits best when you have desktop, mobile and web apps at the same time and want to connect Apple, GitHub or a self-hosted Keycloak the same way in all of them. Feedback, issues and pull requests are welcome.</p><h3>Further reading</h3><ul><li>OpenID Connect Core 1.0: <a href="https://openid.net/specs/openid-connect-core-1_0.html">https://openid.net/specs/openid-connect-core-1_0.html</a>, on checking the ID token’s audience, issuer and subject</li><li>RFC 9700, OAuth 2.0 Security Best Current Practice: <a href="https://datatracker.ietf.org/doc/html/rfc9700">https://datatracker.ietf.org/doc/html/rfc9700</a>, on mix-up attacks and PKCE</li></ul><p>📘 Original HackMD notes, in Traditional Chinese: <a href="https://hackmd.io/@jeff377/polhem-oauth2-oidc">https://hackmd.io/@jeff377/polhem-oauth2-oidc</a></p><p>📢 Reposting welcome, please credit the source.<br>📬 Follow my technical notes and hands-on experience:</p><p>Facebook: <a href="https://www.facebook.com/profile.php?id=61574839666569">https://www.facebook.com/profile.php?id=61574839666569</a><br>HackMD: <a href="https://hackmd.io/@jeff377">https://hackmd.io/@jeff377</a><br>GitHub: <a href="https://github.com/jeff377">https://github.com/jeff377</a><br>NuGet: <a href="https://www.nuget.org/profiles/jeff377">https://www.nuget.org/profiles/jeff377</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=987035419294" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The Same Definitions on Blazor Server: What Has to Change?]]></title>
            <link>https://medium.com/@jeff377/the-same-definitions-on-blazor-server-what-has-to-change-d262eb732c87?source=rss-6d011dcf2f94------2</link>
            <guid isPermaLink="false">https://medium.com/p/d262eb732c87</guid>
            <category><![CDATA[open-source]]></category>
            <category><![CDATA[dotnet]]></category>
            <category><![CDATA[erp]]></category>
            <category><![CDATA[software-architecture]]></category>
            <category><![CDATA[blazor]]></category>
            <dc:creator><![CDATA[Jeff]]></dc:creator>
            <pubDate>Thu, 29 Oct 2026 06:56:15 GMT</pubDate>
            <atom:updated>2026-10-30T06:40:47.915Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*Be4zwClYCvy7N5PU.png" /></figure><iframe src="https://cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.youtube.com%2Fembed%2FHwQXMhrWtKM%3Ffeature%3Doembed&amp;display_name=YouTube&amp;url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DHwQXMhrWtKM&amp;image=https%3A%2F%2Fi.ytimg.com%2Fvi%2FHwQXMhrWtKM%2Fhqdefault.jpg&amp;type=text%2Fhtml&amp;schema=youtube" width="854" height="480" frameborder="0" scrolling="no"><a href="https://medium.com/media/160821aefe481a74846c81538881650b/href">https://medium.com/media/160821aefe481a74846c81538881650b/href</a></iframe><ul><li>Full version: <a href="https://youtu.be/HwQXMhrWtKM">https://youtu.be/HwQXMhrWtKM</a> (about 7 minutes)</li><li>Short version: <a href="https://youtu.be/ek5rZvSzMfI">https://youtu.be/ek5rZvSzMfI</a> (about 2.5 minutes)</li></ul><p>The video has English narration, with English and Traditional Chinese subtitles on YouTube. It was recorded with Polhem 1.11.0.</p><p>The previous post, Can a Form Be Described Only Once? (<a href="https://medium.com/@jeff377/can-a-form-be-described-only-once-2fa92c7db815">https://medium.com/@jeff377/can-a-form-be-described-only-once-2fa92c7db815</a>), was a guide to the Avalonia version: one server plus four front ends for the desktop, the web, iOS and Android. This time it is Blazor Server, with the same Northwind sample and the same six Excel workbooks, and the screens are now rendered by the website on the server.</p><p>The Excel import, the division of labor among the definition files and the three databases are the same in both videos. The previous post covers them, so they only get a brief mention here. The rest of this post is about what is different once you switch to Blazor Server.</p><h3>1️⃣ One project: the website is the server</h3><p>In VS Code, create a new .NET project. Polhem has two templates, and this time the choice is “Polhem App (Blazor Server)”. The generated solution has a single project, the Blazor Server website, next to a Define folder for the definition files and an Excel folder for the workbooks.</p><p>The Avalonia template generates a server plus desktop, web, iOS and Android front ends, and the front ends call the server over JSON-RPC. The Blazor Server template has only one project because the back end runs inside the website. Program.cs has three calls: one hosts the back end in the website, one registers the Blazor form screens, and one sets up the shell (the sign-in screen and the menu). When a page calls the back end, the call stays in the same process and never crosses the network.</p><p>Calls within the same process are treated as trusted local calls. Forms still check the signed-in user’s permissions, but some system operations open only to local callers (reading any definition, for example) are reachable from pages. The template’s Program.cs has a comment about this: in pages you add yourself, do not pass values sent by the browser straight into these calls.</p><p>If you later want Avalonia front ends or JavaScript clients to connect as well, add a JSON-RPC endpoint to the website. Calls from those clients are checked under the rules for remote clients.</p><h3>2️⃣ Database and import: same as the previous post</h3><p>The next two steps are the same as in the Avalonia version, and the video spends only a little over a minute on them:</p><ul><li>Run the VS Code task “Polhem: Initialize database” to create the three databases, common, company and log, along with the framework tables and an administrator account.</li><li>In DefineEditor (Polhem’s definition file editor), import the six workbooks in a batch. The database is upgraded after each one, and the business tables are created along the way.</li></ul><p>Why there are three databases, what the workbooks describe and how the definition files divide the work after import are explained in sections 2 and 3 of the previous post.</p><h3>3️⃣ Running: every screen is derived from the definitions</h3><p>Press F5, and the website starts and opens a browser. Sign in with the administrator created earlier, and the menu has two groups of forms, master data and transactions.</p><p>The video enters categories, suppliers, customers, shippers and products in turn, then opens an order: pick a product on a detail line, enter a quantity and a unit price, and the amount is calculated. Saving without a customer is blocked by a rule, and after picking a customer the save succeeds. The flow is the same as in the Avalonia version. The difference is that every screen this time is drawn by Blazor components from the definitions. The project has no Razor page for any of its forms.</p><p>The sign-in state belongs to the browser tab: reloading or opening a new tab goes back to the sign-in screen. The interface language is chosen on the sign-in screen and applied after signing in.</p><h3>4️⃣ Changing the layout: no sign-out, no restart</h3><p>This is the main point of the video. After the system has been in use for a while, users report that the order’s notes field is a single line and too short.</p><p>In DefineEditor, open the order’s layout (FormLayout), select the notes field and click the globe icon on the toolbar, and a preview opens in the browser. The preview uses the same Blazor screens as the website, so what the preview shows is what users will see. The video puts DefineEditor and the preview side by side and makes three changes:</p><ul><li>The control changes from a single-line text box to a multi-line memo box</li><li>The field spans two columns and is three rows tall</li><li>The notes field is dragged to the end of the form</li></ul><p>The preview follows each change immediately, before anything is saved. Once it looks right, press ⌘S to save.</p><p>Back on the website, in the same tab, there is no sign-out and no restart. Open the customer form first, then go back to orders and click New: the notes field is now the last row, a multi-line input across the full width.</p><p>This works because the definitions are cached, and saving invalidates the matching cache entry. The website reads the layout when a form is opened, so it gets the new one. The word to watch is “opened”: an order form that is already open does not refresh itself, which is why the video switches to another form and back. In the earlier Avalonia video, changing the definitions meant signing out and back in. This time even that step is gone.</p><h3>5️⃣ One layout, from wide screens to phones</h3><p>The last part is RWD (responsive web design, where the layout adapts to the window width). The layout definition only says how the fields are arranged and how many columns each one spans. There is no separate version for phones.</p><p>The video narrows the browser step by step:</p><ul><li>It starts with two columns, and the fields shrink as the window gets narrower</li><li>At phone width, the form becomes a single column and the left-hand menu collapses into a button</li><li>Details are no longer edited directly in a grid. A button opens a form that edits one line at a time</li><li>The menu slides in from the side and closes automatically once a form is chosen</li></ul><p>At the end the browser is at phone width, and the same website still works. On narrow screens the list grid runs past the right edge and scrolls horizontally.</p><h3>6️⃣ When to choose Blazor Server</h3><p>Both templates read the same definitions, so the choice comes down to deployment and how the system is used.</p><p>Blazor Server means one project and one website to deploy. Users only need a browser, and layout changes need no redeploying. The cost is that every user keeps a connection to the server while working and the screen state lives on the server, so an unstable network hurts the experience, and there is no offline use.</p><p>If you need native mobile apps or desktop programs, or want the front end deployed separately from the server, the Avalonia template fits better. The two can also coexist: add a JSON-RPC endpoint to the Blazor Server website, and Avalonia front ends can connect to the same back end.</p><p>What the video does not show is the same as last time. Logic the definitions cannot express still goes into business objects, reports and batch jobs do not go through the definitions, and the framework has permissions, auditing and transport encryption that the video does not demonstrate.</p><h3>✅ Wrapping up</h3><p>This time only the front-end technology changed, and not a single line of the definitions did: the same workbooks, once imported, run on Blazor Server. The definitions only describe which fields a form has and how they are arranged, without tying themselves to how the screens are drawn. Whatever technology the front end uses, it draws its screens from the definitions.</p><p>The Blazor Server version adds one convenience: after a layout change, users see it the next time they open the form, with no redeploying and no signing in again. If your system is used mainly in the browser and has many forms that change often, this combination is worth a try. If you need offline use or native apps, the Avalonia version fits better.</p><p>Try it without installing anything: <a href="https://polhem-northwind.onrender.com/">Blazor Server</a> or <a href="https://polhem-northwind.onrender.com/web/">Avalonia WebAssembly</a>. Sign in with demo / demo, or demo-ro / demo for the read-only account. It runs on a free host, so the first visit after a quiet spell can take about a minute, and the data resets when the service restarts.</p><p>To try it yourself, install the templates with dotnet new install Polhem.Templates, then create a project with dotnet new polhem-blazor-server. The documentation and samples are on GitHub (<a href="https://github.com/polhem-dev/polhem">https://github.com/polhem-dev/polhem</a>).</p><p>📘 Original HackMD notes, in Traditional Chinese: <a href="https://hackmd.io/@jeff377/polhem-blazor-server">https://hackmd.io/@jeff377/polhem-blazor-server</a></p><p>📢 Reposting welcome, please credit the source.<br>📬 Follow my technical notes and hands-on experience:</p><p>Facebook: <a href="https://www.facebook.com/profile.php?id=61574839666569">https://www.facebook.com/profile.php?id=61574839666569</a><br>HackMD: <a href="https://hackmd.io/@jeff377">https://hackmd.io/@jeff377</a><br>GitHub: <a href="https://github.com/jeff377">https://github.com/jeff377</a><br>NuGet: <a href="https://www.nuget.org/profiles/jeff377">https://www.nuget.org/profiles/jeff377</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d262eb732c87" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Can a Form Be Described Only Once?]]></title>
            <link>https://medium.com/@jeff377/can-a-form-be-described-only-once-2fa92c7db815?source=rss-6d011dcf2f94------2</link>
            <guid isPermaLink="false">https://medium.com/p/2fa92c7db815</guid>
            <category><![CDATA[open-source]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[erp]]></category>
            <category><![CDATA[software-architecture]]></category>
            <category><![CDATA[dotnet]]></category>
            <dc:creator><![CDATA[Jeff]]></dc:creator>
            <pubDate>Sat, 24 Oct 2026 09:01:48 GMT</pubDate>
            <atom:updated>2026-10-30T06:41:21.586Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*RMCjC3hFOFB0CvH8.png" /></figure><iframe src="https://cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.youtube.com%2Fembed%2F5WjUTwoPyGw%3Ffeature%3Doembed&amp;display_name=YouTube&amp;url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3D5WjUTwoPyGw&amp;image=https%3A%2F%2Fi.ytimg.com%2Fvi%2F5WjUTwoPyGw%2Fhqdefault.jpg&amp;type=text%2Fhtml&amp;schema=youtube" width="854" height="480" frameborder="0" scrolling="no"><a href="https://medium.com/media/970736084272fa3fcb34516e3641a387/href">https://medium.com/media/970736084272fa3fcb34516e3641a387/href</a></iframe><ul><li>Full version: <a href="https://youtu.be/5WjUTwoPyGw">https://youtu.be/5WjUTwoPyGw</a> (about 10 minutes)</li><li>Short version: <a href="https://youtu.be/OAlAgAuGdKE">https://youtu.be/OAlAgAuGdKE</a> (about 3 minutes)</li></ul><p>The video has English narration, with English and Traditional Chinese subtitles on YouTube.</p><p>This year I wrote a thirty-post series for the iThome Ironman contest, <a href="https://medium.com/@jeff377/erp-architects-notes-designing-a-definition-driven-framework-series-index-7753228c4d33">ERP Architect’s Notes: Designing a Definition-Driven Framework</a>. It covers the mechanisms and trade-offs of definition-driven design, and the framework at the time was <a href="https://github.com/jeff377/bee-library">Bee.NET</a>. After the series ended, Polhem took over from Bee.NET, and the packages moved from Bee.* to Polhem.*. The definition-driven mechanisms carried over, the framework itself went through a major refactoring, and it gained a project template and Excel import. Bee.NET is no longer updated.</p><p><a href="https://github.com/polhem-dev/polhem">Polhem</a> is an open-source .NET enterprise application framework under the MIT license. The source is on GitHub and the packages are on NuGet. The front end uses <a href="https://avaloniaui.net/">Avalonia</a>, so the same UI code runs on the desktop, in the browser, and on iOS and Android.</p><p>The thirty posts are almost all text. This time I recorded a video that walks through the process: using Northwind as the example, it starts from an empty project, imports a few Excel workbooks, and the system runs. When the requirements change, you change the definitions, and the system follows. No CRUD code and no SQL are written along the way. The sections below follow the order of the video and explain the design behind each part.</p><h3>1️⃣ Opening: why is one field written so many times?</h3><p>In a business system, a field is only a few facts: its name, its type, whether it is required. Yet those facts are restated in the entity, the migration, the DTOs, the validation, the API, the form, the list and the translations. Add a field, and every one of those places has to change, and has to change consistently.</p><p>Better tools make each place quicker to write, but they do not reduce the number of places. So the question I care about is where the source lives: in the code, or in the definitions?</p><p>Polhem chooses the definitions. Each form is described once, as data, and the tables, the CRUD SQL, the validation rules and the screens are derived from that description. The same description runs on SQL Server, PostgreSQL, MySQL, Oracle and SQLite, and switching databases is a matter of configuration. The front end reads the definitions at run time, so changing a definition needs no recompiling and no redeploying.</p><p>The description does not have to be written as code either. The video uses six Excel workbooks prepared in advance: categories, suppliers, customers, shippers, products and orders. Each row is one field.</p><h3>2️⃣ Creating the project and preparing the database</h3><p>In VS Code, create a new .NET project and pick “Polhem App (Avalonia)” from the template list, with the default SQL Server database. The generated project already has a server, a desktop front end and a Define folder for the definition files, and the Polhem packages and the SQL Server driver are already referenced.</p><p>Next, run the VS Code task “Polhem: Initialize database”. It creates three databases, common, company and log, along with the tables the framework needs and an administrator account. The video looks at SQL Server before and after, so the difference is easy to see.</p><p>The three databases keep the framework’s own data (sign-in state, cache notifications) apart from each company’s business data, with the audit log stored separately again. When one application serves several companies, each company’s business data stays isolated while the framework data is shared.</p><h3>3️⃣ Importing Excel: the workbook is the specification</h3><p>This is the longest part of the video. Before importing, it opens the orders workbook to show what it describes:</p><ul><li>The field name and data type; the type decides the column type in the database</li><li>The maximum length of text fields</li><li>The input control, for example a drop-down list for the status</li><li>The related form: the customer field points to the Customer form, so after import the customer code and name are filled in automatically and the customer can be picked on screen</li><li>The amount formula: quantity times unit price, less the discount</li><li>A separate sheet that lists the rules checked before saving</li></ul><p>Then DefineEditor (Polhem’s definition file editor) imports the six workbooks in a batch, upgrading the database after each one. When it finishes, each form has its own set of definition files, and the business tables have been created.</p><p>Excel is only the input. The definition files produced by the import are no different from ones written by hand. Here is what each of them does:</p><ul><li>FormSchema: describes the form’s fields, relationships, computed fields and rules. The other definitions are derived from it, and the CRUD SQL is built from it.</li><li>TableSchema: describes the structure of the physical tables. It is derived from FormSchema and used to create and upgrade the tables.</li><li>FormLayout: describes how the fields are arranged. It is derived from FormSchema, and each front end draws its screens from it.</li><li>Language files: hold field captions in each language, the text shown on screen.</li></ul><p>FormSchema describes a form, not a table. An order has a master and details, and the customer field relates to another form. All of that is written at the form level, and the framework generates the SQL from it.</p><h3>4️⃣ Running: a system with no form code</h3><p>Press F5, and the server and the desktop front end start together. Sign in with the administrator created earlier, and the menu already has two groups of forms, master data and transactions, arranged exactly like the program tree in DefineEditor.</p><p>The video enters a few master records, then opens an order: pick a product on a detail line, enter a quantity and a unit price, and the amount is calculated. Saving without a customer is blocked, and the rule that blocks it is the one from the workbook’s rules sheet. Pick a customer, the code and name come along, and the second save succeeds.</p><p>The calculation and the save check both work, yet no code was written for this form. Data moves between the layers as a DataSet, so no form needs its own type or DTO. The computed fields and rules are declared in the definitions, and the framework executes them.</p><h3>5️⃣ Iterating: when requirements change, change the definitions</h3><p>This is the part I most want people to see. Once a system is live, requirements change: sales wants to grade customers, and orders need a quantity limit.</p><p>This time the change is made directly in DefineEditor. The customer form gets a “grade” field: text, ten characters long, B as the default, with choices A, B and C in a drop-down list. After saving, syncing the form adds the field to the TableSchema, the layout and the list. Upgrading only this form’s tables gives the customer table a grade column. The order form gets one more rule: a detail line cannot exceed one hundred units.</p><p>Back in the front end, sign out and sign back in, with no restart needed. The customer list has a grade column, and existing customers have the default value B. The edit screen has the drop-down list. An order with a quantity of two hundred is blocked by the new rule when saved.</p><p>Two mechanisms make this work. The database upgrade compares the definitions with the existing tables and adds only what is missing, leaving existing data alone. The definitions are cached, and a change invalidates the cache, so the front end reads the new definitions the next time.</p><h3>6️⃣ Visual fine-tuning and multiple front ends</h3><p>The video ends with two short parts.</p><p>The first adjusts details in DefineEditor: the contact name becomes required, the layout changes from two columns to three, and “grade” gets a Chinese caption, with the preview updating immediately. After signing in again, the three-column layout and the required check both take effect, and users with the Chinese interface see the new caption.</p><p>The second goes back to the folders created with the project. Besides the desktop, the same project has web, iOS and Android front ends, and one task starts the server and all four front ends together. All four show the same menu and the same orders, because they read the same definitions and talk to the same server.</p><p>FormLayout only describes which fields there are and how they are arranged, without tying itself to a UI technology, and each front end draws its screens from it. Front-end technology turns over every few years, and the definitions can stay in use.</p><h3>7️⃣ What the video does not show</h3><p>The demo picks a flow that the definitions can express completely. So that nobody concludes every form can be finished this way, a few notes:</p><ul><li>Logic the definitions cannot express still needs code. Excel does not describe code. In the framework’s complete Northwind sample, the order form is bound to a custom business object that handles the order total and the detail checks; the video shows the definitions-only version. The definitions handle what is common, and special business logic overrides the business object’s extension points.</li><li>Reports and batch jobs do not go through the definitions. CRUD is driven by the definitions, while reports and batch jobs are implemented by the business objects themselves.</li><li>The framework has permissions, auditing and transport encryption, but the video does not demonstrate them.</li></ul><h3>✅ Conclusion</h3><p>The flow in the video comes down to one sentence: describe the form, and leave the rest to the framework. It works because the definitions are the single source of truth. The database, the SQL, the screens and the rules are all derived from them, so when a definition changes, every layer follows.</p><p>This approach fits systems with many forms of a regular shape that need long-term maintenance and customization, such as ERP. If a system has few forms and every screen is heavily customized, writing the code directly may be simpler. You do not need Polhem either: you can take the idea of making the definitions the source and build it with the tools you already know.</p><p>Try it without installing anything: <a href="https://polhem-northwind.onrender.com/">Blazor Server</a> or <a href="https://polhem-northwind.onrender.com/web/">Avalonia WebAssembly</a>. Sign in with demo / demo, or demo-ro / demo for the read-only account. It runs on a free host, so the first visit after a quiet spell can take about a minute, and the data resets when the service restarts.</p><p>To try it yourself, install the template with dotnet new install Polhem.Templates. The documentation and samples are on <a href="https://github.com/polhem-dev/polhem">GitHub</a>.</p><p>📘 Original HackMD notes, in Traditional Chinese: <a href="https://hackmd.io/@jeff377/polhem-video-guide">https://hackmd.io/@jeff377/polhem-video-guide</a></p><p>📢 Reposting welcome, please credit the source.<br>📬 Follow my technical notes and hands-on experience:</p><p>Facebook: <a href="https://www.facebook.com/profile.php?id=61574839666569">https://www.facebook.com/profile.php?id=61574839666569</a><br>HackMD: <a href="https://hackmd.io/@jeff377">https://hackmd.io/@jeff377</a><br>GitHub: <a href="https://github.com/jeff377">https://github.com/jeff377</a><br>NuGet: <a href="https://www.nuget.org/profiles/jeff377">https://www.nuget.org/profiles/jeff377</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=2fa92c7db815" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[A JSON-RPC Library With No Method Registration: How Does It Decide What Can Be Called?]]></title>
            <link>https://medium.com/@jeff377/a-json-rpc-library-with-no-method-registration-how-does-it-decide-what-can-be-called-f489835890ae?source=rss-6d011dcf2f94------2</link>
            <guid isPermaLink="false">https://medium.com/p/f489835890ae</guid>
            <category><![CDATA[csharp]]></category>
            <category><![CDATA[dotnet]]></category>
            <category><![CDATA[aspnetcore]]></category>
            <category><![CDATA[open-source]]></category>
            <category><![CDATA[api]]></category>
            <dc:creator><![CDATA[Jeff]]></dc:creator>
            <pubDate>Mon, 12 Oct 2026 00:57:58 GMT</pubDate>
            <atom:updated>2026-10-12T01:12:39.425Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*YtyFy9GerNYEylnF" /></figure><p>JSON-RPC 2.0 is a small specification: the client sends {“jsonrpc”:”2.0&quot;,”method”:”…”,”params”:{…},”id”:1}, and the server answers with a result or an error. REST makes you decide on routes, HTTP verbs and status codes; JSON-RPC only cares about which method to call and with what parameters. For an API where you own both the front end and the back end, that is pleasant to work with.</p><p>Polhem.JsonRpc is a set of .NET packages for JSON-RPC 2.0: a transport-independent server, an ASP.NET Core endpoint and a client, built on System.Text.Json alone. It started as the API layer of <a href="https://github.com/polhem-dev/polhem">the Polhem framework</a>. I have now extracted it into standalone packages that do not depend on the framework, so other projects can reference them directly. The source is on <a href="https://github.com/polhem-dev/polhem-jsonrpc">GitHub</a> under the MIT license, and the packages are on <a href="https://www.nuget.org/packages?q=Polhem.JsonRpc">NuGet</a>.</p><h3>1️⃣ What it covers</h3><ul><li>Full JSON-RPC 2.0: ordinary calls, notifications (calls that expect no response), and batches (several calls in one message). An id can be a string, an integer or null.</li><li>A transport-independent server: the dispatcher (the part that finds and runs the method) knows nothing about HTTP. The ASP.NET Core endpoint is a separate package.</li><li>A client: an HTTP transport, batches, notifications, and interceptors that can rewrite the parameters and result of each call.</li><li>Optional payload encryption: the parameters and result go into an envelope that can be compressed and encrypted, and replayed calls can be rejected.</li></ul><p>It is split into several NuGet packages, so an application references only what it needs:</p><ul><li>Polhem.JsonRpc: message types, error codes and the transport abstraction shared by the server and the client</li><li>Polhem.JsonRpc.Server: the dispatcher, which handles method resolution, parameter binding and filters</li><li>Polhem.JsonRpc.AspNetCore: the ASP.NET Core endpoint, MapJsonRpc</li><li>Polhem.JsonRpc.Client: the client, JsonRpcConnector</li><li>Polhem.JsonRpc.Payload (optional): the payload envelope, compression, encryption and replay protection</li><li>Polhem.JsonRpc.Payload.Client (optional): a client that seals the parameters and opens the result of every call</li><li>Polhem.JsonRpc.Payload.Server (optional): opens the envelope and checks for replays on the server</li></ul><p>The server references Polhem.JsonRpc.AspNetCore, and the client references only Polhem.JsonRpc.Client. The split keeps a client, whether a desktop app or a mobile app, from pulling in ASP.NET Core and the reflection-based dispatcher.</p><p>Native AOT compiles an app to native code at publish time, so nothing can rely on reflection at run time; iOS and WebAssembly both need it. The shared package, the client and the payload packages are marked AOT-compatible, and CI publishes a test program with Native AOT and runs it. The server package finds methods by reflection, so it does not support AOT. The target framework is net10.0.</p><h3>2️⃣ Getting started</h3><h4>ASP.NET Core server (Minimal API)</h4><p>The server uses ASP.NET Core Minimal APIs (endpoints mapped directly in Program.cs with MapXxx, without MVC controllers). MapJsonRpc creates a POST endpoint at the given path, and every JSON-RPC call comes in through it. AddControllers is not needed.</p><p>Program.cs needs three things: register the object factory, register the JSON-RPC services, and map the endpoint.</p><pre>using Polhem.JsonRpc.AspNetCore;<br>using Polhem.JsonRpc.Server;</pre><pre>var builder = WebApplication.CreateBuilder(args);<br>builder.Services.AddSingleton&lt;IJsonRpcObjectFactory, AppObjectFactory&gt;();<br>builder.Services.AddJsonRpcServer();</pre><pre>var app = builder.Build();<br>app.MapJsonRpc(&quot;/api&quot;);<br>await app.RunAsync();</pre><p>AddJsonRpcServer takes two sets of options. The first configures the server itself, such as filters, the method policy, the batch limit and serializer options. The second configures the HTTP endpoint, such as the request body size limit and which HTTP status code an error returns. Leave them out and the defaults apply.</p><pre>builder.Services.AddJsonRpcServer(<br>    options =&gt;<br>    {<br>        options.MaxBatchSize = 50;<br>        options.Filters.Add(new ApiKeyFilter(apiKey)); // see section 5<br>    },<br>    http =&gt; http.MaxRequestBodySize = 1024 * 1024);</pre><p>MapJsonRpc returns the same thing as any other Minimal API endpoint, so authorization, CORS and rate limiting chain on the usual way, for example app.MapJsonRpc(“/api”).RequireAuthorization();.</p><p>The object factory and the class that handles the calls:</p><pre>public sealed class AppObjectFactory : IJsonRpcObjectFactory<br>{<br>    public object? CreateObject(string progId, JsonRpcRequestContext context) =&gt; progId switch<br>    {<br>        &quot;Calculator&quot; =&gt; new Calculator(),<br>        _ =&gt; null,<br>    };<br>}</pre><pre>public sealed class Calculator<br>{<br>    public AddResponse Add(AddRequest request) =&gt; new() { Sum = request.A + request.B };<br>}</pre><h4>Client</h4><pre>using var http = new HttpClient { BaseAddress = new Uri(&quot;http://localhost:5080/api&quot;) };<br>var rpc = new JsonRpcConnector(new HttpTransport(http));</pre><pre>var added = await rpc.InvokeAsync&lt;AddResponse&gt;(&quot;Calculator.Add&quot;, new AddRequest { A = 1, B = 2 });</pre><p>That is enough to call Calculator.Add. Note that the server has no AddMethod or similar registration, and Calculator carries no attribute.</p><h3>3️⃣ With no registration, which methods can be called?</h3><p>Skipping registration is convenient, but it raises a worry: if one day I add a public method to the class for internal use, can it be called from the network too? When the server receives Calculator.Add, it runs the following checks in order.</p><p>Name format: the method name must be ProgId.Action. A ProgId (program identifier) may contain letters, digits, underscores and hyphens; an action letters, digits and underscores; each at most 64 characters. A malformed name is rejected before any lookup.</p><p>The application decides the object: the ProgId is passed to your implementation of IJsonRpcObjectFactory.CreateObject, which decides which object to create; returning null means the ProgId is unknown. The packages keep no registry of names, so which ProgIds exist is entirely up to the factory. After the call, the object is passed to ReleaseObjectAsync to be released.</p><p>Method signature: an action maps only to a public, non-generic instance method with exactly one parameter. Static methods, property accessors and methods declared by object do not count. If two or more methods with the same name qualify, the server does not pick one; it treats the method as not found.</p><p>Naming convention: the parameter type must be named {Action}Request, and the return type (or the result type of Task&lt;T&gt; or ValueTask&lt;T&gt;) must be named {Action}Response. Add takes an AddRequest and returns an AddResponse. This is the default method policy; any public method that does not follow it is treated as nonexistent and answered with -32601 Method not found. An internal helper method that does not follow this naming cannot be called from outside.</p><p>The rule can be replaced through JsonRpcServerOptions.MethodPolicy. The Polhem framework replaces it with one that reads its own access-control attribute.</p><p>Policy before filters: the method policy runs before every filter, so filters such as authorization checks or decryption only ever see calls that are allowed to run.</p><p>Only after these checks are the params bound. params must be a JSON object, deserialized into the request class with camelCase names by default; missing params or an array (positional parameters) are answered with -32602 Invalid params. To return a custom error, a method throws JsonRpcErrorException; any other exception is answered with -32603 Internal error, and the exception message is not sent to the client.</p><h3>4️⃣ The client</h3><p>An error returned by the server becomes a JsonRpcErrorException, which carries the error code and message:</p><pre>try<br>{<br>    await rpc.InvokeAsync&lt;DivideResponse&gt;(&quot;Calculator.Divide&quot;, new DivideRequest { Dividend = 1, Divisor = 0 });<br>}<br>catch (JsonRpcErrorException ex)<br>{<br>    Console.WriteLine($&quot;Error {ex.Code}: {ex.Message}&quot;);<br>}</pre><p>Notifications and batches:</p><pre>// The server runs it but does not respond.<br>await rpc.NotifyAsync(&quot;Calculator.Log&quot;, new LogRequest { Message = &quot;Hello&quot; });</pre><pre>// Two calls sent in the same message.<br>var batch = rpc.CreateBatch();<br>var first = batch.Add&lt;AddResponse&gt;(&quot;Calculator.Add&quot;, new AddRequest { A = 2, B = 3 });<br>var second = batch.Add&lt;AddResponse&gt;(&quot;Calculator.Add&quot;, new AddRequest { A = 4, B = 5 });<br>await batch.SendAsync();<br>Console.WriteLine($&quot;{(await first)!.Sum}, {(await second)!.Sum}&quot;);</pre><p>The request and response classes usually live in a project shared by both sides, which is how the samples in the repo are arranged.</p><h3>5️⃣ Extension points: filters and interceptors</h3><p>A server filter wraps every call. It can reject the call, rewrite the parameters before the method runs, and rewrite the result afterwards. For example, checking an API key:</p><pre>public sealed class ApiKeyFilter(string expectedKey) : IJsonRpcFilter<br>{<br>    public ValueTask InvokeAsync(JsonRpcRequestContext context, JsonRpcFilterDelegate next)<br>    {<br>        context.Transport.Headers.TryGetValue(&quot;X-Api-Key&quot;, out var key);<br>        if (!CryptographicOperations.FixedTimeEquals(<br>                Encoding.UTF8.GetBytes(key ?? &quot;&quot;), Encoding.UTF8.GetBytes(expectedKey)))<br>        {<br>            throw new JsonRpcErrorException(-32001, &quot;Unauthorized&quot;);<br>        }<br>        return next(context);<br>    }<br>}</pre><pre>builder.Services.AddJsonRpcServer(options =&gt; options.Filters.Add(new ApiKeyFilter(apiKey)));</pre><p>To add an HTTP header on the client, use HttpClient’s own DelegatingHandler; the packages add no layer of their own. To rewrite the parameters and result of every call, add an IJsonRpcClientInterceptor.</p><p>The Polhem framework plugs its sessions and authorization checks into these extension points (the object factory, the method policy and filters). None of that logic is in the packages themselves.</p><h3>6️⃣ Encrypted payloads</h3><p>HTTPS protects the connection. If the parameters and results also need end-to-end protection, or a call must not run a second time when it is resent, add the optional payload packages.</p><p>They put params and result into an envelope with three formats: plain JSON, encoded (serialized, then gzip-compressed), and encrypted (AES-256-CBC with HMAC-SHA256, encrypt-then-MAC). A frame carrying a timestamp and a sequence number can also be put in front of the content, so the server can reject expired or repeated requests; that is the replay protection.</p><pre>// Server: the application&#39;s policy decides the keys and which methods must be encrypted or replay-protected.<br>builder.Services.AddJsonRpcServer(options =&gt; options.UsePayload(payloadOptions, new MyPayloadPolicy()));</pre><pre>// Client: called the same way as an ordinary call; each call seals its parameters and opens its result.<br>var rpc = new PayloadConnector(connector, new PayloadProcessor(payloadOptions),<br>    new PayloadConnectorOptions { KeyProvider = () =&gt; sessionKey });<br>var added = await rpc.InvokeAsync&lt;AddResponse&gt;(&quot;Calculator.Add&quot;, request);</pre><p>A few more security details:</p><ul><li>The HMAC is compared in constant time and verified before anything is decrypted.</li><li>The HMAC covers the method name and the direction, so an intercepted call cannot be redirected to another method, and a response cannot be sent back as a request.</li><li>A method can require a minimum format; a request in a lower format is rejected before any key is asked for.</li></ul><p>How keys are negotiated (exchanged after sign-in, provisioned in advance, and so on) is outside the packages and left to the application.</p><h3>7️⃣ How it differs from common libraries</h3><p>There are quite a few JSON-RPC libraries for .NET; here are two common ones for comparison. The version after each name is the latest stable release on NuGet as of October 2026, and the details come from that release’s documentation and NuGet dependency list. Later releases may differ.</p><h4>StreamJsonRpc 2.25.29</h4><ul><li>JSON library: Newtonsoft.Json by default, switchable to System.Text.Json; the package still depends on Newtonsoft.Json and MessagePack</li><li>Transport model: full duplex over a Stream, WebSocket or Pipe</li><li>Client: yes, with proxies generated from interfaces</li><li>How methods are registered: AddLocalRpcTarget adds a target object whose public methods become callable</li><li>Native AOT: partially supported, within the limits its documentation lists</li><li>Good fit: two-way communication, such as Visual Studio extensions or LSP</li></ul><h4>Tochka.JsonRpc 7.4.1</h4><ul><li>JSON library: System.Text.Json</li><li>Transport model: HTTP on ASP.NET Core MVC</li><li>Client: yes</li><li>How methods are registered: controllers that inherit JsonRpcControllerBase; each action is a method</li><li>Native AOT: tied to MVC, not supported</li><li>Good fit: you already use MVC and want to keep writing controllers</li></ul><h4>Polhem.JsonRpc 1.2.0</h4><ul><li>JSON library: System.Text.Json, with no other dependencies</li><li>Transport model: HTTP request and response on ASP.NET Core Minimal APIs</li><li>Client: yes</li><li>How methods are registered: no registration; found by ProgId.Action and the naming convention</li><li>Native AOT: the shared package, the client and the payload packages support it; the server does not</li><li>Good fit: an API where you own both ends, possibly with desktop or mobile clients</li></ul><p>StreamJsonRpc is the most complete, with cancellation, progress reporting and server-to-client calls, but it is designed for streams and full duplex; turning it into an HTTP request/response API means building the endpoint yourself.</p><p>Tochka.JsonRpc is the closest in scope to Polhem.JsonRpc. It builds on MVC controllers, so MVC filters and model binding work as they are, at the cost of sharing MVC’s lack of AOT support.</p><p>Polhem.JsonRpc goes in a different direction: it trades a fixed call shape for “no registration” and “an API that can evolve”, as the next section explains.</p><h3>8️⃣ Design trade-offs</h3><p>The fixed call shape is there so the API can evolve. The ProgId.Action name, one request class and one response class are a deliberate restriction. When a member is added to a request or response class, a member an older front end does not send binds to its default on the server, and a result member an older front end does not know is simply skipped when read. Old and new front ends call the same method, with no v1 and v2 endpoints to maintain. Positional parameters cannot do this: add, remove or reorder one parameter and every caller has to change.</p><p>Defaults follow the specification. The internal error code is -32603, a response carries only jsonrpc, result or error, and id, and id is always written, as null when it cannot be determined. The Polhem framework’s original response format differed from the specification in places; when the packages were extracted, it was the framework that changed to follow the specification, not the packages that bent to the old format.</p><p>The reasoning behind each decision is recorded as ADRs (Architecture Decision Records) in the repo’s <a href="https://github.com/polhem-dev/polhem-jsonrpc/tree/main/maintainers/adr">maintainers/adr/</a>, and the security design is summarized in <a href="https://github.com/polhem-dev/polhem-jsonrpc/blob/main/docs/security.md">docs/security.md</a>.</p><h3>✅ Wrapping up</h3><p>Install the server and client packages:</p><pre>dotnet add package Polhem.JsonRpc.AspNetCore<br>dotnet add package Polhem.JsonRpc.Client</pre><p>The repo includes <a href="https://github.com/polhem-dev/polhem-jsonrpc/tree/main/samples">samples</a>: an ASP.NET Core Minimal API server, a console client (ordinary calls, error handling, notifications and batches), and a server and client using encrypted payloads.</p><p>These packages do convention-based JSON-RPC, not general-purpose JSON-RPC. Protocols whose method names and parameters are defined by someone else, such as the Language Server Protocol, MCP or an Ethereum node’s API (names like textDocument/didOpen and eth_call with positional parameters), cannot be implemented with them; StreamJsonRpc or the MCP C# SDK fit those better. Nor do they offer a full-duplex connection where the server calls the client: one call is one HTTP request and its response.</p><p>If you own both ends of your API, want JSON-RPC that relies on System.Text.Json alone, or have clients that run as desktop or mobile apps, give it a try. Feedback, issues and pull requests are welcome.</p><h3>Further reading</h3><ul><li><a href="https://www.jsonrpc.org/specification">JSON-RPC 2.0 Specification</a> — the full JSON-RPC 2.0 specification</li><li><a href="https://github.com/microsoft/vs-streamjsonrpc">StreamJsonRpc</a> — the choice when you need full-duplex streams</li><li><a href="https://github.com/tochka-public/Tochka.JsonRpc">Tochka.JsonRpc</a> — JSON-RPC built on ASP.NET Core MVC controllers</li><li><a href="https://learn.microsoft.com/dotnet/core/deploying/native-aot/">Native AOT deployment</a> — the limits and compatibility of .NET Native AOT</li></ul><p>📘 Original HackMD notes: <a href="https://hackmd.io/@jeff377/polhem-jsonrpc">https://hackmd.io/@jeff377/polhem-jsonrpc</a></p><p>📢 Reposting welcome, please credit the source.<br>📬 Follow my technical notes and hands-on experience:<br><a href="https://www.facebook.com/profile.php?id=61574839666569">Facebook</a> ｜ <a href="https://hackmd.io/@jeff377">HackMD</a> ｜ <a href="https://github.com/jeff377">GitHub</a> ｜ <a href="https://www.nuget.org/profiles/jeff377">NuGet</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=f489835890ae" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[One OAuth2 Library for Every Kind of .NET App]]></title>
            <link>https://medium.com/@jeff377/one-oauth2-library-for-every-kind-of-net-app-678c3e03bb93?source=rss-6d011dcf2f94------2</link>
            <guid isPermaLink="false">https://medium.com/p/678c3e03bb93</guid>
            <category><![CDATA[c-sharp-programming]]></category>
            <category><![CDATA[oauth2]]></category>
            <category><![CDATA[aspnetcore]]></category>
            <category><![CDATA[dotnet-maui]]></category>
            <category><![CDATA[dotnet]]></category>
            <dc:creator><![CDATA[Jeff]]></dc:creator>
            <pubDate>Sat, 19 Sep 2026 12:08:45 GMT</pubDate>
            <atom:updated>2026-09-19T12:08:45.639Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*K4KEhZrAoPWjnbYZ.png" /></figure><p>Adding “Sign in with Google” to a .NET app sounds like a solved problem, until you have more than one kind of app. The web app uses ASP.NET Core authentication handlers, the desktop tool needs something that opens a browser and catches the redirect, the mobile app needs yet another approach, and the old Web Forms site that still pays the bills uses none of them.</p><p>I wanted one small library that handles all of these the same way, so I built Polhem.OAuth2. It’s open source under the MIT license and available on NuGet.</p><p>If you read my earlier post, <a href="https://medium.com/@jeff377/quick-oauth2-integration-in-net-with-bee-oauth2-3823e01ba44c">Quick OAuth2 Integration in .NET with Bee.OAuth2</a>, Polhem.OAuth2 is its successor. It keeps the idea of one set of options per provider, but most of the rest was rebuilt. The section near the end lists what changed.</p><h3>What it covers</h3><ul><li>Desktop and console apps. It opens the system browser, receives the redirect on a loopback address, and uses PKCE. It works on Windows, macOS and Linux.</li><li>.NET MAUI apps on Android, iOS and Mac Catalyst. It signs in through WebAuthenticator with PKCE, and no client secret goes into the app. An app with its own ASP.NET Core back end can sign in through that back end instead, so the provider&#39;s tokens never reach the device.</li><li>ASP.NET Core. The authorization code flow with PKCE. Each sign-in keeps its state in its own protected cookie.</li><li>Classic ASP.NET. The same flow for Web Forms and MVC apps on System.Web.</li><li>Any other server framework. The core OAuth2Client runs the flow in two steps without depending on an HTTP framework.</li></ul><p>PKCE (Proof Key for Code Exchange) is an OAuth2 extension: the app creates a random value when it starts the sign-in and presents it again when it exchanges the code, so an intercepted authorization code is useless without it. For desktop and mobile apps, which can’t keep a client secret, it’s the protection that matters.</p><p>Supported providers: Google, Facebook, LINE, Microsoft Entra ID, Auth0 and Okta. Every provider returns the same result: a user ID, name and email address, plus the access, refresh and ID tokens.</p><p>The packages:</p><ul><li>Polhem.OAuth2 (netstandard2.0, net10.0): the providers; desktop, console and .NET MAUI apps; other server frameworks.</li><li>Polhem.OAuth2.AspNetCore (net10.0): ASP.NET Core.</li><li>Polhem.OAuth2.AspNet (net472): ASP.NET Web Forms and MVC on System.Web.</li></ul><h3>A desktop or console app</h3><p>LoopbackOAuth2Client listens on the redirect URI, opens the sign-in page in the default browser, waits for the provider to redirect back, and exchanges the code:</p><pre>using Polhem.OAuth2;<br> <br>var options = new GoogleOAuth2Options<br>{<br>    ClientId = &quot;your-client-id&quot;,<br>    ClientSecret = &quot;your-client-secret&quot;,<br>    RedirectUri = &quot;http://127.0.0.1:0/callback&quot;<br>};<br> <br>var client = new LoopbackOAuth2Client(options);<br>AuthorizationResult result = await client.SignInAsync();<br> <br>if (result.IsSuccess)<br>    Console.WriteLine($&quot;{result.UserInfo.UserId} {result.UserInfo.UserName} {result.UserInfo.Email}&quot;);</pre><p>Port 0 picks a free port for each sign-in. It works with providers that accept any loopback port, such as Google; the others need the port you registered.</p><h3>An ASP.NET Core app</h3><p>Register a client at startup:</p><pre>builder.Services.AddOAuth2Client(&quot;Google&quot;, new GoogleOAuth2Options<br>{<br>    ClientId = &quot;your-client-id&quot;,<br>    ClientSecret = &quot;your-client-secret&quot;,<br>    RedirectUri = &quot;https://localhost:7032/auth/callback&quot;<br>});</pre><p>Then start the sign-in and complete it in two actions:</p><pre>public class AuthController(OAuth2Manager oauth2Manager) : ControllerBase<br>{<br>    [HttpGet(&quot;/auth/login&quot;)]<br>    public IActionResult Login()<br>    {<br>        return Redirect(oauth2Manager.CreateAuthorizationUrl(HttpContext, &quot;Google&quot;));<br>    }<br> <br>    [HttpGet(&quot;/auth/callback&quot;)]<br>    public async Task&lt;IActionResult&gt; Callback()<br>    {<br>        AuthorizationResult result = await oauth2Manager.CompleteAuthorizationAsync(HttpContext, HttpContext.RequestAborted);<br>        return result.IsSuccess<br>            ? Content($&quot;Hello, {result.UserInfo.UserName}&quot;)<br>            : Content($&quot;The sign-in failed: {result.Exception.Message}&quot;);<br>    }<br>}</pre><p>Each sign-in keeps its state, PKCE code verifier and redirect URI in a cookie of its own, encrypted with ASP.NET Core data protection. That means no session state, sign-ins started in several tabs don’t overwrite each other, and several servers work together once they share the data protection keys.</p><h3>A .NET MAUI app</h3><p>A mobile app can’t keep a secret, so AppOAuth2Client always uses PKCE without a client secret. You pass it the function that opens the browser, which is usually WebAuthenticator:</p><pre>var options = new Auth0OAuth2Options<br>{<br>    Domain = &quot;your-tenant.auth0.com&quot;,<br>    ClientId = &quot;your-native-client-id&quot;,<br>    RedirectUri = &quot;com.example.app:/oauth2redirect&quot;<br>};<br> <br>var client = new AppOAuth2Client(options, async (url, redirectUri, cancellationToken) =&gt;<br>    (await WebAuthenticator.Default.AuthenticateAsync(url, redirectUri)).CallbackUri);<br> <br>AuthorizationResult result = await client.SignInAsync();</pre><p>If the app signs in to its own back end, the back end can do the sign-in as a web client and give the app a single-use code. The app redeems that code for the user information, and the provider’s tokens stay on the server.</p><h3>Design choices</h3><p>A few decisions shape how the library behaves:</p><ul><li>PKCE is on by default, and every provider endpoint must use https.</li><li>Options are checked when a client is created. Invalid options throw right away, and at startup in ASP.NET Core, not on the first sign-in.</li><li>Expected failures come back as a result, and bugs are thrown. A failed HTTP request, a mismatched state or an error from the provider ends up in result.Exception. An unregistered client name is a programming error, so it is thrown.</li><li>Identify users by provider and user ID, not by email address. Email addresses change, and providers differ in whether they verify them.</li><li>Few dependencies. The net10.0 build of the core package has no package dependencies, nullable annotations cover the public API, and the trim and AOT analyzers check the net10.0 build.</li></ul><p>The reasons behind each decision are written up as architecture decision records in the repository.</p><h3>Coming from Bee.OAuth2</h3><ul><li>Five packages become three. Bee.OAuth2.WinForms and Bee.OAuth2.Desktop are replaced by LoopbackOAuth2Client in the core package.</li><li>Desktop sign-in uses the system browser instead of an embedded WebView2 window. Users can check the address bar, they keep their existing sign-in session and password manager, and the app can’t watch what they type. Google’s policy refuses embedded browsers anyway, and dropping WebView2 means desktop sign-in is no longer tied to Windows.</li><li>Web sign-in no longer needs session state or the OAUTH2_STATE_KEY environment variable. Each sign-in has its own cookie, protected with ASP.NET Core data protection or MachineKey.</li><li>ASP.NET Core registration is one call: AddOAuth2Client replaces the hand-built OAuth2Manager singleton.</li><li>PKCE is on by default, and Okta and .NET MAUI support are new.</li><li>No Bee.Base or Newtonsoft.Json dependency. JSON is parsed with System.Text.Json.</li></ul><p>The README has a <a href="https://github.com/polhem-dev/polhem-oauth2#migrating-from-beeoauth2">migration guide</a> that maps each old type and method to its replacement.</p><h3>Get started</h3><pre>dotnet add package Polhem.OAuth2</pre><p>The README covers each kind of app, including registering redirect URIs with each provider. The repository also includes sample apps for a console app, Windows Forms on .NET and .NET Framework, ASP.NET Core and .NET MAUI.</p><p>GitHub: <a href="https://github.com/polhem-dev/polhem-oauth2">https://github.com/polhem-dev/polhem-oauth2</a></p><p>The library covers one part of the job: signing in and getting the user information and tokens. It doesn’t validate the signature of ID tokens, and it doesn’t manage accounts or permissions after the sign-in. If your project already handles sign-in well with ASP.NET Core’s built-in authentication or an OpenID Connect package, you may not need to switch. It fits best when you have several kinds of apps, such as desktop, mobile and web, and want to write sign-in the same way in all of them.</p><p>Feedback, issues and pull requests are welcome.</p><h3>Further reading</h3><ul><li><a href="https://datatracker.ietf.org/doc/html/rfc7636">RFC 7636: Proof Key for Code Exchange</a>: the PKCE specification</li><li><a href="https://datatracker.ietf.org/doc/html/rfc8252">RFC 8252: OAuth 2.0 for Native Apps</a>: why desktop and mobile apps should sign in through the system browser</li></ul><p>📘 Original article on HackMD, in Traditional Chinese:<br>👉 <a href="https://hackmd.io/@jeff377/polhem-oauth2">https://hackmd.io/@jeff377/polhem-oauth2</a></p><p>📢 You are welcome to republish this, please credit the source.<br>📬 Follow for more engineering notes:<br><a href="https://www.facebook.com/profile.php?id=61574839666569">Facebook</a> ｜ <a href="https://hackmd.io/@jeff377">HackMD</a> ｜ <a href="https://github.com/jeff377">GitHub</a> ｜ <a href="https://www.nuget.org/profiles/jeff377">NuGet</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=678c3e03bb93" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[ERP Architect’s Notes: Designing a Definition-Driven Framework · Series Index]]></title>
            <link>https://medium.com/@jeff377/erp-architects-notes-designing-a-definition-driven-framework-series-index-7753228c4d33?source=rss-6d011dcf2f94------2</link>
            <guid isPermaLink="false">https://medium.com/p/7753228c4d33</guid>
            <category><![CDATA[enterprise-software]]></category>
            <category><![CDATA[software-architecture]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[metadata]]></category>
            <category><![CDATA[erp]]></category>
            <dc:creator><![CDATA[Jeff]]></dc:creator>
            <pubDate>Mon, 14 Sep 2026 17:35:08 GMT</pubDate>
            <atom:updated>2026-10-30T01:24:56.429Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*Ymy8R_a3o8hXI7En.png" /></figure><blockquote><em>The complexity of an ERP is not in how hard any single feature is. It is in how many times the same fact gets restated, multiplied by how many tables, multiplied again by how many customizations.</em></blockquote><p>A thirty-post series written for <a href="https://ithelp.ithome.com.tw/users/20007956/ironman/9251">iThome Ironman 2026</a>, a thirty-day technical writing challenge in Taiwan, published from 2026–08–17 to 2026–09–15. The series is complete.</p><p>This series is not about building one form with a framework. It is about designing a framework that can drive hundreds of forms: the single source of truth lives in definitions rather than code, and the database structure, SQL, screens for multiple front ends, validation and computation, multiple languages, multi-tenancy and customization are all derived from the same layer of definitions. The Northwind case study verifies it, but the case study is evidence, not the subject.</p><p>It is about mechanisms and trade-offs, not a usage tutorial, and the cost of every design is written as plainly as its benefits.</p><h3>Chapter One · Why Definition-Driven</h3><p>What the problem is, where the paradigms diverge, and the case study’s first appearance. This chapter sets side by side how many places one field touches under each paradigm.</p><ul><li>Day 1 · <a href="https://medium.com/@jeff377/why-erp-needs-a-definition-driven-framework-099db9d65927">Why ERP Needs a Definition-Driven Framework</a></li><li>Day 2 · <a href="https://medium.com/@jeff377/an-overview-of-definition-driven-architecture-a4eb489c73f1">An Overview of Definition-Driven Architecture</a></li><li>Day 3 · <a href="https://medium.com/@jeff377/the-northwind-case-study-eight-forms-and-a-custom-business-object-07a98ba2baa8">The Northwind Case Study: Eight Forms and a Custom Business Object</a></li></ul><h3>Chapter Two · Definition Layer</h3><p>What kinds of definition files there are, why their lifecycles differ, and how one structural description grows into the database structure, CRUD SQL, screens for multiple front ends and business rules.</p><ul><li>Day 4 · <a href="https://medium.com/@jeff377/the-purpose-and-classification-of-definition-files-3c84e980bfb1">The Purpose and Classification of Definition Files</a></li><li>Day 5 · <a href="https://medium.com/@jeff377/how-formschema-drives-sql-bd0a83e80273">How FormSchema Drives SQL</a></li><li>Day 6 · <a href="https://medium.com/@jeff377/tableschema-and-database-structure-upgrades-cc9953a4863b">TableSchema and Database Structure Upgrades</a></li><li>Day 7 · <a href="https://medium.com/@jeff377/formlayout-and-screen-generation-for-multiple-front-ends-3eee75c07a1b">FormLayout and Screen Generation for Multiple Front Ends</a></li><li>Day 8 · <a href="https://medium.com/@jeff377/declarative-business-rules-and-computed-fields-0e1fc9381f51">Declarative Business Rules and Computed Fields</a></li></ul><h3>Chapter Three · Data Access and Caching</h3><p>Without writing DTOs, how data crosses layers; the only two things multiple databases have in common; and how a cache knows its source has changed.</p><ul><li>Day 9 · <a href="https://medium.com/@jeff377/day-9-data-and-definitions-split-apart-so-forms-need-no-types-of-their-own-5e76d8564d72">Data and Definitions Split Apart, So Forms Need No Types of Their Own</a></li><li>Day 10 · <a href="https://medium.com/@jeff377/day-10-multi-database-support-crud-and-structure-upgrades-9d1cebf6f8db">Multi-Database Support: CRUD and Structure Upgrades</a></li><li>Day 11 · <a href="https://medium.com/@jeff377/day-11-connections-transactions-and-query-conditions-in-the-data-access-layer-5aca98e186a4">Connections, Transactions and Query Conditions in the Data Access Layer</a></li><li>Day 12 · <a href="https://medium.com/@jeff377/day-12-cross-node-invalidation-for-definition-and-data-caches-dbef9c7f4b82">Cross-Node Invalidation for Definition and Data Caches</a></li></ul><h3>Chapter Four · Business Logic and API</h3><p>Who takes over the part definitions cannot express, where the extension points open, and what a call passes through on its way from the caller to the business object.</p><ul><li>Day 13 · <a href="https://medium.com/@jeff377/day-13-session-management-and-lifecycle-8653e8394fde">Session Management and Lifecycle</a></li><li>Day 14 · <a href="https://medium.com/@jeff377/day-14-extension-points-on-a-business-object-and-when-to-override-them-0131cbcbcb45">Extension Points on a Business Object and When to Override Them</a></li><li>Day 15 · <a href="https://medium.com/@jeff377/day-15-api-contract-layering-and-the-type-registry-b45176dc7536">API Contract Layering and the Type Registry</a></li><li>Day 16 · <a href="https://medium.com/@jeff377/day-16-json-rpc-2-0-protocol-choice-and-the-request-pipeline-c725c8f7dd20">JSON-RPC 2.0: Protocol Choice and the Request Pipeline</a></li><li>Day 17 · <a href="https://medium.com/@jeff377/day-17-the-connector-and-the-convergence-of-client-responsibilities-1a2156273b60">The Connector and the Convergence of Client Responsibilities</a></li><li>Day 18 · <a href="https://medium.com/@jeff377/day-18-the-error-contract-and-user-visible-messages-cc74c1b0f60c">The Error Contract and User Visible Messages</a></li></ul><h3>Chapter Five · Multi-Tenancy and Customization</h3><p>How one codebase lets every company look different without branching and without recompiling or redeploying. Where the customization work currently stops is stated plainly too.</p><ul><li>Day 19 · <a href="https://medium.com/@jeff377/day-19-the-scope-of-the-customization-layer-and-overlay-granularity-59db53e658ba">The Scope of the Customization Layer and Overlay Granularity</a></li><li>Day 20 · <a href="https://medium.com/@jeff377/day-20-multilingual-customization-and-resource-structure-16d5199f3767">Multilingual Customization and Resource Structure</a></li><li>Day 21 · <a href="https://medium.com/@jeff377/day-21-business-logic-customization-and-the-four-plugin-stages-038d5a6c630f">Business Logic Customization and the Four Plugin Stages</a></li></ul><h3>Chapter Six · Transport, Security and Audit</h3><p>What data looks like when it is sent, which protections it passes through, who is allowed to call, and what can be looked up afterward.</p><ul><li>Day 22 · <a href="https://medium.com/@jeff377/day-22-the-division-of-labor-between-xml-json-and-messagepack-b9297b93f38d">The Division of Labor Between XML, JSON and MessagePack</a></li><li>Day 23 · <a href="https://medium.com/@jeff377/day-23-the-api-payload-security-pipeline-order-protection-levels-and-keys-427d561df8c3">The API Payload Security Pipeline: Order, Protection Levels and Keys</a></li><li>Day 24 · <a href="https://medium.com/@jeff377/day-24-the-three-axes-of-permissions-action-row-and-column-dc55d934637a">The Three Axes of Permissions: Action, Row and Column</a></li><li>Day 25 · <a href="https://medium.com/@jeff377/day-25-the-audit-trail-and-the-before-and-after-values-of-a-change-f10f39eb5bce">The Audit Trail and the Before and After Values of a Change</a></li></ul><h3>Chapter Seven · Data Semantics</h3><p>Amounts, quantities, dates and times of day: how the meaning of these values is kept from the definition all the way to the database, without any layer quietly changing it along the way.</p><ul><li>Day 26 · <a href="https://medium.com/@jeff377/day-26-numeric-semantics-multiple-currencies-and-units-of-measure-fcb1f4e37e20">Numeric Semantics, Multiple Currencies and Units of Measure</a></li><li>Day 27 · <a href="https://medium.com/@jeff377/day-27-the-semantic-boundaries-between-date-datetime-and-time-8c91efb1616f">The Semantic Boundaries Between Date, DateTime and Time</a></li><li>Day 28 · <a href="https://medium.com/@jeff377/day-28-time-zone-conversion-of-datetime-0aa3cf9660f2">Time Zone Conversion of DateTime</a></li></ul><h3>Chapter Eight · Case Review and The Big Picture</h3><p>The Northwind application examined item by item: which part definitions, the framework and application code each own. Then a single big picture, and the systems this design does not suit.</p><ul><li>Day 29 · <a href="https://medium.com/@jeff377/day-29-which-part-definitions-the-framework-and-application-code-each-own-6d3269aa8cf5">Which Part Definitions, the Framework and Application Code Each Own</a></li><li>Day 30 · <a href="https://medium.com/@jeff377/day-30-three-depths-of-development-and-the-big-picture-of-the-framework-68bbe77ceede">Three Depths of Development and the Big Picture of the Framework</a></li></ul><h3>About the framework behind this series</h3><p>The mechanisms discussed in the series are all built into an open source framework, <a href="https://github.com/jeff377/bee-library">bee-library</a>. The case study is a separate repository, <a href="https://github.com/jeff377/bee-northwind-avalonia">bee-northwind-avalonia</a>, which pulls the framework in as a package and holds only the application’s own definition files and code.</p><p>Update: Bee.NET (bee-library), the framework used when this series was written, has since been taken over by <a href="https://github.com/polhem-dev/polhem">Polhem</a>. The mechanisms carry over, the framework has been substantially refactored, and it is open source under the MIT license. The bee-library and bee-northwind-avalonia repositories are archived; type names and code in the posts follow bee-library as it was at the time of writing.</p><p>The framework’s only role in this series is to show that these ideas are not just talk on paper. You can skip it entirely, take away only the idea of letting definitions be the source, and build that idea in the languages and tools you know.</p><p>📘 Original index on HackMD, in Traditional Chinese:<br>👉 <a href="https://hackmd.io/@jeff377/ironman-2026">https://hackmd.io/@jeff377/ironman-2026</a></p><p>📢 You are welcome to republish this, please credit the source.<br>📬 Follow for more engineering notes:<br><a href="https://www.facebook.com/profile.php?id=61574839666569">Facebook</a> ｜ <a href="https://hackmd.io/@jeff377">HackMD</a> ｜ <a href="https://github.com/jeff377">GitHub</a> ｜ <a href="https://www.nuget.org/profiles/jeff377">NuGet</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=7753228c4d33" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Day 30: Three Depths of Development and the Big Picture of the Framework]]></title>
            <link>https://medium.com/@jeff377/day-30-three-depths-of-development-and-the-big-picture-of-the-framework-68bbe77ceede?source=rss-6d011dcf2f94------2</link>
            <guid isPermaLink="false">https://medium.com/p/68bbe77ceede</guid>
            <category><![CDATA[erp]]></category>
            <category><![CDATA[software-architecture]]></category>
            <category><![CDATA[enterprise-software]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[metadata]]></category>
            <dc:creator><![CDATA[Jeff]]></dc:creator>
            <pubDate>Mon, 14 Sep 2026 17:13:08 GMT</pubDate>
            <atom:updated>2026-09-14T18:58:45.718Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*4dX69EVRVd6PJ2Yd.png" /></figure><p>The previous post, <a href="https://medium.com/@jeff377/day-29-which-part-definitions-the-framework-and-application-code-each-own-6d3269aa8cf5">Which Part Definitions, the Framework and Application Code Each Own</a>, ended by saying that this one would gather the thirty posts into a single big picture.</p><p>This post covers:</p><ol><li>The three depths the framework offers along the axis of NoCode, LowCode and AnyCode</li><li>The big picture: what grows out of a single FormSchema, and what every call passes through</li><li>Which systems this design suits and does not suit, and where the long term return lands</li><li>The road not yet finished, and what is deliberately not done</li></ol><h3>1. Three depths</h3><p>The three depths are not mutually exclusive, and one form can use all three:</p><ul><li>NoCode: what you write is definitions, being FormSchema, TableSchema, FormLayout, and the FormRule and ValueExpression entries on fields. Changing it means swapping in another definition</li><li>LowCode: what you write is overridden business object steps and business plugins. Changing it means compiling, packaging and deploying</li><li>AnyCode: what you write is a custom front end, business object or repository, or an ExecFunc method. Changing it means compiling, packaging and deploying</li></ul><p>What can be done by changing a definition is NoCode. Adding a piece of code at a step or stage the framework has already cut out is LowCode. Writing a whole stretch yourself because the framework’s flow cannot hold it is AnyCode.</p><p>Logic that every company does the same way moves step by step from LowCode into definitions and the framework, following the process in the previous post’s section on converging from the application into the framework.</p><h3>2. The big picture</h3><p>The vertical path answers what this form looks like, and it grows linearly as forms are added. The horizontal path answers what happened on this call, and it does not change as forms are added.</p><p>The vertical path:</p><pre>             Definitions (single source of truth)<br>                   FormSchema at the center<br>                               │<br>   ┌───────────────────────────┼───────────────────────────┐<br>   │ generated                 │ generated                 │ evaluated<br>   ↓                           ↓                           ↓<br> Layouts                     TableSchema                 FormRule<br> → record, list, lookup      → upgraded after comparing  → at save and delete<br> CRUD statements             DataSet structure           ValueExpression<br> → assembled at run time     → no entity classes needed  → when a related field changes</pre><p>The horizontal path:</p><pre> Front end → Connector → serialize → compress → encrypt<br>                                                   ↓<br>             Endpoint → access control → session → BO (extension points and plugins)<br>                                                   ↓<br>                                              Repository → data access → database</pre><p>Mechanisms that cut across both paths:</p><ul><li>Definition caching and cross-node invalidation: <a href="https://medium.com/@jeff377/day-12-cross-node-invalidation-for-definition-and-data-caches-dbef9c7f4b82">Cross-Node Invalidation for Definition and Data Caches</a></li><li>The error contract: <a href="https://medium.com/@jeff377/day-18-the-error-contract-and-user-visible-messages-cc74c1b0f60c">The Error Contract and User Visible Messages</a></li><li>Customization overlays and multiple languages: <a href="https://medium.com/@jeff377/day-19-the-scope-of-the-customization-layer-and-overlay-granularity-59db53e658ba">The Scope of the Customization Layer and Overlay Granularity</a> and <a href="https://medium.com/@jeff377/day-20-multilingual-customization-and-resource-structure-16d5199f3767">Multilingual Customization and Resource Structure</a></li><li>Deciding and applying permissions: <a href="https://medium.com/@jeff377/day-24-the-three-axes-of-permissions-action-row-and-column-dc55d934637a">The Three Axes of Permissions: Action, Row and Column</a></li><li>Auditing: <a href="https://medium.com/@jeff377/day-25-the-audit-trail-and-the-before-and-after-values-of-a-change-f10f39eb5bce">The Audit Trail and the Before and After Values of a Change</a></li><li>Numeric rounding, the semantics of time, and time zone conversion: <a href="https://medium.com/@jeff377/day-26-numeric-semantics-multiple-currencies-and-units-of-measure-fcb1f4e37e20">Numeric Semantics, Multiple Currencies and Units of Measure</a>, <a href="https://medium.com/@jeff377/day-27-the-semantic-boundaries-between-date-datetime-and-time-8c91efb1616f">The Semantic Boundaries Between Date, DateTime and Time</a> and <a href="https://medium.com/@jeff377/day-28-time-zone-conversion-of-datetime-0aa3cf9660f2">Time Zone Conversion of DateTime</a></li></ul><p>Mechanisms all over the picture keep using the same few principles.</p><p>Position decides meaning. Which side of the transaction an extension point is on, in <a href="https://medium.com/@jeff377/day-14-extension-points-on-a-business-object-and-when-to-override-them-0131cbcbcb45">Extension Points on a Business Object and When to Override Them</a>. Whether a value is kept per process, per session or per call, in <a href="https://medium.com/@jeff377/day-17-the-connector-and-the-convergence-of-client-responsibilities-1a2156273b60">The Connector and the Convergence of Client Responsibilities</a>. Which layer stands in when a translation cannot be found, in the post on multilingual customization.</p><p>Failure has to be visible. Whether you can tell that a cache has gone stale, in the post on cross-node invalidation. Whether a ProgId bound to the wrong type fails on the spot or looks like it is still running, in <a href="https://medium.com/@jeff377/day-15-api-contract-layering-and-the-type-registry-b45176dc7536">API Contract Layering and the Type Registry</a>.</p><p>Everything the caller sends is a claim, not a fact. A type name has to pass the allowlist first, in <a href="https://medium.com/@jeff377/day-22-the-division-of-labor-between-xml-json-and-messagepack-b9297b93f38d">The Division of Labor Between XML, JSON and MessagePack</a>. PayloadFormat has to match the level the method declares, in <a href="https://medium.com/@jeff377/day-23-the-api-payload-security-pipeline-order-protection-levels-and-keys-427d561df8c3">The API Payload Security Pipeline: Order, Protection Levels and Keys</a>. The department column is looked up in the database once more, in the post on permissions.</p><p>The paths in the picture are offered, not enforced. Open your own connection, assemble your own statements, or go around the entry point, and none of the cross-cutting mechanisms take effect.</p><h3>3. Which systems this suits and does not suit</h3><p><a href="https://medium.com/@jeff377/an-overview-of-definition-driven-architecture-a4eb489c73f1">An Overview of Definition-Driven Architecture</a> asked three questions before you commit. Each gets one more sentence here, and two more questions are added.</p><p>Are the screens standardized forms? The answer before: layouts converge into a master block plus a detail block, and dashboards and scheduling are not in the pattern. What going through the series adds: screens outside the pattern use manual layout, and the part that binds data is shared with forms, as <a href="https://medium.com/@jeff377/formlayout-and-screen-generation-for-multiple-front-ends-3eee75c07a1b">FormLayout and Screen Generation for Multiple Front Ends</a> showed.</p><p>Is a request a single document? The answer before: the DataSet is self describing, and every response carries its structure along. What going through the series adds: definitions have to be cached, and changes reach each node through notifications, as the post on cross-node invalidation showed.</p><p>How long does the system have to live? The answer before: the cost is concentrated up front, and the return takes years to show. What going through the series adds: where the return lands is laid out below.</p><p>Is it connecting to an existing database? The overview post did not ask. Existing tables first have to be changed to carry the framework’s system fields, as <a href="https://medium.com/@jeff377/the-northwind-case-study-eight-forms-and-a-custom-business-object-07a98ba2baa8">The Northwind Case Study: Eight Forms and a Custom Business Object</a> noted.</p><p>Will a second one appear? The overview post did not ask this either. A second company, a second language, a second role, a second currency. If none will appear, mechanisms such as the customization layer, multiple languages, permission models and the currency master are pure cost, as the previous post concluded.</p><p><a href="https://medium.com/@jeff377/why-erp-needs-a-definition-driven-framework-099db9d65927">Why ERP Needs a Definition-Driven Framework</a> said that in the short term Code-First wins almost every time. The return on definition-driven design is long term:</p><ul><li>Development process: there is only one way to do the same thing, and nothing to compile, package or deploy between changing a definition and it taking effect</li><li>Maintenance cost: thousands of structurally identical FormSchema files can be checked by one script, for example whether every Currency field is marked with NumberKind</li><li>Education cost: understand one form and you understand them all, as the overview post said. Extension points are listed, and which step you override and which stage you hook into each have a fixed name</li><li>User training: the layout vocabulary is small, so training cost does not grow in proportion to the number of forms, as the post on FormLayout said</li></ul><h3>4. The road not yet finished</h3><p>The previous post separated boundaries from backlog: what deliberately does not go through definitions is a boundary, and what the framework has not finished is backlog. The list below sorts what is not yet complete by why it is not complete:</p><ul><li>Should converge, and has not yet: the document numbering rule, a prefix plus date plus a sequence, which every company currently writes itself</li><li>The declarative side has not caught it yet: cross row aggregation, such as at least one detail row and the master total; and the query condition screen for reports, where FilterNode already exists but a layout generator is missing</li><li>The mechanism is there, but only half done: rounding a value to the column’s capacity before a write has a rule and no implementation, as the post on numeric semantics noted; there is no extension point inside the transaction yet; the front end has no logout flow; the service container for local calls is not yet DI based; JSON-RPC batch requests are not implemented</li><li>The definitions are enough, and the tools are not built yet: exporting import formats and test data from definitions, as in <a href="https://medium.com/@jeff377/day-9-data-and-definitions-split-apart-so-forms-need-no-types-of-their-own-5e76d8564d72">Data and Definitions Split Apart, So Forms Need No Types of Their Own</a></li><li>Not unfinished, but not done by design: genuine business judgment, SQL for reports and batch jobs, and deep screen customization, as the previous post laid out; and ValueExpression does not query the database</li></ul><p>The declarative side not having caught something yet is progress: add aggregate functions and evaluation ordering, and it can become a declaration. Not done by design is a design decision. If ValueExpression could query the database, for example, the front end and the back end could not compute the same answer. Filing either one under the wrong heading costs something different. Treat progress as a boundary, and things that could have converged stay in every company&#39;s code for good. Treat a design decision as backlog, and the framework grows into one that can do anything, which means it has made no decisions for you, as the overview post put it.</p><p>The half done kind is the easiest to mistake for finished when reading the documentation: a rule written with no implementation, a route missing one stretch, something built with no caller. Take rounding to capacity before a write. If the discount column from the previous post, declared with no decimal places, is someday filled with a decimal, whether it gets rounded and how is up to whichever database it happens to be.</p><h3>In closing</h3><p>The first post said the enemy of ERP is restatement. What definition-driven design eliminates is not restatement but copying. The facts about one field still appear in FormLayout, TableSchema, the statements, the DataSet, FormRule, auditing, permissions and time zone conversion. The difference is that all of these places read the same FormSchema, rather than each keeping a copy of its own.</p><p>With everything reading the same one, that one has to be:</p><ul><li>Wide enough to carry meaning beyond structure (the overview post)</li><li>Kept current by something that guarantees every node gets the latest version, or they stay on old values (the post on cross-node invalidation)</li><li>Clear about who can change it, and down to which layer (the post on the customization layer)</li><li>Built so that a missing declaration is visible, because once something is left out the remaining values are still valid (the post on numeric semantics)</li></ul><p>A definition is structured data, and <a href="https://medium.com/@jeff377/how-formschema-drives-sql-bd0a83e80273">How FormSchema Drives SQL</a> listed batch scripts, tools that produce definitions, and AI as all able to work with it. Now that AI can write code, what it produces can be a definition: build time diagnostics check it, the framework expands it, and structurally identical forms can be made one after another by the same procedure. The work of an ERP engineer moves accordingly to the framework, the mechanisms and this procedure, and what has to be understood is how the whole architecture works.</p><p>The thirty posts end here. As the first post said, the framework’s only role in this series is to show that these ideas are not just talk on paper. You can skip it entirely, take away only the idea of letting definitions be the source, and build that idea in the languages and tools you know.</p><p>📚 Part of the thirty-post series <a href="https://medium.com/@jeff377/erp-architects-notes-designing-a-definition-driven-framework-series-index-7753228c4d33">ERP Architect’s Notes: Designing a Definition-Driven Framework</a></p><p>📘 Original article on HackMD, in Traditional Chinese:<br>👉 <a href="https://hackmd.io/@jeff377/day-30-depths-and-map">https://hackmd.io/@jeff377/day-30-depths-and-map</a></p><p>📢 You are welcome to republish this, please credit the source.<br>📬 Follow for more engineering notes:<br><a href="https://www.facebook.com/profile.php?id=61574839666569">Facebook</a> ｜ <a href="https://hackmd.io/@jeff377">HackMD</a> ｜ <a href="https://github.com/jeff377">GitHub</a> ｜ <a href="https://www.nuget.org/profiles/jeff377">NuGet</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=68bbe77ceede" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Day 29: Which Part Definitions, the Framework and Application Code Each Own]]></title>
            <link>https://medium.com/@jeff377/day-29-which-part-definitions-the-framework-and-application-code-each-own-6d3269aa8cf5?source=rss-6d011dcf2f94------2</link>
            <guid isPermaLink="false">https://medium.com/p/6d3269aa8cf5</guid>
            <category><![CDATA[enterprise-software]]></category>
            <category><![CDATA[metadata]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[software-architecture]]></category>
            <category><![CDATA[erp]]></category>
            <dc:creator><![CDATA[Jeff]]></dc:creator>
            <pubDate>Sun, 13 Sep 2026 16:30:54 GMT</pubDate>
            <atom:updated>2026-09-14T18:58:16.141Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*gwiQgUgF0YQtjR7S.png" /></figure><p>The previous post, <a href="https://medium.com/@jeff377/day-28-time-zone-conversion-of-datetime-0aa3cf9660f2">Time Zone Conversion of DateTime</a>, ended by saying that this one would go back to the case study and put those mechanisms in their places one by one.</p><p><a href="https://medium.com/@jeff377/why-erp-needs-a-definition-driven-framework-099db9d65927">Why ERP Needs a Definition-Driven Framework</a> said that of Northwind’s eight forms only one needs code written for it, and promised to lay the whole application out and reconcile it item by item before the series closes. What is inside that one form, <a href="https://medium.com/@jeff377/the-northwind-case-study-eight-forms-and-a-custom-business-object-07a98ba2baa8">The Northwind Case Study: Eight Forms and a Custom Business Object</a> already covered. This post takes every behavior apart and looks at who is responsible for each part.</p><p>This post covers:</p><ol><li>The three levels of system behavior, and the test for each</li><li>What appears at each level from a single form</li><li>What runs on every call, and what the application paid for each</li><li>What hand written code remains, how it converges into the framework, and where definitions are deliberately not used</li></ol><h3>1. System behavior falls into three levels</h3><p>Take any behavior in the system apart, and each part lands in one of these three levels:</p><ul><li>Definition: the behavior is decided by a definition file, and changing that file changes it</li><li>Built into the framework: this part is the framework’s code running, and the application wrote no code for it</li><li>Application code: someone wrote C# by hand, and switching to another ERP means writing it again</li></ul><h4>One behavior can span several levels</h4><p>Take the detail amount. Taken apart, it belongs to all three levels:</p><ul><li>The formula for the amount: definition, written in the field’s ValueExpression</li><li>How many places to round to: definition, looked up in the currency master</li><li>When to recalculate and when to round: built into the framework</li><li>Adding up each row’s amount and writing it back to the master: application code</li></ul><p>So a few items in the next section’s list read definition plus built into the framework.</p><h4>The lists record the current state</h4><p>The lists that follow record the case study as it is now, not necessarily where each thing belongs. Where it belongs is judged with the test from <a href="https://medium.com/@jeff377/an-overview-of-definition-driven-architecture-a4eb489c73f1">An Overview of Definition-Driven Architecture</a>: would every ERP in the world do this the same way? What is the same is done by the framework, and what differs is left to the application. The totaling above is an example: it is the same everywhere, yet today it is still in application code.</p><h4>Not all definitions are written by the application</h4><p>The TableSchema files for the common and log categories use the framework&#39;s defaults as they are. The ones for departments, employees, audit rules and permissions were copied from the framework&#39;s defaults the way <a href="https://medium.com/@jeff377/the-purpose-and-classification-of-definition-files-3c84e980bfb1">The Purpose and Classification of Definition Files</a> describes, and employee has two extra fields added.</p><h3>2. What grows out of a single form</h3><p>The overview post listed what is derived from definitions: most of it is generated, and the other kind is evaluating declared rules and expressions. The behaviors that actually appear along with a form number a few more than that list:</p><ul><li>Fields, types, whether NULL is allowed, uniqueness: definition. Declared completely in one FormSchema</li><li>Creating tables and upgrading them later: definition plus built into the framework. The definition part is one TableSchema per physical table plus a row in DbCategorySettings; comparing against the current state and issuing DDL is the framework&#39;s</li><li>Layouts for the single record form, the list and the lookup window: definition plus built into the framework. The single record form reads the eight FormLayout files the application wrote, and the list and lookup window are arranged on the spot from the field set of the FormSchema</li><li>CRUD statements: built into the framework. A query is assembled on the spot from the fields this particular call uses, cross table JOINs included; inserts and updates carry every column of the table</li><li>Cross table relationships: definition plus built into the framework. One declaration decides the editor, what is filled back after a pick, the JOIN and the value that gets stored</li><li>The cross layer data container: built into the framework. No entity classes, no DTOs, no mapping configuration</li><li>Validation rules and computed fields: definition. Across the whole application, only the order declares FormRule entries and one ValueExpression</li><li>Default values for a new row: built into the framework. Filled in by field type, and a date field gets today in the user’s time zone</li><li>The actions exposed to callers: built into the framework. All eight forms share the same set, differing only in ProgId</li><li>Menu and program registration: definition. One item in MenuSettings, one row in ProgramSettings</li><li>Whether definitions agree with one another: built into the framework. Build time diagnostics ship with the package, and the case study’s server is checked when it builds</li></ul><p>Everything that adding a form touches falls in the definition level: one FormSchema, one TableSchema per physical table, one FormLayout, a row in DbCategorySettings, a row in ProgramSettings and an item in MenuSettings. The first three are new files, and the last three each gain one line. The table creation code does not change either; it creates or upgrades each table registered in DbCategorySettings in turn.</p><p>The definition level can go wrong too, and nobody reports it. The detail’s discount declares only a type and no decimal places, so it is created as a column with a decimal scale of zero. SQLite, which the case study uses, keeps decimals as they are, and every discount is zero anyway, so it has never been hit.</p><p>As for the application code level: seven of the eight forms have zero lines. Those seven rows in ProgramSettings give only a ProgId and a display name, which means the whole flow takes the defaults.</p><h3>3. What runs on every call</h3><p>The things below happen on every call. All of them are built into the framework, and after each one is what the application paid for it:</p><ul><li>Endpoint, request parsing and method dispatch: an empty controller subclass</li><li>Serialization and binding of transport types: zero lines on the server; of the four front ends, all but the desktop one carry an entry in their build files granting an exception</li><li>Compression, encryption and key derivation: a few lines at startup, being a master key seed, the payload options and a flag allowing automatic creation</li><li>Access control, the API key check and the three axes of permissions: nothing declared separately</li><li>Login, the session, and the user’s time zone and language: zero lines of code, with the time zone and language read from the user’s seeded row</li><li>The error contract and the messages users can see: the message text is written on FormRule attributes, and the order&#39;s code puts it in the exceptions it throws</li><li>Auditing: a block of switches in SystemSettings and a few rows in DbCategorySettings, zero lines of code</li><li>Time zone conversion: zero lines of code, since the application’s own two time fields are both calendar dates</li><li>Numeric rounding: two fields are marked with NumberKind, and on top of that the currency master is deployed and the company&#39;s base currency is set to USD</li><li>Definition caching and cross-node invalidation: a row in DbCategorySettings for the notification table</li></ul><p>There is also a group of mechanisms that the case study uses only lightly:</p><ul><li>Not used: business plugins, permission models, the unit of measure master, and the maintenance screen for plugin settings</li><li>Connected, but with only one of each: the customization layer, multiple languages and the currency master. The case study is still one company, one customization and one currency, and only the order has a translation</li></ul><p>They pay off only once a second one appears: a second company, a second language, a second role, a second currency. So this group cannot be counted as what the framework saves the application. It is the more expensive part of this design, and until the second one appears, the cost paid out looks like pure waste.</p><h3>4. What hand written code remains</h3><h4>The order’s five things</h4><p><a href="https://github.com/jeff377/bee-northwind-avalonia/blob/main/Bee.Northwind.Server/BusinessObjects/OrderBO.cs">OrderBO</a> overrides only two of the steps the framework cuts out: getting a new record, and the step before saving. The latter looks like this:</p><pre>protected override void DoBeforeSave(SaveContext context)<br>{<br>    base.DoBeforeSave(context);   // FormRule and ValueExpression finish running here first</pre><pre>    var dataSet = context.DataSet;<br>    var master = OrderDataSet.MasterRow(dataSet);</pre><pre>    OrderDataSet.RequireAtLeastOneDetail(dataSet);<br>    EnforceStatusRules(dataSet, master);<br>    AssignOrderNumber(master);<br>    OrderDataSet.ComputeTotal(dataSet);<br>}</pre><p>That is four things, and the fifth is in the step that gets a new record. Why each of the five is still in code:</p><ul><li>Whether a status transition is legal: a genuine business judgment. Which states can be jumped to, and whether details can still change after confirmation, is set differently at every company</li><li>Generating the order number: standard behavior, which the framework should absorb and has not yet</li><li>At least one detail row: cross row aggregation. A rule model that evaluates row by row can see the fields of one row, but not how many rows this document has</li><li>Summing the details back into the master: the same. The framework already decides when each row is rounded, and adding up the rounded values is still outside it</li><li>The order date defaulting to today: the framework already does this, taking today in the user’s time zone; this line takes the server’s today</li></ul><h4>Converging from the application into the framework</h4><p>The logic and customization specific to a form converge toward the framework along the same path:</p><ol><li>The application writes it first: the framework has no matching mechanism yet, so it goes into an overridden business object step or a business plugin. In the case study, the detail amount, the required field checks and the five things above all started out in OrderBO</li><li>Deciding whether to absorb it: the test from the overview post, whether every company does it the same way. Status transitions differ at every company, so they stay in the application</li><li>The framework takes over: what can be declared goes into definitions, and what needs no declaration is built into the framework. The detail amount became a ValueExpression, the required field checks became FormRule entries, and defaulting the order date to today is built into the framework; the order number and cross row totals have no matching mechanism yet</li><li>The application deletes the old code: the part that has been taken over is removed from the business object. The amount and the required field checks are already deleted, and the order date line is still there</li></ol><h4>The application shell</h4><p>On the server, apart from the order, all the code describes this deployment and has nothing to do with forms:</p><ul><li>Multiple databases: the code registers only database drivers, and the case study uses SQLite. The common, company and log categories each have a connection in DatabaseSettings, all currently pointing at the same file. Splitting them into different databases means changing only this settings file, switching to another database also means registering its driver, and no form definition has to change.</li><li>The rest: host wiring, cross origin settings for development, the empty controller subclass, the demo account, and creating tables and loading sample data.</li></ul><h4>The front end side</h4><p>The front ends have nothing to do with forms either:</p><ul><li>Multiple front ends: desktop, browser, iOS and Android share one UI project, each with only a few lines of startup code, declaring remote only, the endpoint, and where the key is stored.</li><li>Calling the back end through the Connector: every action a form uses has a matching method. A call carries the API key and the token obtained at login, and its content is compressed and then encrypted; the browser one cannot get the key used for encryption, so it goes only as far as compression.</li><li>No file in the UI project is written for a particular form: the container that hosts a form takes a ProgId, and the navigation list grows out of MenuSettings. Going from eight forms to eighty, this side does not change.</li></ul><h4>Where definitions are deliberately not used</h4><ul><li>Genuine business judgment: in the case study, only the status transition</li><li>SQL for reports and batch jobs: multi table JOINs, aggregation, dynamic conditions and performance tuning. Forcing definitions onto them only makes things more complicated, and what the framework offers is a route for writing your own repository</li><li>Deep screen customization: FormLayout describes how fields are arranged, not what a dashboard should look like</li></ul><p>These are boundaries, not backlog items. The backlog is what the framework has not finished, such as the order number and cross row totals.</p><h3>In closing</h3><p>Seven of the eight forms have zero lines, and neither the application shell nor the front ends depend on how many forms there are.</p><p>The three levels relate to the number of forms in different ways. The definition level grows linearly, and it should, because every form has its own fields, its own relationships and its own idea of what to show. The level built into the framework is constant, since what one call has to do does not grow as forms are added. The application code level follows rules, not forms: every rule the framework has not taken over yet has to be written once in every form that uses it, and what should finally remain is only the few rules that differ from company to company.</p><p>Of the order’s five things, four can leave the application sooner or later: the order number once the framework absorbs it, at least one detail row and the detail total once definitions can compute across rows, and the order date line by simply being deleted. The status transition will always stay, because every company differs. The case study post closed on writing code only where a judgment is genuinely required, and in this case study that means the status transition.</p><p>The next post, <a href="https://medium.com/@jeff377/day-30-three-depths-of-development-and-the-big-picture-of-the-framework-68bbe77ceede">Three Depths of Development and the Big Picture of the Framework</a>, is the last one, gathering the thirty posts into a single big picture.</p><p>📚 Part of the thirty-post series <a href="https://medium.com/@jeff377/erp-architects-notes-designing-a-definition-driven-framework-series-index-7753228c4d33">ERP Architect’s Notes: Designing a Definition-Driven Framework</a></p><p>📘 Original article on HackMD, in Traditional Chinese:<br>👉 <a href="https://hackmd.io/@jeff377/day-29-case-reconciliation">https://hackmd.io/@jeff377/day-29-case-reconciliation</a></p><p>📢 You are welcome to republish this, please credit the source.<br>📬 Follow for more engineering notes:<br><a href="https://www.facebook.com/profile.php?id=61574839666569">Facebook</a> ｜ <a href="https://hackmd.io/@jeff377">HackMD</a> ｜ <a href="https://github.com/jeff377">GitHub</a> ｜ <a href="https://www.nuget.org/profiles/jeff377">NuGet</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=6d3269aa8cf5" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>