© Sergei Y.Kitáev, 2020
Screenshots (not from above pages):
Client-Server WASM-Application In C#, TypeScript And Transact-SQL
See it in :
See it at
(Developer Community Web-Site):
The idea is to create reusable skeleton for Web-application simultaneously on both client and server sides, including also some support at database level. This idea also may be named simply as Web-application engine. Such an engine is build in several languages which are normally the same that are used in user application code. (Let us shortly reference to this idea as CSWEB.)
The formula issues from the title. Client-Server.WEB is an approach based on usage of traditional programming language(s), that allows to build almost-classic application for database access, which may be loaded into browser web-page (plus involvement of different capabilities from Web-platform that is famous of its richness). In other words, base realization of such a model has to provide from one side a way of building UI-forms (at the client-side), and from another server-side — a technique of query writing (to database and not only). Program interface of client-server interoperation should be declared mainly in high-level traditional programming language(s). As for UI-behaviour — the most clean behaviour is required, like that we have in traditional desktop GUI. More synchronized interaction (user–application) is needed here, but without prolonged and non-cancellable blockings of the UI (like we may find in numerous old-styled desktop apps). It seems that some compromise in UI-organization may be suitable for this task (such “intermediate incarnation”: Web/Desktop-styled UI).
Due to strange evolution way of Web-browsers which is resulted in survival of the sole available UI-construction form that is HTML/CSS,
we do not have any right of choise here, in development of UI for Web-browser application (only ecumenical HTML/CSS).
C#-language is well suitable for our experimental task (even inspite of difficult JS-interoperation).
Main advantages of C#-usage for Client-Server.WEB:
– uniform client-server interface in form of exchangeable stuctures (data-models for interoperation: Client–Server);
– partial classes as salvation of “kilometer-length” files of code (but unfortunately except razor-markup files where Blazor-components are the cure).
C# is not the only imperative language in this project. TypeScript is used intensively for access to DOM. At serve-side database queries are constructed in Transact-SQL (SQL-Server DBMS is used) side-by-side with C# data-models — so-called “bilingual queries” (C#/SQL).
BookRegistry-program is a sample Web-application which is intended to probe Blazor-WASM framework and to work out some generalized C#-cooperation: WASM-Blazor client (C#) versus Web-server in ASP.NET (C#), plus necessary TypeScript for access to DOM. The purpose was to elaborate a multilingual support for traditional client-server functionality that should be accessible from Web-page (so-called client-server app.engine for Web).
The program demonstrates some operations of simple tool (Web-application), which is intended to support following two things: (I) book selection from database by different parameters, and also (II) editing of book registry. Authorized user may: (1) correct book-record, (2) add new book into book-registry (database), and (3) to delete unnecessary book-record. It’s simple itself (not much user code), but it is strongly cooperated with the engine (skeleton). This construction (engine+app.) provides certain unification into UI and into user app. behaviour. Simplified preuso-synchronous approach for UI-interaction is used in this SPA like somewhere in classic desktop UI (but this is not very restrictive). The program is provided with so-called Magistral layout for SPA performed in a special manner, so as if it is embedded at browser level. This layout is intended to supplement a lack of some important user accessors to UI (that are: vertical side-bar inside application page — with top/bottom scrolling, content selection button, operation escape-unblock, intentional reloading of virtual-page etc.) and also supports so-called Foreground UI-operation (with corresponding visual indication of performing action). Magistral layout is interesting thing which is potentially useful in terms of its general application. It is implemented in TypeScript and it has corresponding simple API for C# (WASM DLL).
BookRegistry application together with all its libraries and auxiliaries, all this is standing directly on three imperative languages and without intensive usage of something high-level — as in Web-client so as at server-side. For instance, BootStrap library is used superficially (mainly for decorations of different kinds). The server which is in C# (in ASP.NET) operates with database with help of extremely lightweight ORM to SP and queries which is implemented in DotNetHelpers. (This construction sits on ADO.NET.)
Both parts of the program Client & Server are in C# and this is determinative here. For the sake of unified Client-Server interoperation special C#-classes are introduced (as base exchanging structures for data-models). Normally user code does not use JSON-features (C# attributes) intensively. Instead, all declarations of data exchange are specified mainly in pure C# language, which has priority over JSON (in this approach). Conditional compilation is used extensively however for declaration of C# exchangeable objects and in some implementations (code-files). Such non-trivial declaration is used in order to represent exchange data-model in one single place, so that this description to take effect for the both sides (client/server), but with some differences in behaviour at sides of the server and the client.
Also, there is a lot interesting concerning to error handling, especially in client-side. For example, error page is implemented in WASM-Blazor. Special technique is used when dealing with possible exceptions. See source code of BookRegistry.Client subproject (in corresponding BookRegistry app. download from supporting site).
SPA (Single Page Application) is equipped with so-called Magistral-layout, which has been designed as SPA-container for clean internal SPA-navigation and possibility of explicit cancellation (abandoment by user) of server request invocation. Such cancellable busy-operation is realized here as semi-blocking visual procedure.
Magistral-layout is implemented with help of TypeScript (there is C# API for Blazor-client; .NET-classes: AFXUI.UMagistral and AFXUI.UMagistralMI). Magistral HTML (layout elements in markup) was intentionally built at topmost in wwwroot/index.html (instead of Razor-file) — for the sake of sense presence of embedded SPA-enhancement, as if it has been built-in into browser (for such perceptional effect).
BookRegistry-application consists of a set of modules (DLLs) and each side (client/server) has its own subset.
This Blazor-based program (WASM-client) uses special error control technique for UI-access from C#. This technique is based on extensive usage of corresponding exception guards in UI-message/event circuit. This mechanism together with other helpers of visual character are packed into AFXUI auxiliary library (AFXUI.dll-module; AFXUI-namespace). Public types (lib.classes etc.) has following name-patterns: “U…” (prefixed) and “…AFX” (suffixed).
Other app.-framework extensions are implemented in client-project, in AFXUI.App-subfolder.
In addition, this application uses its own modest component collection located in “Client\Shared”-subfolder (“A…”-classes).
In folder “SHARED\$General.AFX” there are extension classes for both sides: C#-client / C#-server.
(AFX-abbreviation means here Application Framework Extension.)
BookRegistry-application is build with auxiliary base library DotNetHelpers
(set of libs with extensions of general runtime character), which is represented by following modules:
– CommonHelpers.WASM.dll (at client-side);
– CommonHelpers.dll+CommonHelpers.2.dll+CommonHelpers.3.dll (at server-side).
Satellite library sources (DotNetHelpers base-lib.):
– “HandicraftSDK\Legacy\DotNetHelpers\Libraries\.WASM\CommonHelpers.WASM” (code-packages: $Core);
– “HandicraftSDK\Legacy\DotNetHelpers\Libraries\.WIN32\CommonHelpers.*” (code-packages: $Core, $Plus, $Console, $Data, $ORM, …).
DotNetHelpers and BookRegistry app.:
For the sake of simplification all DotNetHelpers DLLs were placed under following local binary root: “BookRegistry\AssemblyRef\Legacy\DotNetHelpers”. You do not need to compile DotNetHelpers-library by oneself nor reference its assemblies located in Handicraft-SDK. Source projects of BookRegistry application are prepared for standalone build. Also it is not required to install TypeScript because “BookRegistry.TS.njsproj” is allready compiled into “Client\wwwroot\ts\**\*.js”. (If you wish to reference DotNetHelpers DLLs from Handicraft-SDK, for this purpose there are commented references to corresponding DLLs in three “.csproj”-files.)
It is possible to perform total re-compilation: DotNetHelpers + BookRegistry app.
All DotNetHelpers DLLs are provided with strong name. Code signing is considered as obligatory here (for compilation of whetever library module). DotNetHelpers-library compilation requires private key installed into CSP-container on your machine (under your local profile). You can install it from “XSoft” test certificate (from “HandicraftSDK\Author code signature\XSoft\Private key\XSoft.pfx”). Also define following environment variable for DotNetHelpers code signing: “DNH_KeyContainerName=XSoft” (in var.initialization system applet). You may specify your own key-container name. But then you also need to correct “!CommonHelpers.Common.props”-file (in “HandicraftSDK\Legacy\DotNetHelpers\Libraries”-folder) containing corresponding MSBUILD-properties (referenced by all library compilations).
DotNetHelpers must be compiled under local administrator, and not from Windows Explorer (folders shell) but from standalone admin.console for instance (with full rights). The most comfortable way of library build and configuration is achieved by using of Far Manager started with elevated rights. (Also Visual Studio is suitable for compilation of separate library module.)
On side of Web-server service code is separated into following two different parts:
“hard-part” (C#-controllers) and “soft-part” (procedural T-SQL).
In spite of any difficulties of such division, soft-part is very useful thing, because it may be corrected
on the fly, without need of server restart. Also the code may be changed by little pieces as opposed to hard C# EXE/DLL-recompilation.
In BookRegistry Web-server each query to database is represented by two nearly-situated files of same base-name:
<NamedQuery>.sql and <NamedQuery>.cs. Such DB-query is visible not only for server-side C#,
but also exposes correspondent data-structures and/or error-statuses for C#-client (WASM app.).
Directives of conditional compilation are used intensively for the sake of flexibility
(instead of simple DLL-sharing by means of .NET-standard format).
The project uses (intentionally) its own specially-made support for database access — extremely lightweight ORM to SP and “traditional queries”, which sits directly on ADO.NET.
Database data-models (structures) are normally declared only once in C# — simultaneously for server and client sides
(with some differences, that is achieved via conditional compilation).
This approach is used to form interaction API (Web-client—Web-server) with minimal involvement of usage of JSON-attributes for C#.
Exchangeable C# data-models are implemented as so-called self-checking objects, with strict property getters
applied to values, whose type (in C#) does not provide null. Such autonomous checking technique (C#-only)
is used to guarantee consistency of nulls.
At client-side additional JSON-to-null checking is fired automatically by service invocation routine (in AFX) — when response-object is received from server. It is realized as so-called “back-packing”-test (in AFX) for the sake of null-checking (before access to response object properties from application writer client-code).
At DB-level — Transact-SQL is used for queries. SQL-code is maintained with help of SQL-file technology — lightweight scripting/command-line tools for Transact-SQL enhancement, which allows to organize SQL-project on base of traditional file/directory structure usage (for code-files), with corresponding code-translation: from SQL-files to SQL-database.
In BookRegistry-application SQL-code is located in following folders:
– “SHARED\$ClientServer\!DB-queries (application SP)”: top-level stored procedures;
– “SQL (DB-modelling)”: base stored procedures, table creation, initial data filling, data deletion, table-structure removal etc.
SQL-file technology includes following components:
– $SqlTrans command utility (SQL-file to DB translation, preprocessor etc.; it is based on well-known SQLCMD-tool);
– other CMD-utilities: $SqlUplodad, $SqlToCsvExp (SqlToCsvExport.exe), $SqlCon, $SQL;
– SQLAUX scripting library (helper objects like SP, scalar/table-function, etc.; import definitions, templates etc.);
– integration features (plugin/marco for Far-Manager, settings/instructions, etc.);
– miscellaneous templates and samples, illustration pictures etc.
For information about SQL-file proceed following local page:
BookRegistry-program together with its libraries (AFXUI.dll, DotNetHelpers,
modest app.component lib. and other AFX-subfolders in application projects), — all this has been built/united
as minimal implementation of simple idea: to launch Client-Server WASM-application in C#, TypeScript and T-SQL.
BookRegistry-program (WASM-Blazor app.) is working example of this idea.
(This minimal sample code-project was produced in April 2020.)
This work was performed some time before WebAssembly 3.2.0 Release.
There is introductory article: Client-Server WASM-Application In C#, TypeScript And Transact-SQL.
See it in :
(open the article in new tab).
See it at
(Developer Community Web-Site):
(open the article in new tab).