DEV Community: ben

Practical Combat of MAUI Embedded Web Architecture (10) App Web Shell Architecture: Building a Cross-Platform Local Application Platform

ben — Sun, 05 Apr 2026 02:45:16 +0000

PicoServer
Source Code URL:
https://github.com/densen2014/MauiPicoAdmin

In the previous articles of this series, we have gradually built a complete local web architecture based on MAUI + PicoServer, which includes the following components:

Embedded Web Server
REST API
Web Admin Management Backend
WebSocket Real-Time Communication
Permission System
Automatic Controller Discovery
PWA Offline System

At this point, we can re-examine this system.

You will find that:
It is no longer just a Web Admin.

It is actually a new application architecture:
App Web Shell

I. What Is App Web Shell

Traditional Application Structure

Native UI
↓
Native Logic
↓
Database

Web Application Structure

Browser
↓
Web Server
↓
Database

App Web Shell Architecture

Web UI
↓
Local Web Server
↓
Local Services
↓
Database / Device

Its essence is:
Driving local applications with Web UI

II. Complete System Architecture

The final architecture is as follows:

                Web UI
                 │
             Service Worker
                 │
        ┌────────┴─────────┐
        │                  │
   Cache Storage       IndexedDB
        │                  │
        └────────┬─────────┘
                 │
             PicoServer
                 │
            REST API
                 │
        ┌────────┴─────────┐
        │                  │
      MAUI Services    Plugin APIs
        │                  │
        └────────┬─────────┘
                 │
              SQLite
                 │
               Device

This architecture achieves the following capabilities:

Web UI
Local API
Local Database
Offline Operation
Plugin Extension

III. Why Choose Web Shell

Traditional App UI has many drawbacks:

1. High UI Development Cost

Native UI requires three separate codebases for:

Android
iOS
Windows

Web UI only needs one set of technologies:

HTML
CSS
JS

2. Difficult Updates

Native Apps require:

Publishing
Review
Update Distribution

Web UI can be updated simply by:

Refreshing the page

3. Troublesome Plugin Extension

Traditional Apps need:

Recompilation
Republishing

Web Shell enables extension by:

Adding new APIs
Adding new pages

IV. The Role of PicoServer

In the entire architecture:
PicoServer is the core component

It undertakes the following roles:

Web Server
API Gateway
Plugin Loader
Local Service Bridge

All web requests follow this flow:

Browser
↓
PicoServer
↓
MAUI

V. Plug-in API System

With the automatic controller discovery mechanism we implemented earlier, adding new APIs becomes extremely simple:

public class ProductController
{
    [Route("/api/products")]
    public List<Product> GetProducts()
}

The system automatically registers the API on startup via:

api.AddRoute(...)

No modifications to the main program are required.

VI. PWA Offline Capabilities

With Service Worker, we achieve:

Offline Caching
Background Updates
Local Database

The user experience is close to that of a native app.

The system supports:

Browsing products offline
Placing orders offline
Syncing data when the network is restored

VII. WebSocket Real-Time Communication

WebSocket solves the needs for:

Real-time data updates
Device status monitoring
Log pushing

The structure is as follows:

Browser
↕
WebSocket
↕
PicoServer

This enables real-time UI updates.

VIII. Advantages of App Web Shell

The final system has the following strengths:

1. Cross-Platform Compatibility

MAUI supports multiple platforms:

Windows
Android
iOS
Mac

2. Offline Operation

Service Worker
IndexedDB
Cache Storage

3. High Extensibility

Through the plug-in API system:

Controllers
Modules
Plugins

4. Rapid UI Development

Web UI supports any frontend framework:

Vue
React
Alpine
HTMX

IX. Applicable Scenarios

This architecture is particularly suitable for:

IoT Devices
- Device management
- Local control
- Monitoring dashboards
Commercial Terminals
- POS systems
- Warehouse management systems
- PDAs
Industrial Systems
- Production equipment management
- Factory monitoring
- Control systems
Local Tools
- NAS management
- Download utilities
- Administrative backends

X. Architecture Summary

The entire system can be summarized in one sentence:
App = Web UI + Local API + Local Database

In other words:

Web Shell
↓
Local Server
↓
Local Services

Web is responsible for:

UI presentation
User interaction
Business logic

Local layer is responsible for:

Device access
Data storage
System-level capabilities

Series Summary

This series of articles has demonstrated how to build a local web application architecture based on MAUI + PicoServer from scratch.

We have evolved from the basics to a complete system, covering:

Web Server
REST API
Web Admin
WebSocket
Plugin System
PWA Offline
Web Shell

Ultimately, we have built a cross-platform local application platform.

Practical Combat of MAUI Embedded Web Architecture (9) PicoServer + PWA Offline System: Building a True Local Web App

ben — Sun, 05 Apr 2026 02:41:51 +0000

PicoServer
Source Code URL:
https://github.com/densen2014/MauiPicoAdmin

In the previous articles of this series, we have gradually built a complete PicoServer local Web Admin system with the following components:

MAUI Embedded Web Server
REST API Architecture
Web Admin Management Backend
WebSocket Real-Time Communication
Automatic Controller Discovery and Plug-in Support

Currently, the system has the following workflow:

Web UI
↓
REST API
↓
MAUI Local Services
↓
SQLite / Device

However, one question remains:
Can the system still run when the browser is offline?

The answer is: Yes.

With PWA (Progressive Web App) + Service Worker, we can enable the Web Admin to have the following capabilities:

Offline Operation
Local Caching
Background Sync
Automatic Updates

Ultimately achieving:
PicoServer + PWA = Local Web Application Platform

I. Overall System Architecture

The complete architecture is as follows:

            Browser / WebView
                   │
             Service Worker
                   │
       ┌───────────┴───────────┐
       │                       │
   Cache Storage          IndexedDB
       │                       │
       │                       │
       └───────────┬───────────┘
                   │
               PicoServer
                   │
                REST API
                   │
                 MAUI
                   │
             SQLite / Device

Explanation:

Cache Storage

Used for caching:

HTML
JS
CSS
Images

IndexedDB

Used for caching:

Product Lists
Orders
Offline Documents
Sync Queues

Service Worker

Responsible for:

Request Interception
Offline Caching
Background Updates

II. Basic PWA Components

PWA mainly consists of three parts.

1. Manifest

manifest.json:

{
  "name": "Pico Admin",
  "short_name": "PicoAdmin",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#1976d2",
  "icons": [
    {
      "src": "/icons/icon-192.png",
      "sizes": "192x192",
      "type": "image/png"
    }
  ]
}

Functions:

Allows web pages to be installed as apps
Defines app icons
Defines launch modes

2. Register Service Worker

Add the following code in the frontend entry file:

if ('serviceWorker' in navigator) {
    navigator.serviceWorker.register('/sw.js')
        .then(reg => {
            console.log("SW registered");
        });
}

III. Cache Strategy Design

In offline systems, different resources require different caching strategies.

Resource Type	Strategy
HTML	Network First
JS / CSS	Cache First
Images	Cache First
Product API	Stale While Revalidate

Explanation:

Cache First

Prioritize reading from cache:

cache → network

Suitable for:

JS
CSS
Images

Network First

Prioritize accessing the network:

network → cache

Suitable for:

HTML
API

Stale While Revalidate

Return cached data first, then update in the background:

cache → network update

Suitable for:

Product lists
Configuration data

IV. Complete Service Worker Implementation

sw.js:

const STATIC_CACHE = "pico-static-v1";
const API_CACHE = "pico-api-v1";

const STATIC_FILES = [
    "/",
    "/index.html",
    "/app.js",
    "/style.css"
];

self.addEventListener("install", event => {
    event.waitUntil(
        caches.open(STATIC_CACHE)
            .then(cache => cache.addAll(STATIC_FILES))
    );
});

self.addEventListener("activate", event => {
    event.waitUntil(
        caches.keys().then(keys => {
            return Promise.all(
                keys.filter(k => k !== STATIC_CACHE && k !== API_CACHE)
                    .map(k => caches.delete(k))
            );
        })
    );
});

V. Request Interception

Service Worker can intercept all requests.

fetch → Service Worker
      → Cache
      → Network

Implementation code:

self.addEventListener("fetch", event => {
    const url = new URL(event.request.url);

    // Product API
    if (url.pathname.startsWith("/api/products")) {
        event.respondWith(cacheProductApi(event.request));
        return;
    }

    // Static resources
    event.respondWith(cacheFirst(event.request));
});

VI. Product API Caching Example

Product API endpoint:

GET /api/products

Caching strategy: Stale While Revalidate

Code implementation:

async function cacheProductApi(request) {
    const cache = await caches.open(API_CACHE);
    const cached = await cache.match(request);

    const networkFetch = fetch(request)
        .then(response => {
            cache.put(request, response.clone());
            return response;
        })
        .catch(() => cached);

    return cached || networkFetch;
}

Explanation:

Workflow:

Return cached product data immediately
Fetch the latest product data in the background
Update the cache with new data

Users won't perceive any delay.

VII. Static Resource Caching

async function cacheFirst(request) {
    const cache = await caches.open(STATIC_CACHE);
    const cached = await cache.match(request);

    if (cached) return cached;

    const response = await fetch(request);
    cache.put(request, response.clone());
    return response;
}

Suitable for:

js
css
images

VIII. Periodic Product List Refresh

You can periodically update the product cache in the frontend page.

For example:

setInterval(async () => {
    try {
        await fetch("/api/products");
        console.log("products refreshed");
    } catch (e) {
        console.log("offline");
    }
}, 300000);

This refreshes the product list every 5 minutes.

The workflow:

Cache Products
↓
Background Update
↓
Available Offline

IX. Offline Data Architecture

Browser database: IndexedDB

Typical structure:

IndexedDB
 ├─ products
 ├─ orders
 ├─ syncQueue

Functions:

products: Product caching
orders: Offline order storage
syncQueue: Sync queue for pending operations

Sync workflow:

Place Order Offline
↓
Store in IndexedDB
↓
Network Restored
↓
POST /api/orders
↓
Sync Completed

X. Advantages of PicoServer + PWA

Regular PWA Architecture:

Browser
↓
Internet
↓
Remote Server

PicoServer Architecture:

Browser
↓
PicoServer (Local)
↓
MAUI
↓
SQLite

Advantages:

Local API
API endpoint: http://127.0.0.1/api
Latency: < 1ms
Fully Offline
All system components run locally:
- UI
- API
- DB
Cross-Platform
MAUI supports multiple platforms:
- Windows
- Android
- iOS
- Mac

XI. Final System Structure

The complete system architecture:

        PWA Web Admin
              │
       Service Worker
              │
     ┌────────┴────────┐
     │                 │
 Cache Storage     IndexedDB
     │                 │
     └────────┬────────┘
              │
          PicoServer
              │
            API
              │
            MAUI
              │
          SQLite

One-sentence summary:
PicoServer + PWA = Local Web Application Platform

XII. Additional Code

Due to space limitations, some code is not fully displayed. Please refer to the synchronized source code in the project: https://github.com/densen2014/MauiPicoAdmin

Partial code from MauiPicoAdmin\Resources\Raw\wwwroot\search.html:

<input id="productIdInput" type="text" class="form-control form-control-sm" style="width:120px;" placeholder="Enter Product ID" oninput="loadProducts(this.value)" autocomplete="off">
<div class="card-body">
<table id="table">
<tbody></tbody>
</table>
<script>
        async function loadProducts(id) {
            id = (id || '').trim();
            if (!id) {
                document.querySelector("#table tbody").innerHTML = "";
                return;
            }
            document.getElementById("spinner").style.display = "block";
            try {
                let res = await fetch(`/api/product/detail?id=${encodeURIComponent(id)}`);
                let json = await res.json();
                let p = json.data || [];
                let tbody = document.querySelector("#table tbody");
                tbody.innerHTML = "";
                let row = `
                            <tr>
                                <td>${p.id}</td>
                                <td>${p.name}</td>
                                <td>${p.price}</td>
                            </tr>
                        `;
                tbody.innerHTML += row;
            } catch (e) {
                document.querySelector("#table tbody").innerHTML = `<tr><td colspan='3' class='text-danger'>Failed to load</td></tr>`;
            }
            document.getElementById("spinner").style.display = "none";
        } 
</script>

Next Article Preview

Next article summary:
Complete App Web Shell Architecture

Practical Combat of MAUI Embedded Web Architecture (8) Plug-in API Architecture: Automatic Controller Discovery and Modular Expansion

ben — Sun, 05 Apr 2026 02:39:34 +0000

PicoServer
Source Code URL:
https://github.com/densen2014/MauiPicoAdmin

In the previous articles of this series, we have gradually built a complete embedded web service architecture based on MAUI + PicoServer, which includes the following components:

PicoServer local web server
REST API interface system
Web Admin management backend
Permission authentication system
WebSocket real-time communication

As the system continues to expand, a new architectural challenge emerges:

When the number of APIs keeps growing, how can we make the server automatically discover and register APIs instead of manually registering each interface?

For example, the following API modules may emerge in the system one after another:

/api/system/*
/api/device/*
/api/order/*
/api/storage/*
/api/user/*

If every API needs to be registered manually like this:

api.AddRoute("/api/system/info", SystemInfo, "GET");
api.AddRoute("/api/device/start", DeviceStart, "POST");
api.AddRoute("/api/order/list", OrderList, "GET");
api.AddRoute("/api/storage/add", StorageAdd, "POST");

When the number of interfaces reaches dozens or even hundreds:
The server startup code will become extremely cluttered.

Therefore, in this article, we will implement a more elegant architecture:
API Architecture with Automatic Controller Discovery

Core capabilities include:

Marking Controllers with [ApiController]
Marking APIs with [ApiRoute]
Scanning Controllers via reflection
Automatic API registration
Modular interface system

The final development experience will be as follows:

[ApiController]
public class DeviceController
{
    [ApiRoute("/api/device/list","GET")]
    public object List()
    {
        return DeviceManager.GetDevices();
    }
}

There is no longer a need to manually register APIs.

When the server starts, it will automatically complete the following steps:

Scan Controllers
↓
Scan API methods
↓
Automatically register Routes

I. Target Architecture

The final server structure is as follows:

MAUI App
   │
   └── PicoServer
          │
          ├── API Core
          │
          ├── Controller Scanner
          │
          └── Controllers
                 ├── SystemController
                 ├── DeviceController
                 ├── OrderController
                 └── StorageController

Server startup process:

Scan Controllers
↓
Scan APIs
↓
Automatically register Routes

II. Define the ApiController Attribute

First, define the Attribute for marking Controllers:

[AttributeUsage(AttributeTargets.Class)]
public class ApiControllerAttribute : Attribute
{
}

Usage:

[ApiController]
public class DeviceController
{
}

During scanning, the server will only load classes marked with [ApiController].

III. Define the API Route Attribute

Describe each API using an Attribute:

namespace MauiPicoAdmin;

[AttributeUsage(AttributeTargets.Method)]
public class ApiRouteAttribute : Attribute
{
    public string Path { get; }
    public string? Method { get; } 

    public ApiRouteAttribute(string path)
    {
        Path = path;
    }

    public ApiRouteAttribute(string path, string? method)
    {
        Path = path;
        Method = method;
    }
}

Usage:

[ApiRoute("/api/system/info","GET")]
public object Info()
{
    return new
    {
        version = "1.0",
        time = DateTime.Now
    };
}

IV. Controller Example

A complete Controller implementation:

[ApiController]
public class DeviceController
{
    [ApiRoute("/api/device/list","GET")]
    public object List()
    {
        return new
        {
            count = 5
        };
    }

    [ApiRoute("/api/device/start","POST")]
    public object Start()
    {
        return new
        {
            ok = true
        };
    }
}

Once the Controller is written, the API definition is complete.

V. Automatically Scan Controllers

Scan the assembly when the server starts:

var asm = Assembly.GetExecutingAssembly();

var controllers = asm.GetTypes()
    .Where(t => t.GetCustomAttribute<ApiControllerAttribute>() != null);

This way, we can find all classes marked with [ApiController].

VI. Instantiate Controllers

Iterate through the discovered Controllers:

foreach (var type in controllers)
{
    var controller = Activator.CreateInstance(type);

    RegisterController(controller);
}

VII. Scan API Methods

Scan the methods within each Controller:

void RegisterController(object controller)
{
    var methods = controller.GetType().GetMethods();

    foreach (var method in methods)
    {
        var route = method.GetCustomAttribute<ApiRouteAttribute>();

        if (route == null)
            continue;

        RegisterApi(route, controller, method);
    }
}

This step finds all methods marked with [ApiRoute].

VIII. Automatically Register APIs

Unifiedly register interfaces in PicoServer using api.AddRoute():

The implementation code is as follows:

void RegisterApi(ApiRouteAttribute route, object controller, MethodInfo method)
{
    Func<HttpListenerRequest, HttpListenerResponse, Task> handler = (request, response) =>
    {
        var result = method.Invoke(controller, new object[] { request, response });
        return result as Task ?? Task.CompletedTask;
    };
    api.AddRoute(route.Path, handler, route.Method);
}

This automatically converts Controller methods into API Routes.

IX. Complete Runtime Process

Execute the following method when the server starts:

ScanControllers();

The complete process is as follows:

Scan the assembly
↓
Find [ApiController] classes
↓
Scan methods
↓
Find [ApiRoute] methods
↓
Call api.AddRoute()
↓
Complete API registration

Eventually, all APIs are loaded automatically.

X. Final Development Experience

When developing APIs, you only need to write Controllers:

[ApiController]
public class OrderController
{
    [ApiRoute("/api/order/list","GET")]
    public object List()
    {
        return OrderService.GetOrders();
    }
}

After the server starts, the API GET /api/order/list is registered automatically.

Developers no longer need to manually write any api.AddRoute(...) code, making the code extremely concise.

XI. Architectural Advantages

This API architecture brings the following benefits:

1. Automatic API Registration

Eliminates the need for a large number of api.AddRoute(...) code lines.

2. Modular Development

Each module has its own independent Controller:

SystemController
DeviceController
OrderController
StorageController
UserController

Resulting in a very clear structure.

3. Simple Expansion

Adding a new API only requires adding a method marked with [ApiRoute], with no need to modify server code.

4. Foundation for Plug-in Architecture

Although this article only scans the current assembly, it can be extended in the future to:

Scan external DLLs
Load Controllers from external assemblies

Thus implementing a true plug-in API system.

XII. Next Article Preview

In the next article, we will continue to upgrade the architecture with:

PicoServer + PWA Offline System

We will implement:

Browser offline operation
Service Worker
Local data caching
Offline Web Admin
MAUI Web Shell

Ultimately building a complete solution that integrates:

Offline Web App
Local API
MAUI Web Shell

A true local web application platform.

Practical Combat of MAUI Embedded Web Architecture (7) PicoServer + WebSocket: Building Real-Time Device Communication and Control Systems

ben — Sun, 05 Apr 2026 02:37:22 +0000

PicoServer
Source Code URL:
https://github.com/densen2014/MauiPicoAdmin

I. Why WebSocket Is Needed

In the previous articles, we have implemented a complete architecture:

Web Admin UI
      ↓
PicoServer REST API
      ↓
MAUI Service
      ↓
SQLite / Device

Web APIs are suitable for:

CRUD operations
Request-response workflows

However, for real-time systems, REST APIs have obvious limitations.

For example:

Scenario	Issues with REST API
Device status changes	Requires continuous polling
Real-time logging	High latency
Device control	Slow interaction

Take browsers as an example: they send a request to /api/device/status every second. This is called Polling.

Problems with polling:

High server load
High latency
Poor user experience

The solution is WebSocket.

II. What Is WebSocket

WebSocket is a persistent connection communication protocol.

Communication mode:

Browser
   ⇅
WebSocket
   ⇅
Server

Key features:

Feature	Description
Bidirectional communication	Both client and server can send data
Persistent connection	No need to repeatedly establish connections
Real-time performance	Millisecond-level latency

Therefore, it is ideal for:

Device control
Real-time logging
Message pushing
IoT systems

III. System Architecture Upgrade

After integrating WebSocket, the architecture becomes:

           Web Admin
             │
      ┌──────┴───────┐
      │              │
 REST API        WebSocket
      │              │
      ▼              ▼
         PicoServer
              │
              ▼
            Service
              │
              ▼
         Device / DB

REST API: Handles CRUD operations
WebSocket: Manages real-time communication and device control

IV. Code Implementation of WebSocket Server

Add a WebSocketManager to PicoServer.

Create the file: Services/WebSocketManager.cs

Sample implementation:

using PicoServer;

public class WebSocketManager
{
    private WebAPIServer? api;

    public void RegisterWebSocket(WebAPIServer api)
    {
        this.api = api;
        api.enableWebSocket = true; 
        api.WsOnConnectionChanged = WsConnectChanged;
        api.WsOnMessage = OnMessageReceived;
    }

    public async Task OnMessageReceived(string clientId, string message, Func<string, Task> reply)
    {
        await reply("Received!");
        var clients = api!.WsGetOnlineClients();
        foreach (var client in clients)
        {
            await api.WsSendToClientAsync(client, $"{clientId} says: {message}");
        }
    } 

    public async Task WsConnectChanged(string clientId, bool connected)
    {
        await api!.WsBroadcastAsync($"{clientId} {connected}");
    }
}

This component implements:

Connection management
Message reception
Message broadcasting

V. Register WebSocket Routes

ws.RegisterWebSocket(api);

Now browsers can connect via:

ws://localhost:8090/ws

VI. Frontend WebSocket Connection

In the Web Admin interface:

const ws = new WebSocket("ws://127.0.0.1:8090/ws");

ws.onopen = () => {
  console.log("WebSocket Connected");
};

ws.onmessage = (event) => {
  console.log("Message:", event.data);
};

ws.onclose = () => {
  console.log("Disconnected");
};

function send() {
  ws.send("hello device");
}

Send messages with:

ws.send("hello device");

VII. Device Control Protocol Design

In practical systems, you need to define a communication protocol. JSON is recommended.

Examples:

Device control:

{
  "type": "device_control",
  "device": "printer",
  "cmd": "start"
}

Device status:

{
  "type": "device_status",
  "device": "printer",
  "status": "running"
}

Log message:

{
  "type": "log",
  "message": "device started"
}

VIII. Server-Side Device Command Handling

Parse WebSocket messages:

var cmd = JsonSerializer.Deserialize<WsCommand>(msg);

switch(cmd.Type)
{
    case "device_control":
        DeviceService.Execute(cmd.Device, cmd.Cmd);
        break;
}

Example:

DeviceService.Execute("printer","start");

IX. Real-Time Device Status Pushing

When device status changes:

await ws.Broadcast(JsonSerializer.Serialize(new
{
    type = "device_status",
    device = "printer",
    status = "running"
}));

The frontend receives the message immediately:

ws.onmessage = e => {
    let msg = JSON.parse(e.data);
    if(msg.type === "device_status")
    {
        updateUI(msg);
    }
}

This enables real-time updates in the flow: Device → Server → Web Admin

Click to expand complete sample code
Click to expand complete backend code

X. Real-Time Logging System

For device logs:

await ws.Broadcast(JsonSerializer.Serialize(new
{
    type="log",
    message="print job started"
}));

Frontend implementation:

if(msg.type==="log"){
   logPanel.append(msg.message)
}

Effect: A real-time log window

XI. Complete Real-Time Architecture

The final system architecture is:

                 Web Admin UI
                /            \
          REST API        WebSocket
              │               │
              ▼               ▼
             PicoServer Core
                    │
                    ▼
                 Services
                    │
          ┌─────────┴─────────┐
          ▼                   ▼
       SQLite              Device

The system's capabilities are now upgraded to include:

Backend management
Real-time communication
Device control
Data storage

XII. Summary of This Article

In this article, we added the following core capabilities to the system:

WebSocket real-time communication
Device control protocol
Real-time log pushing
Status synchronization

The system now integrates:

Web Admin
REST API
WebSocket
Device control

It can be applied to scenarios such as:

IoT systems
Device management platforms
Local control software
Industrial tool systems

Next Article Preview

The next article will take a crucial step in architecture upgrading:

Practical Combat of MAUI Embedded Web Architecture (8)
Plug-In API Architecture: Automatic Controller Discovery and Modular Expansion

We will implement:

Plug-in loading
Module expansion
Dynamic APIs
Module management

Ultimately, we will upgrade the system into a truly scalable local web platform.

Practical Combat of MAUI Embedded Web Architecture (6) PicoServer Web Admin Permission System Design and Authentication Architecture

ben — Sun, 05 Apr 2026 02:33:02 +0000

PicoServer
Source Code URL:
https://github.com/densen2014/MauiPicoAdmin

In the previous articles, we have gradually built a complete PicoServer local Web Admin system, including:

Routing mechanism
REST API architecture
Static file hosting
Web Admin management backend

Up to this point, we already have the following architecture:

Web UI
 ↓
REST API
 ↓
Business Service

However, for any real-world system, there is still one most critical component missing:
Authentication and Authorization System (Auth System)

Without a permission system:

Any user can access the management backend
All APIs can be called directly
The entire system has no security boundaries

Therefore, in this article, we will design a:
complete authentication and authorization architecture suitable for PicoServer

And implement the following features:

Login authentication
Token mechanism
API permission protection
Role-based permission model
API filter
Permission attribute mechanism

Ultimately, we will build a scalable permission system framework.

I. Permission System Architecture Design

In web systems, a permission system usually consists of three layers:

Authentication Identity verification
Authorization Permission control
Permission Model Permission modeling

The relationship between these layers is as follows:

User Login
   ↓
Get Token
   ↓
API Requests Carry Token
   ↓
Server Validates Token
   ↓
Check User Permissions
   ↓
Allow / Deny Access

II. Overall Architecture Design

In PicoServer, we design the following architecture:

             Web Admin UI
                │
                │ fetch API
                ▼
          ┌───────────────────┐
          │  PicoServer       │
          │                   │
          │ Auth Middleware   │
          │       │           │
          │       ▼           │
          │ Permission Filter │
          │       │           │
          │       ▼           │
          │ Controller        │
          │       │           │
          │       ▼           │
          │ Service Layer     │
          └───────────────────┘

Core Idea:
All API requests pass through the authentication middleware first.

III. Token Authentication Mechanism

In a local Web Admin system, Token-based authentication is recommended for the following reasons:

Does not rely on browser sessions
Suitable for REST APIs
Simple to call from the frontend
Low implementation cost

The authentication process is as follows:

User Login
   ↓
Server Generates Token
   ↓
Frontend Stores Token
   ↓
Token is Carried in Each API Request
   ↓
Server Validates Token

IV. Implement the Login Interface

First, implement the login API:
POST /api/login

Request body:

{
  "username":"admin",
  "password":"123456"
}

Login Interface Implementation

public class LoginController
{
    public async Task Login(HttpListenerRequest request, HttpListenerResponse response)
    {
        var body = await new StreamReader(request.InputStream).ReadToEndAsync();

        var login = JsonSerializer.Deserialize<LoginRequest>(body, new JsonSerializerOptions { PropertyNameCaseInsensitive = true });

        if (login != null && login.Username == "admin" && login.Password == "123456")
        {
            var token = TokenService.GenerateToken(login.Username);

            await response.WriteJsonAsync(new
            {
                success = true,
                token = token
            });
        }
        else
        {
            response.StatusCode = 401;

            await response.WriteJsonAsync(new
            {
                success = false,
                message = "Invalid username or password"
            });
        }
    }

    public class LoginRequest
    {
        public string? Username { get; set; }
        public string? Password { get; set; }
    }
}

HttpHelper Tool Correction (from Article 3)
The previous version had a bug where the contentType was not set correctly. The corrected version is as follows, with the method name changed from WriteJson to WriteJsonAsync:

public static class HttpHelper
{
    public static async Task WriteJsonAsync(HttpListenerResponse response, object obj)
    {
        string json = JsonSerializer.Serialize(obj);
        await response.WriteAsync(json, contentType: "application/json");
    }
}

V. Token Service Design

To manage tokens, we create a TokenService:

public class TokenService
{
    static Dictionary<string, UserSession> sessions = new();

    public static string GenerateToken(string username)
    {
        var token = Guid.NewGuid().ToString();

        sessions[token] = new UserSession
        {
            Username = username,
            Role = "admin",
            ExpireTime = DateTime.Now.AddHours(12)
        };

        return token;
    }

    public static UserSession Validate(string token)
    {
        if(!sessions.ContainsKey(token))
            return null;

        var session = sessions[token];

        if(session.ExpireTime < DateTime.Now)
            return null;

        return session;
    }
}

Session Data Structure:

public class UserSession
{
    public string? Username { get; set; }

    public string? Role { get; set; }

    public DateTime ExpireTime { get; set; }
}

VI. Authentication Middleware (Auth Middleware)

To avoid manually validating tokens in every API, we design a unified authentication middleware.

Request flow:

All APIs
   ↓
Auth Middleware
   ↓
Controller

Implementation:

public class AuthMiddleware
{
    public static UserSession? Authenticate(HttpListenerRequest request)
    {
        var token = request.Headers["Authorization"];

        if (string.IsNullOrEmpty(token))
            return null;

        return TokenService.Validate(token);
    }
}

VII. API Filter Mechanism

Furthermore, we can add an API Filter with the following functions:

Automatically intercept unauthorized access
Return unified error responses

Example implementation:

public static async Task<bool> RequireAuth(
    HttpListenerRequest request,
    HttpListenerResponse response)
{
    var session = AuthMiddleware.Authenticate(request);

    if(session == null)
    {
        response.StatusCode = 401;

        await response.WriteJsonAsync(new
        {
            message = "Unauthorized"
        });

        return false;
    }

    return true;
}

VIII. Protect API Interfaces

Now APIs can be written like this:

public async Task GetUserList(HttpListenerRequest request, HttpListenerResponse response)
{
    if(!await RequireAuth(request,response))
        return;

    var users = new[]
    {
        new { id = 1, name = "admin" },
        new { id = 2, name = "operator" }
    };

    await response.WriteJsonAsync(users);
}

This way, all APIs are automatically protected.

IX. Permission Model Design

As the system becomes more complex, a role-based permission model needs to be introduced.

Classic permission model hierarchy:

User
 ↓
Role
 ↓
Permission

Example:

User
 ├─ admin
 └─ operator

Role
 ├─ admin
 └─ viewer

Permission
 ├─ product.view
 ├─ product.edit
 └─ order.manage

APIs can be associated with specific permissions:

/api/product/list → product.view
/api/product/create → product.edit
/api/order/delete → order.manage

The server determines access rights based on the user's role.

X. Permission Attribute Design (Advanced Architecture)

A more advanced design is to use permission attributes (Attribute):

Example:

[RequirePermission("product.view")]
public async Task ProductList()
{
}

Attribute Definition:

public class RequirePermissionAttribute : Attribute
{
    public string Permission { get; }

    public RequirePermissionAttribute(string permission)
    {
        Permission = permission;
    }
}

Before API execution:

Read the attribute
Check permissions
Automatically intercept unauthorized requests

This is the mechanism used in many web frameworks, such as:

ASP.NET Core
Spring Boot
NestJS

XI. Complete Permission System Architecture

The final system architecture is as follows:

MAUI App
   │
   ├── WebView
   │
   └── PicoServer
          │
          ├── Static File Server
          │
          ├── REST API
          │
          ├── Auth Middleware
          │
          ├── Permission Filter
          │
          └── Service Layer

Advantages:

Serverless deployment
Local operation
High performance
Cross-platform compatibility

XII. Additional Code

Due to space limitations, some code is not fully displayed. Please refer to the synchronized source code in the project: https://github.com/densen2014/MauiPicoAdmin

Final Route Registration:

private void RegisterRoutes()
{
    var demo = new DemoController();
    var product = new ProductController();
    var login = new LoginController();
    var user = new UserController();
    api.AddStaticFiles("/", wwwrootPath);
    api.AddRoute("/api/hello", demo.Hello);
    api.AddRoute("/api/time", demo.GetTime);
    api.AddRoute("/api/status", demo.GetStatus);
    api.AddRoute("/api/product/list", product.List);
    api.AddRoute("/api/product/detail", product.Detail); 
    api.AddRoute("/api/login", login.Login); 
    api.AddRoute("/api/user/list", user.GetUserList); 
}

Add Test File: api_test.http
Relevant documentation: https://aka.ms/vs/httpfile

# For more info on HTTP files go to https://aka.ms/vs/httpfile

@hostname=127.0.0.1

### Hello
GET http://{{hostname}}:8090/api/hello

### Time
GET http://{{hostname}}:8090/api/time

### Status
GET http://{{hostname}}:8090/api/status

### Product List
GET http://{{hostname}}:8090/api/product/list

### Product Detail
GET http://{{hostname}}:8090/api/product/detail?id=1

### Login
### Automatically extract response content from the previous request through variables and scripts, and reuse it in the next request
# @name login
POST http://{{hostname}}:8090/api/login
Content-Type: application/json

{
  "username": "admin",
  "password": "123456"
} 

### User List (with token)
GET http://{{hostname}}:8090/api/user/list
Authorization: {{login.response.body.$.token}}

# Response

XIII. Summary of This Article

In this article, we have built a complete PicoServer permission system architecture, implementing the following features:

Login authentication API
Token mechanism
API permission protection
Auth Middleware
API Filter
Role-based permission model
Permission attribute architecture

At this point, our system has been equipped with:
enterprise-level Web Admin infrastructure

Next Article Preview

Next, we will continue to upgrade the system capabilities with:

Practical Combat of MAUI Embedded Web Architecture (7)
Local Database and Data Persistence

We will implement:

SQLite database
ORM data access
Product CRUD APIs
Admin data management
Local data synchronization

Ultimately, we will build:
a fully usable local management system

Practical Combat of MAUI Embedded Web Architecture (5) Building a Complete Web Admin Backend with PicoServer

ben — Sun, 05 Apr 2026 02:29:52 +0000

PicoServer
Source Code URL:
https://github.com/densen2014/MauiPicoAdmin

I. From API Server to Complete Application

In the previous articles, we have gradually built the core capabilities of PicoServer in MAUI:

Article 1
Embed PicoServer local web service in MAUI.

Article 2
Implement PicoServer routing mechanism and API design.

Article 3
Build a scalable REST API architecture including:

Controller
Service
Model

Article 4
Implement static file hosting to enable PicoServer to run web pages.

At this point, our system already has the following components:

Local Web Server
Local REST API
Local Web Frontend

In other words:
The infrastructure of a complete web application is already in place.

Next, we need to do something more important:
Build a truly usable Web Admin management backend

For example:

Product management
Device management
System configuration
Log viewing

The final effect will be similar to this flow:

localhost:8090
↓
Admin Dashboard
↓
API
↓
MAUI Local Logic

II. Web Admin Architecture

Under the PicoServer + MAUI architecture, the structure of a complete backend system is as follows:

                 ┌─────────────────────┐
                 │      Web Admin      │
                 │ Vue / React / UI    │
                 └──────────▲──────────┘
                            │ fetch
                            │
                 ┌──────────┴──────────┐
                 │      PicoServer     │
                 │   Static + REST     │
                 └──────────▲──────────┘
                            │
                     ┌──────┴──────┐
                     │ Controller  │
                     └──────▲──────┘
                            │
                     ┌──────┴──────┐
                     │   Service   │
                     └──────▲──────┘
                            │
                     ┌──────┴──────┐
                     │ MAUI Logic  │
                     └─────────────┘

Core Ideas:

Use web technologies for UI
Use PicoServer for API
Use C# for business logic

This pattern is very common in many systems, such as:

Industrial equipment systems
IoT management platforms
Local control systems
Embedded device backends

III. Choosing an Admin UI Framework

Developing backend interfaces usually does not require starting from scratch. You can directly use mature Admin UI frameworks.

Here are several commonly recommended solutions:

Bootstrap Admin

The simplest solution with the tech stack:

Bootstrap
Chart.js
jQuery

Suitable for:

Lightweight backends
Rapid development

Vue Admin

A common solution with the tech stack:

Vue
Element Plus
Vite

Advantages:

Rich component library
High development efficiency
Mature ecosystem

React Admin

Tech stack:

React
Ant Design

Suitable for:

Complex systems
Large-scale backends

In this series, for simplicity, we will first use:
Native HTML + Bootstrap

It can be upgraded to Vue later.

IV. Creating Admin Pages

Create the following files and directories under the wwwroot folder:

wwwroot
 ├─ index.html
 ├─ product.html
 ├─ css
 └─ js

index.html

<!DOCTYPE html>
<html>

<head>
    <meta charset="utf-8">
    <title>PicoServer Admin</title>
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.2/dist/css/bootstrap.min.css" rel="stylesheet">
</head>

<body class="container">
    <h1 class="mt-4">PicoServer Admin</h1>
    <div class="mt-4">
        <a href="product.html" class="btn btn-primary">
            Product Management
        </a>
    </div>
</body>
</html>

Visit the address:
http://localhost:8090

And you can see the backend homepage.

V. Product Management Page

Create the product.html page with the following structure:

<h2>Product Management</h2>

<button onclick="loadProducts()">
    Load Products
</button>

<table id="table">
    <thead>
        <tr>
            <th>ID</th>
            <th>Name</th>
            <th>Price</th>
        </tr>
    </thead>
    <tbody></tbody>
</table>

VI. Calling API to Load Data

Add the following JavaScript code:

async function loadProducts()
{
    let res = await fetch("/api/product/list");
    let json = await res.json();
    let list = json.data;
    let tbody = document.querySelector("#table tbody");

    tbody.innerHTML = "";

    for(let p of list)
    {
        let row = `
        <tr>
        <td>${p.id}</td>
        <td>${p.name}</td>
        <td>${p.price}</td>
        </tr>
        `;
        tbody.innerHTML += row;
    }
}

At this point, the data flow is as follows:

Page
↓
fetch API
↓
PicoServer
↓
Return JSON
↓
Render Table

VII. API Implementation

Controller

public async Task List(HttpListenerRequest req, HttpListenerResponse res)
{
    var data = service.GetProducts();
    var result = ApiResult.Success(data);
    string json = JsonSerializer.Serialize(result);

    res.ContentType = "application/json";
    await res.WriteAsync(json);
}

Service

public List<object> GetProducts()
{
    return new List<object>
    {
        new { id = 1, name = "Apple", price = 10 },
        new { id = 2, name = "Orange", price = 8 }
    };
}

Complete Page Code

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>PicoServer Admin</title>
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.2/dist/css/bootstrap.min.css" rel="stylesheet">
</head>
<body class="bg-light">
    <div class="container py-5">
        <div class="row justify-content-center">
            <div class="col-lg-8">
                <div class="card shadow-sm">
                    <div class="card-header bg-primary text-white d-flex justify-content-between align-items-center">
                        <h4 class="mb-0">Product Management</h4>
                        <button onclick="loadProducts()" class="btn btn-light btn-sm">
                            <span class="bi bi-arrow-repeat"></span> Load Products
                        </button>
                    </div>
                    <div class="card-body">
                        <div id="spinner" class="text-center my-3" style="display:none;">
                            <div class="spinner-border text-primary" role="status">
                                <span class="visually-hidden">Loading...</span>
                            </div>  
                        </div>
                        <div class="table-responsive">
                            <table id="table" class="table table-striped table-hover align-middle">
                                <thead class="table-primary">
                                    <tr>
                                        <th>ID</th>
                                        <th>Name</th>
                                        <th>Price</th>
                                    </tr>
                                </thead>
                                <tbody></tbody>
                            </table>
                        </div>
                    </div>
                </div>
            </div>
        </div>
    </div>
    <script>
        async function loadProducts() {
            document.getElementById("spinner").style.display = "block";
            let res = await fetch("/api/product/list");
            let json = await res.json();
            let list = json.data;
            let tbody = document.querySelector("#table tbody");
            tbody.innerHTML = "";
            for (let p of list) {
                let row = `
                    <tr>
                        <td>${p.id}</td>
                        <td>${p.name}</td>
                        <td>${p.price}</td>
                    </tr>
                `;
                tbody.innerHTML += row;
            }
            document.getElementById("spinner").style.display = "none";
        }
    </script>
</body>
</html>

VIII. Adding CRUD Functions

Backend systems usually require complete CRUD capabilities, such as:

Add product
Edit product
Delete product
Query product

API Examples

GET /api/product/list
GET /api/product/detail?id=1
POST /api/product/add
POST /api/product/delete

Frontend Calls

fetch("/api/product/add")
fetch("/api/product/delete")

IX. Final Effect of the Admin Backend

After completion, the system structure is as follows:

localhost:8090
Backend Pages:
- Homepage
- Product Management
- System Configuration

Call Flow:

Web UI
   ↓
fetch API
   ↓
PicoServer
   ↓
Controller
   ↓
Service
   ↓
MAUI Logic

At this point, your MAUI application has essentially become:
A complete web application container

X. Why This Architecture Is Powerful

This architecture has significant advantages in many scenarios, such as:

1. Industrial Equipment Systems

Equipment control
Parameter configuration
Log viewing

2. IoT Systems

Device management
Data display
Remote control

3. Local Management Backends

Inventory systems
POS systems
Offline business systems

4. Cross-Platform UI

The same set of Web UI can run on:

Windows
Android
iOS
Mac
Linux

XI. WebView App Shell

In MAUI, you can directly embed the following code:

<WebView Source="http://127.0.0.1:8090" />

Application Structure:

MAUI App
   ↓
WebView
   ↓
PicoServer
   ↓
Web Admin

This is the Local Web Shell architecture.

Many desktop applications actually use a similar architecture, such as:

VS Code
Slack
Notion

XII. Summary of This Article

In this article, we have achieved an important milestone of the entire series:
Building a complete Web Admin management backend

The implemented contents include:

Admin Dashboard page
Product management CRUD example
API and frontend interaction
Complete Web Admin architecture

At this point, our MAUI application has the following capabilities:

Local Web Server
Local API
Local Web UI
Complete Admin system

Next Article Preview

Next, we will continue to upgrade the system with:

Practical Combat of MAUI Embedded Web Architecture (6)
Web Admin Permission System and Login Authentication

We will implement:

User login
Token authentication
Permission control
Login interception
API authentication

Ultimately, we will build a truly usable Admin management system.

Practical Combat of MAUI Embedded Web Architecture (4) PicoServer Static File Hosting and Integration with Vue/React Frontends

ben — Sun, 05 Apr 2026 02:26:01 +0000

PicoServer
Source Code URL:
https://github.com/densen2014/MauiPicoAdmin

In the previous articles, we have implemented the core capabilities of PicoServer in MAUI:

Embedding a local HTTP service in a .NET MAUI application
Building local REST APIs with PicoServer
Implementing a layered Controller/Service architecture

At this point, our application already has the capability of a local API Server.

However, a complete application system usually consists of two parts:

Backend APIs
Frontend interfaces

Having only APIs is still not enough to build a complete application.

Therefore, in this article, we will further upgrade PicoServer to equip it with static file hosting capabilities.

In other words, we will enable the MAUI application to directly run web frontends such as:

HTML
Vue
React
Admin Dashboard

Ultimately, we will implement a complete local Web Admin system.

The overall architecture is as follows:

Browser / WebView
        │
        ▼
 http://localhost:8090
        │
        ▼
     Web Admin
        │
   fetch API
        │
        ▼
    PicoServer
        │
        ▼
    MAUI Business Logic

I. What is Static File Hosting?

Static file hosting means that the server directly returns files. For example:

URL	File Returned
/	index.html
/css/app.css	CSS file
/js/app.js	JavaScript file

For example, when accessing:
http://127.0.0.1:8090/index.html

The server will read the file:
wwwroot/index.html

Then return it to the browser.

This mode is exactly the same as traditional web servers (Nginx / Apache / ASP.NET).

II. Create a Static Resource Directory

First, create a directory in the MAUI project:
Resources\Raw\wwwroot

Recommended directory structure:

wwwroot
 ├─ index.html
 ├─ css
 │   └─ app.css
 ├─ js
 │   └─ app.js
 └─ images

This directory name is very common in web frameworks, such as:

ASP.NET Core
Spring Boot
Node.js

All use a similar directory as the static file directory.

III. Create a Test Page

Create a simple page:

index.html

<!DOCTYPE html>
<html>

<head>
<meta charset="utf-8">
<title>PicoServer Admin</title>
</head>

<body>

<h1>PicoServer Web Admin</h1>

<button onclick="loadTime()">Get Server Time</button>

<p id="result"></p>

<script>

async function loadTime()
{
    let res = await fetch("/api/time");
    let data = await res.json();

    document.getElementById("result").innerText = data.data.time;
}

</script>

</body>
</html>

This page will call the API we implemented earlier:
/api/time

IV. Implement Static File Reading

Place the static file (index.html) in the project directory Resources\Raw\wwwroot.

The following steps are required to implement the file system:

Define the path

public readonly string wwwrootPath = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "wwwroot");

Edit the project file to automatically generate wwwroot/filelist.txt before each Debug/Build. The file contains the relative paths of all files under wwwroot. There is no need to manually maintain the list—all packaged static files can be automatically released when the app starts.

<!-- Automatically generate wwwroot/filelist.txt before each Debug. The file contains relative paths of all files in the wwwroot directory. -->
<Target Name="GenerateWwwrootFileList" BeforeTargets="Build">
    <ItemGroup>
      <WwwrootFiles Include="Resources\Raw\wwwroot\**\*" />
    </ItemGroup>
    <WriteLinesToFile
      File="Resources\Raw\wwwroot\filelist.txt"
      Lines="@(WwwrootFiles->'%(RecursiveDir)%(Filename)%(Extension)')"
      Overwrite="true" />
</Target>

V. Release Resources to Writable Folder

Since we are using MAUI, except for the Windows platform which allows direct access, other platforms require manual release of resources to a writable folder.

Add the following method: All packaged static files can be automatically released when the app starts.

public PicoServerHost()
{
    EnsureWwwrootExistsAsync().Wait(); // Add this line
    RegisterRoutes();
    api.StartServer();
}

/// <summary>
/// Automatically generate wwwroot/filelist.txt before each Debug/Build. The file contains relative paths of all files under wwwroot. No need to manually maintain the list—all packaged static files can be automatically released when the app starts.
/// </summary>
/// <returns></returns>
private async Task EnsureWwwrootExistsAsync()
{
    string wwwrootPath = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "wwwroot");
    if (!Directory.Exists(wwwrootPath))
    {
        Directory.CreateDirectory(wwwrootPath);
        string[] files;
        try
        {
            using var listStream = await FileSystem.OpenAppPackageFileAsync("wwwroot/filelist.txt");
            using var reader = new StreamReader(listStream);
            var content = await reader.ReadToEndAsync();
            files = content.Split('\n', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
        }
        catch
        {
            files = new[] { "index.html" };
        }
        foreach (var file in files)
        {
            string destPath = Path.Combine(wwwrootPath, file);
            string packagePath = $"wwwroot/{file}";
            string destDir = Path.GetDirectoryName(destPath)!;
            if (!Directory.Exists(destDir)) Directory.CreateDirectory(destDir);
            using var stream = await FileSystem.OpenAppPackageFileAsync(packagePath);
            using var fileStream = File.Create(destPath);
            await stream.CopyToAsync(fileStream);
        }
    }
}

VI. Register Static Routes

api.AddStaticFiles("/", wwwrootPath);

Now, accessing the address:
http://127.0.0.1:8090

will automatically load the file:
wwwroot/index.html

VII. Collaboration Between APIs and Frontend

Now the entire system structure becomes:

Browser
   ↓
index.html
   ↓
fetch("/api/time")
   ↓
PicoServer API
   ↓
MAUI Local Logic

For example:

fetch("/api/product/list")

calls the interface:
/api/product/list

This approach has several advantages:

1. No Cross-Origin Issues

Because both the pages and APIs are hosted on the same server:
localhost:8090

2. Local Offline Operation

The entire system—including HTML, JS, APIs, and database—can run locally without relying on an external network.

3. UI Development with Web Technologies

You can directly use web technologies such as:

Vue
React
Bootstrap
Admin Template

to develop backend interfaces.

VIII. Hosting Vue/React Frontends

If you use a frontend framework such as Vue, the build process will generate a dist directory with the following structure:

dist
 ├─ index.html
 ├─ assets
 └─ js

You only need to copy all contents from the dist directory to the wwwroot directory.

Then accessing the address:
http://localhost:8090

will launch the entire Admin system.

IX. Static Resource Caching Optimization (Recommended)

In web servers, static resources can usually be cached. For example, resources like CSS, JS, and images can have a cache header set:

response.Headers.Add("Cache-Control", "public,max-age=3600");

This means the browser will cache the resources for 1 hour, which reduces repeated requests and improves page loading speed.

Recommended caching strategy:

Resource Type	Cache Duration
HTML	No caching
CSS / JS	1 hour
Images	1 day

X. WebView Shell Mode

In MAUI, you can use WebView to open local pages:

<WebView Source="http://127.0.0.1:8090/index.html" />

At this point, the application structure becomes:

MAUI App
   ↓
WebView
   ↓
localhost:8090
   ↓
PicoServer
   ↓
API

This architecture is called Local Web Shell, and it has the following advantages:

UI developed with web technologies
Logic implemented with C#
Cross-platform compatibility

Add a new page: Pages\WebViewPage.xaml

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="MauiPicoAdmin.Pages.WebViewPage"
             Title="WebView">
    <WebView Source="http://127.0.0.1:8090/index.html" />
</ContentPage>

Edit AppShell.xaml to add a route

<ShellContent
    Title="WebView"
    Icon="{StaticResource IconDashboard}"
    ContentTemplate="{DataTemplate pages:WebViewPage}"
    Route="webview" />

XI. Complete Architecture

Now the entire system has evolved into a complete web architecture:

            ┌───────────────────────┐
            │       Web UI          │
            │ Vue / React / Admin   │
            └──────────▲────────────┘
                       │ fetch
                       │
            ┌──────────┴────────────┐
            │      PicoServer       │
            │   Static + REST API   │
            └──────────▲────────────┘
                       │
                ┌──────┴──────┐
                │ Controller  │
                └──────▲──────┘
                       │
                ┌──────┴──────┐
                │  Service    │
                └──────▲──────┘
                       │
                ┌──────┴──────┐
                │  MAUI Logic │
                └─────────────┘

This pattern is commonly used in scenarios such as:

Industrial device management systems
Local management backends
Embedded device web UIs
Offline business systems

XII. Summary of This Article

In this article, we added a key capability to PicoServer: static file hosting.

The newly added capabilities include:

Static file server
HTML page hosting
Frontend calling local APIs
Vue/React frontend integration
WebView shell architecture

At this point, our MAUI application has evolved into a local Web Admin system.

Next Article Preview

In the next article, we will continue to upgrade the system with:

Practical Combat of MAUI Embedded Web Architecture (5)
Building a Complete Web Admin Management Backend

Content will include:

Admin UI framework selection
Product management CRUD example
API and page interaction
Table, pagination, and form design

Ultimately, we will implement a truly usable local backend management system.

Practical Combat of MAUI Embedded Web Architecture (3)Building a Scalable PicoServer REST API Framework

ben — Sun, 05 Apr 2026 02:21:20 +0000

PicoServer
Source Code URL:
https://github.com/densen2014/MauiPicoAdmin

I. From Simple APIs to a Scalable Architecture

In the previous article Practical Combat of MAUI Embedded Web Architecture (II), we have successfully built multiple PicoServer APIs, such as:

/api/time
/api/product/list
/api/product/detail

These interfaces are already capable of:

Handling HTTP requests
Returning JSON data
Supporting simple parameter reading

For example:
Access address: http://127.0.0.1:8090/api/product/list

Response:

{
  "code":0,
  "message":"ok",
  "data":[]
}

This means our MAUI application has been equipped with local REST API service capabilities.

However, as the number of interfaces grows, new problems will gradually emerge:

All APIs are written in a single class
HTTP logic is mixed with business logic
Inconsistent response formats
Error handling becomes difficult to maintain

For example:

class PicoAdmin
{
    ProductList()
    ProductDetail()
    ProductAdd()
    ProductDelete()
}

When the number of interfaces reaches:

50+
100+
200+

The code will become difficult to maintain.

Therefore, this article will perform an architecture upgrade on PicoServer.

The goal is to build a:
scalable local REST API framework structure

Core objectives include:

API modularization
Controller/Service layered architecture
Unified response structure
Unified exception handling
Clear project structure

II. Core Architecture of the REST API Framework

The upgraded API architecture is as follows:

HTTP Request
      │
      ▼
   PicoServer
      │
     Router
      │
   Controller
      │
    Service
      │
Data / Device / Logic

Responsibilities of each layer:

Layer	Function
Router	Route distribution
Controller	HTTP request handling
Service	Business logic processing
Data / Device	Data or device operations

This structure is very similar to common web frameworks (e.g., ASP.NET Core).

III. Recommended Project Directory Structure

To make the API more maintainable, the following directory structure can be adopted:

Server
 ├─ Controllers
 │   ├─ ProductController.cs
 │   └─ SystemController.cs
 │
 ├─ Services
 │   └─ ProductService.cs
 │
 ├─ Models
 │   └─ ApiResult.cs
 │
 └─ PicoServerHost.cs

Directory responsibility description:

Directory	Function
Controllers	API route handling
Services	Business logic implementation
Models	Data models definition
PicoServerHost	Server startup and route registration

This structure ensures clear, modularized code.

IV. Unified API Response Structure

In an API system, a unified response format is extremely important.

First, we define a response model:

ApiResult.cs

public class ApiResult
{
    public int Code { get; set; }
    public string Message { get; set; }
    public object Data { get; set; }

    public static ApiResult Success(object data)
    {
        return new ApiResult
        {
            Code = 0,
            Message = "ok",
            Data = data
        };
    }

    public static ApiResult Error(string msg)
    {
        return new ApiResult
        {
            Code = 1,
            Message = msg
        };
    }
}

Unified JSON response format:

{
  "code":0,
  "message":"ok",
  "data":{}
}

Advantages:

Unified front-end parsing
Simplified error handling
Standardized API structure

V. Service Layer (Business Logic)

Business logic should be separated from HTTP processing.

Create:

ProductService.cs

public class ProductService
{
    public List<object> GetProducts()
    {
        return new List<object>
        {
            new { id = 1, name = "Apple", price = 10 },
            new { id = 2, name = "Orange", price = 8 }
        };
    }

    public object GetProduct(string id)
    {
        return new { id = id, name = "Demo Product", price = 100 };
    }
}

Responsibilities:

Controller → calls Service
Service → processes business logic

Benefits:

Reusable business logic
Simpler Controllers
Easier maintenance and expansion

VI. Controller Layer (API Entry)

The Controller is responsible for:

Receiving HTTP requests
Reading parameters
Calling Services
Returning JSON

Create:

ProductController.cs

public class ProductController
{
    private ProductService service = new ProductService();

    public async Task List(HttpListenerRequest request, HttpListenerResponse response)
    {
        var data = service.GetProducts();

        var result = ApiResult.Success(data);

        string json = JsonSerializer.Serialize(result);

        response.ContentType = "application/json";
        await response.WriteAsync(json);
    }

    public async Task Detail(HttpListenerRequest request, HttpListenerResponse response)
    {
        string id = request.QueryString["id"];

        var data = service.GetProduct(id);

        var result = ApiResult.Success(data);

        string json = JsonSerializer.Serialize(result);

        response.ContentType = "application/json";
        await response.WriteAsync(json);
    }
}

The responsibilities of the Controller are very clear:

HTTP Request
      ↓
Read Parameters
      ↓
Call Service
      ↓
Return JSON

VII. Unified Route Registration

Next, create the server startup class:

PicoServerHost.cs

public class PicoServerHost
{
    private readonly WebAPIServer api = new WebAPIServer();

    public PicoServerHost()
    {
        RegisterRoutes();
        api.StartServer();
    }

    private void RegisterRoutes()
    {
        var product = new ProductController();

        api.AddRoute("/api/product/list", product.List);
        api.AddRoute("/api/product/detail", product.Detail);
    }
}

The complete call flow becomes:

HTTP Request
      ↓
PicoServer Router
      ↓
Controller
      ↓
Service
      ↓
Data / Device

This structure is already very close to a lightweight web framework.

VIII. Unified JSON Output Utility

To make Controllers more concise, we can encapsulate a utility method.

public static class HttpHelper
{
    public static async Task WriteJson(HttpListenerResponse response, object obj)
    {
        string json = JsonSerializer.Serialize(obj);
        await response.WriteAsync(json, contentType: "application/json");
    }
}

Then the Controller can be written as:

await HttpHelper.WriteJson(response, ApiResult.Success(data));

The code becomes much cleaner.

IX. Unified Exception Handling

In an API system, it is recommended to capture exceptions uniformly:

try
{
    var data = service.GetProducts();
    await HttpHelper.WriteJson(response, ApiResult.Success(data));
}
catch(Exception ex)
{
    await HttpHelper.WriteJson(response, ApiResult.Error(ex.Message));
}

This ensures that:

APIs always return JSON
No HTML error pages will appear
Frontends can handle errors uniformly

Finally, remove the class PicoAdmin from MauiProgram.cs, and change the initialization new PicoAdmin() to:

var picoAdmin = new PicoServerHost(); // Instantiate PicoServerHost to start PicoServer
var picoAdmin = new PicoServerHost();

X. Complete Upgraded Architecture

After the transformation in this article, the overall system structure is as follows:

Browser / WebView
        ↓
     HTTP
        ↓
    PicoServer
        ↓
     Router
        ↓
    Controller
        ↓
     Service
        ↓
   Data / Device

Advantages:

Clear API structure
Modular architecture
Easy to extend
Easy to maintain

At this point, we have built a:
lightweight embedded REST API framework

XI. Further Expansion Capabilities

Based on the current architecture, many additional capabilities can be extended, such as:

Middleware system
Logging
Authentication
Request filtering
CORS
Token-based login system
- /api/login
- /api/user/info
Web Admin backend

Integrate with frontend frameworks:

Vue
React
Admin Dashboard

To implement a complete management system.

XII. Summary of This Article

In this article, we completed the architecture upgrade of the PicoServer API.

New capabilities added:

API layered architecture
Controller/Service architecture
Unified JSON response
Unified route registration
Exception handling mechanism

At this point, our MAUI application has been equipped with:
a scalable local REST API service framework

This also serves as the foundation for building the Web Admin backend in subsequent steps.

Next Article Preview

The next article will cover a very critical part:

Practical Combat of MAUI Embedded Web Architecture (IV)
Static File Hosting and Frontend Framework Integration

We will implement:

Hosting HTML/CSS/JS files
Hosting Vue/React build artifacts
Setting default homepage
Building a true local Web Admin system

The final architecture will be:

Browser
   ↓
localhost:8090
   ↓
Web Admin UI
   ↓
PicoServer API
   ↓
MAUI Local Logic

Practical Combat of MAUI Embedded Web Architecture (2)PicoServer Routing Mechanism and API Design

ben — Sun, 05 Apr 2026 02:17:49 +0000

PicoServer
Source Code URL:
https://github.com/densen2014/MauiPicoAdmin

I. Overall Architecture

After embedding PicoServer in a .NET MAUI application, the following embedded web architecture can be formed:

                Browser / WebView
                       │
                    HTTP
                       │
                ┌────────────┐
                │ PicoServer │
                └────────────┘
                       │
        ┌──────────────┼──────────────┐
        │                             │
     REST API                     Web Admin
        │                             │
        └──────────────┬──────────────┘
                       │
                   Service Layer
                       │
                    MAUI App

In this architecture:

PicoServer is responsible for handling HTTP requests.
REST API provides data interfaces.
Web Admin offers an administration interface.
Service Layer takes charge of business logic.
MAUI App manages device capabilities and local functions.

This pattern enables a mobile or desktop application to be equipped with web server capabilities simultaneously.

II. From Hello PicoServer to API Server

In the previous article Practical Combat of MAUI Embedded Web Architecture (I), we have completed the basic environment setup:

Embed PicoServer in MAUI
Launch the local HTTP service
Access via browser: http://127.0.0.1:8090
Response received:

   Hello PicoServer

This indicates that our application has gained the capability of a local web server.

However, in real-world projects, simply returning a string is far from enough.

A truly usable local web service typically requires:

REST API
JSON data interfaces
Device control interfaces
Local web administration backend

Therefore, this article will focus on:
The routing mechanism and API design methods of PicoServer

and upgrade the sample server into a truly usable local API service.

III. What is a Route?

In a web server, a Route is used to define:
The mapping relationship between URLs and handler functions.

For example:

URL	Processing Logic
/	Homepage
/api/time	Return server time
/api/device/list	Return device list

When a browser accesses the address:
http://127.0.0.1:8090/api/time

The server processing flow is as follows:

Browser
   │
HTTP Request
   │
/api/time
   │
PicoServer Router
   │
Handler Method
   │
JSON Response

Thus, the routing system is one of the core components of a web service.

IV. Basic Usage of PicoServer Routing

In the sample from the first article, we already used the simplest route:

MyAPI.AddRoute("/", Hello);

The complete code is as follows:

public class PicoAdmin
{
    private readonly WebAPIServer MyAPI = new WebAPIServer();

    public PicoAdmin()
    {
        MyAPI.AddRoute("/", Hello);
        MyAPI.StartServer();
    }

    private async Task Hello(HttpListenerRequest request, HttpListenerResponse response)
    {
        await response.WriteAsync("Hello PicoServer");
    }
}

Route mapping relationship:
/ → Hello()

When accessing /, the Hello() method will be executed.

V. Adding Multiple API Routes

In practical projects, we usually need multiple APIs, such as:

Get server time
Query system status
Retrieve device list

Multiple routes can be defined like this:

public PicoAdmin()
{
    MyAPI.AddRoute("/", Hello);
    MyAPI.AddRoute("/api/time", GetTime);
    MyAPI.AddRoute("/api/status", GetStatus);

    MyAPI.StartServer();
}

Implement the corresponding interfaces:

private async Task GetTime(HttpListenerRequest request, HttpListenerResponse response)
{
    var time = DateTime.Now.ToString();
    await response.WriteAsync(time);
}

private async Task GetStatus(HttpListenerRequest request, HttpListenerResponse response)
{
    await response.WriteAsync("Server Running");
}

Access address:
http://127.0.0.1:8090/api/time

Sample response:

2026/3/5 14:30:12

VI. Designing RESTful APIs

Modern web systems usually adopt RESTful APIs.

For example:

API	Function
GET /api/product/list	Product list
GET /api/product/detail?id=1	Product details
POST /api/product/add	Add new product

This design has the following advantages:

Clear interface semantics
Scalable structure
Convenient for front-end invocation

It can be designed in PicoServer like this:

MyAPI.AddRoute("/api/product/list", ProductList);
MyAPI.AddRoute("/api/product/detail", ProductDetail);

VII. Returning JSON Data

Practical APIs usually return JSON data instead of simple strings.

For example:

{
  "code": 0,
  "message": "ok",
  "data": {
    "time": "2026-03-05 14:30:00"
  }
}

It can be implemented in C# like this:

private async Task GetTime(HttpListenerRequest request, HttpListenerResponse response)
{
    var result = new
    {
        code = 0,
        message = "ok",
        data = new
        {
            time = DateTime.Now
        }
    };

    string json = System.Text.Json.JsonSerializer.Serialize(result);

    response.ContentType = "application/json";
    await response.WriteAsync(json);
}

Access address:
http://127.0.0.1:8090/api/time

Response received:

{
  "code":0,
  "message":"ok",
  "data":{
    "time":"2026-03-05T14:30:00"
  }
}

With this, a standard REST API is completed.

VIII. Reading GET Parameters

Many APIs need to read request parameters, such as:
/api/product/detail?id=1001

Parameters can be obtained like this:

private async Task ProductDetail(HttpListenerRequest request, HttpListenerResponse response)
{
    string id = request.QueryString["id"];

    var result = new
    {
        id = id,
        name = "Demo Product",
        price = 100
    };

    string json = JsonSerializer.Serialize(result);

    response.ContentType = "application/json";
    await response.WriteAsync(json);
}

Access address:
http://127.0.0.1:8090/api/product/detail?id=1001

Response received:

{
  "id":"1001",
  "name":"Demo Product",
  "price":100
}

IX. Product List API Example

private async Task ProductList(HttpListenerRequest request, HttpListenerResponse response)
{
    var products = new[]
    {
        new { id = "1", name = "Demo Product 1", price = 100 },
        new { id = "2", name = "Demo Product 2", price = 200 },
        new { id = "3", name = "Demo Product 3", price = 300 }
    };

    var result = new
    {
        code = 0,
        message = "ok",
        data = products
    };

    string json = JsonSerializer.Serialize(result);

    response.ContentType = "application/json";
    await response.WriteAsync(json);
}

Access address:
http://127.0.0.1:8090/api/product/list

Response received:

{
  "code": 0,
  "message": "ok",
  "data": [
    { "id": "1", "name": "Demo Product 1", "price": 100 },
    { "id": "2", "name": "Demo Product 2", "price": 200 },
    { "id": "3", "name": "Demo Product 3", "price": 300 }
  ]
}

X. API Routing Design Recommendations

When designing local APIs, it is recommended to follow these rules:

1. Unified API Prefix

It is recommended to use a unified prefix:
/api/*

Examples:

GET /api/product/list
GET /api/product/detail?id=1
POST /api/product/add
DELETE /api/product/delete?id=1

HTTP Method Description:

GET Query
POST Create
PUT Update
DELETE Delete

2. Unified Response Structure

It is recommended to use a unified JSON response format:

{
  "code":0,
  "message":"ok",
  "data":{}
}

Advantages:

Unified front-end processing
Simple error handling
Clear interface specifications

3. API Module Grouping

It is recommended to group APIs by business modules:

/api/system/*
/api/device/*
/api/product/*

This keeps the interface structure clear and easy to maintain.

XI. Typical Application Scenarios of Local APIs

When an HTTP server runs inside an app, many interesting architectural patterns can be implemented.

Local Web Admin

Browser
   ↓
localhost:8090
   ↓
PicoServer API
   ↓
MAUI Local Logic

WebView + Local API

WebView Page
     ↓
fetch("/api/product/list")
     ↓
PicoServer
     ↓
C# Business Logic

LAN Device Control

Mobile Phone / PC
     ↓
http://192.168.1.100:8090
     ↓
Device Control API

This pattern is very common in the following scenarios:

IoT device management
Desktop software backend
Local console
Debugging interfaces

XII. Summary of This Article

In this article, we have completed three key steps:

Understanding the PicoServer routing mechanism
Building multiple API interfaces
Returning standard JSON data

So far, we have upgraded the initial
Hello PicoServer
to
a truly usable local REST API service.

Next Article Preview

In the next article, we will continue to upgrade the architecture with:
Practical Combat of MAUI Embedded Web Architecture (III): Building a Scalable PicoServer REST API Framework

Content will include:

Controller structure design
Service layer architecture
Unified API response model
Global exception handling
Logging system

The ultimate goal is to build a scalable embedded API framework.

Series Articles

Embedding PicoServer in MAUI
PicoServer Routing Mechanism and API Design
Building a Scalable REST API Framework
Static File Hosting and Frontend Integration
Building a Web Admin Backend
Login Authentication and Permission System
LAN Access and Device Management
Local Cache Architecture
PicoServer + PWA Offline System
Complete App Web Shell Architecture

MAUI Embedded Web Architecture Practice (1) Running PicoServer Local Web Service in MAUI Applications

ben — Mon, 09 Mar 2026 13:14:38 +0000

In traditional mobile or desktop applications, the client is usually just a consumer that calls remote APIs.
However, with the development of Hybrid App and web technologies, a new architectural pattern has gradually become popular:

Embedding a Web Server in local applications.

In this way, the application itself can provide HTTP services, such as:

Local REST API
Web Admin management backend
WebView Hybrid App
LAN device control
PWA offline system

In the .NET ecosystem, we can implement this architecture using .NET MAUI + PicoServer.

This series will build a complete MAUI embedded web architecture system through practical hands-on implementation.

Through this series, you will learn to:

Run a local Web Server in MAUI
Build a REST API framework
Develop a Web Admin management backend
Construct a Hybrid App architecture
Implement a PWA offline system

As the first article in the series, this piece will first complete the most fundamental step:
Running the PicoServer local HTTP service in a MAUI application.

I. Core Architecture

After embedding a Web Server in MAUI, the application architecture becomes:

Browser / WebView
        │
        │ HTTP
        ▼
   PicoServer
        │
   Local REST API
        │
     MAUI App

In other words:
A MAUI application is not only a client but also a web server.

The advantages of this architecture are very obvious:

Advantage	Description
Cross-platform	Windows / Android / iOS
Local API	Direct calls from WebView
Easy development	UI built with web technologies
High scalability	Can build a complete Web Admin

In subsequent chapters, we will gradually extend this architecture.

II. Technology Introduction

1. .NET MAUI

.NET MAUI (Multi-platform App UI) is a cross-platform application development framework launched by Microsoft, used to build applications for:

Windows
Android
iOS
macOS

Developers can use:

C#
XAML

to build cross-platform UIs and share a large amount of business code.

Core features of .NET MAUI include:

Single project structure with multi-platform compilation
Native performance
Deep integration with the .NET ecosystem
Support for WebView / Blazor / ASP.NET Core

Official website:
https://dotnet.microsoft.com/en-us/apps/maui

2. PicoServer

PicoServer is a lightweight embedded web server component based on .NET.

Its design goal is:

To quickly launch an HTTP service inside an application.

PicoServer is implemented based on HttpListenerand has the following features:

Lightweight embedded Web Server
Support for HTTP route mapping
Suitable for local APIs
Support for Web Admin
Support for LAN access

Typical application scenarios include:

Local device control interfaces
Web management backends
Hybrid App APIs
Debugging interfaces

Official website:
https://picoserver.cn/

III. Embedding PicoServer in MAUI

Below, we will demonstrate how to run PicoServer in a MAUI application through a simple example.

Supporting source code:
https://github.com/densen2014/MauiPicoAdmin

IV. Creating a MAUI Project

First, create a standard MAUI project.

In Visual Studio:

File
→ New Project
→ .NET MAUI App

After creation, you will get a default sample page.

V. Installing PicoServer

Next, install PicoServer via NuGet.

Steps:

Right-click the project
Manage NuGet Packages
Search for PicoServer
Click Install

VI. Starting PicoServer

Next, we run PicoServer when the application starts.

Open the file:
MauiProgram.cs

Add the following code before MauiApp.CreateBuilder():

var picoAdmin = new PicoAdmin();

This will run PicoServer when the application starts.

VII. Creating a PicoServer Service

Next, create a simple server class:

public class PicoAdmin
{
    private readonly WebAPIServer MyAPI = new WebAPIServer();

    public PicoAdmin()
    {
        MyAPI.AddRoute("/", Hello);
        MyAPI.StartServer();
    }

    private async Task Hello(HttpListenerRequest request, HttpListenerResponse response)
    {
        await response.WriteAsync("Hello PicoServer");
    }
}

The code logic is very simple:

Step	Description
Create server	WebAPIServer
Add route	/
Handle request	Hello()
Start service	StartServer()

VIII. Running Tests

First, run on the Windows platform.

After launching the program, access the following address in a browser:
http://127.0.0.1:8090

If the page displays:
Hello PicoServer

It indicates:

The MAUI application started successfully
PicoServer is running successfully
The local HTTP service is working properly

IX. Running on Mobile Platforms

This example can run not only on Windows but also on:

Android
iOS
macOS

After running on Android or iOS, you can access it via:
http://[Device IP]:8090

X. Running Principle

The entire running process is as follows:

MAUI App Start
        │
        ▼
   PicoAdmin
        │
        ▼
   PicoServer
        │
        ▼
 HttpListener
        │
        ▼
   HTTP Request

In other words:
The MAUI application starts a local Web Server at the same time it launches.
All subsequent HTTP requests are processed by PicoServer.

XI. Summary

Through this article, we have completed a key step:
Embedding the PicoServer web service in a MAUI application.

The implemented content includes:

Running an HTTP Server in MAUI
Adding simple routes
Accessing local APIs via a browser
Cross-platform running tests

Although this example is very simple, it lays the foundation for the entire series.

In subsequent articles, we will continue to expand PicoServer's capabilities:

Building REST APIs
Designing a scalable API architecture
Implementing a static file server
Developing a Web Admin management backend

In the next article, we will delve deeper into PicoServer's core capabilities:
PicoServer Routing Mechanism and API Design.

And build the first truly usable API interface.

Keywords:

-.NET MAUI
-PicoServer
-MAUI Web Server
-MAUI HTTP API
-Embedded Web Server
-MAUI Web Admin

Author: Microsoft MVP AlexChow
Translated from: https://www.cnblogs.com/densen2014/p/19670893

MAUI + PicoServer: Practical Implementation of Embedded Web Architecture

ben — Mon, 09 Mar 2026 13:02:29 +0000

PicoServer: A Lightweight Cross-Platform Web Service Solution

In traditional desktop and mobile applications, UI logic and business logic are often tightly coupled.
In modern web architectures, however, the separation of front-end and back-end has become the mainstream paradigm.

This raises a series of questions:

Can a local app have its "own web server"?
Can an API layer run inside the app?
Can web technologies be used to build a local backend management system?
Can we create a true local web shell application?

This series will focus on building the following components with PicoServer + MAUI:

Cross-platform local HTTP service
Embedded API architecture
Lightweight Web Admin system
Local web shell application framework

We will start with the simplest step:
Hello PicoServer

Then evolve step by step to a complete solution featuring:

Full-fledged local Admin system
REST API
Static resource hosting
Web front-end integration
Permission control
Local area network (LAN) access
Cross-platform deployment

You will discover that:
A MAUI application can actually be transformed into a "mini server".

This is not just a technical experiment, but a brand-new architectural approach.

Series Objectives

Through 10 articles, you will master:

How to embed PicoServer in MAUI
How to design a local API architecture
How to build a lightweight Web Admin system
How to develop a local application with front-end and back-end separation
How to turn an app into a web shell
How to implement permission control and security design
How to enable LAN access
How to design a cross-platform publishing solution

Ultimately, we will build a local web backend system that can run on Windows / Android / iOS.

Series Outline

Phase 1: Core Capabilities (Articles 1–3)

Article 1: Embedding PicoServer in MAUI – Building Local Web Services

Content:

Introduction to PicoServer
Launching a web server in MAUI
Creating the first API
Accessing localhost via browser

Objective:
Enable the app with HTTP service capabilities.

Article 2: Routing Mechanism and API Design

Content:

Route registration
API URL structure design
GET / POST methods
Parameter parsing

Objective:
Establish the API architecture.

Article 3: Building an Extensible REST API Framework

Content:

API layer separation
Controller / Service pattern
JSON response structure
Error handling

Objective:
Equip PicoServer with engineering-level capabilities.

Phase 2: Web Admin System (Articles 4–6)

Article 4: Static File Hosting and Front-End Framework Integration

Content:

Static file management
index.html configuration
Vue / React integration
WebView shell implementation

Objective:
Enable the app to run Web UI.

Article 5: Building a Complete Web Admin Backend System

Content:

Admin UI development
API and page interaction
CRUD operation examples
Tables and forms implementation

Objective:
Deliver a full-fledged backend system.

Article 6: Web Admin Permission System and Login Authentication

Content:

Login API development
Token-based authentication
Authentication middleware
Admin login interface design

Objective:
Establish a backend security system.

Phase 3: Real-Time Capabilities (Article 7)

Article 7: WebSocket Real-Time Communication and Device Control

Content:

WebSocket server setup
Real-time status monitoring
Message push functionality
Real-time data display in Web Admin

Objective:
Implement real-time system capabilities.

Phase 4: Architecture Upgrading (Articles 8–10)

Article 8: Plugin-Based API Architecture (Automatic Controller Discovery)

Content:

Automatic controller registration
Reflection-based API scanning
Modular plugin system

Objective:
Develop APIs in an ASP.NET-like manner.

Article 9: PicoServer + PWA Offline System

Content:

PWA fundamentals
Service Worker implementation
Offline caching strategy
Local database integration
App offline operation support

Final Implementation:
PWA + PicoServer = A Complete Offline System

Use Cases:

Offline warehouse management system
Offline POS system
Offline PDA application

Article 10: Complete App Web Shell Architecture

Content:

MAUI = Web Shell
PicoServer = API Layer
Web UI = Front-End Layer

Final Architecture:

MAUI App
   │
WebView
   │
PicoServer
   │
REST API
   │
Business Logic

Architecture Evolution Roadmap:
Hello Server → Simple API → Full REST Architecture → Front-End & Back-End Separation → Local Admin System → Web Shell Mode → Permission Control → LAN Access → Cross-Platform Deployment → Production-Grade Architecture

Who Is This Series For?

MAUI developers
Developers looking to build local backend systems
Developers aiming to create desktop apps with web technologies
Developers working on lightweight IoT consoles
Developers exploring local SaaS architectures

Conclusion

When an app is empowered with web server capabilities, it is no longer just a client-side application.

It can be:

A local service node
A LAN control center
An embedded backend system
A lightweight management platform

This is the true value of PicoServer.

The ultimate goal of this series is to build a complete architectural system integrating MAUI + PicoServer + Web UI, enabling developers to build cross-platform apps with web technologies while leveraging PicoServer to implement local APIs, offline systems, and Web Admin backend management systems.

Author: Microsoft MVP AlexChow
Translated from: https://www.cnblogs.com/densen2014/p/19670899

PicoServer Progressive Usage Guide (VB.NET Version)

ben — Wed, 28 Jan 2026 04:08:49 +0000

🧰 PicoServer Progressive Usage Guide

Chapter 1: Basic WebAPI (Out-of-the-Box)

If you only need your application to respond to web requests and return data, this section is all you need.

1. Server Startup & Getting Started

Simply initialize WebAPIServer and call StartServer.

Private ReadOnly MyAPI As New WebAPIServer

Sub Main()
    ' Start the server (default port: 8090)
    MyAPI.StartServer()
    ' Register route (see mapping methods below)
    MyAPI.AddRoute("/", AddressOf hello, "GET")
    Console.ReadKey()
End Sub

Related Methods

' Add routes to the whitelist; whitelisted routes bypass middleware processing
MyAPI.RouteWhiteList.Add("/hello")
MyAPI.ClearRoutes() ' Clear all routes
MyAPI.StopServer() ' Stop the server

2. Three Ways to Map Routes

PicoServer offers flexible route configuration methods:

Method Mapping: The most commonly used method with clear logic and restricted request methods. MyAPI.AddRoute("/hello", AddressOf hello, "GET")

Private Async Function hello(request As HttpListenerRequest, response As HttpListenerResponse) As Task
    Dim name = request.GetQuery("name") ' Get URL query parameters
    If name = "" Then
        name = "PicoServer"
    End If
    Await response.WriteAsync(<t>{"code":1,"msg":"Hello <%= name %> WebAPI"}</t>.Value)
End Function

Anonymous Function: Ideal for logic that can be implemented in a single line of code.

MyAPI.AddRoute("/status", Function(req, resp) resp.WriteAsync("OK"), "GET")

Multi-Action Routing: No method restrictions, with judgment and distribution implemented in the logic. MyAPI.AddRoute("/user", AddressOf userHandle)

Private Async Function users(request As HttpListenerRequest, response As HttpListenerResponse) As Task
    Select Case request.HttpMethod
        Case "GET"
            ' Generate a JWT Token valid for 1 hour
            Dim token = MyAPI.JWT.GenerateToken(<t>{"username":"PicoServer","exp":<%= MyAPI.GetTimeStamp10(60 * 60) %>}</t>.Value)
            ' Return user information request with Token attached
            Await response.WriteAsync(<t>{"code":1,"msg":"Successfully retrieved user information","data":{"username":"PicoServer","age":30},"token":"<%= token %>"}</t>.Value)
        Case "POST"
            ' Directly decode the JWT Token to get the payload here; built-in authentication automatically verifies Token validity.
            ' Invalid Tokens will be intercepted by middleware and won't execute to this point.
            Dim payload = MyAPI.JWT.DecodePayload(request.GetToken)
            ' Further validate Token validity and expiration time if needed

            ' Assume the request body is in JSON format and contains user information
            Await response.WriteAsync(<t>{"code":1,"msg":"User created successfully","data":<%= payload %>}</t>.Value)
        Case Else
            response.StatusCode = 405 ' Method Not Allowed
            Await response.WriteAsync(<t>{"code":0,"msg":"Method not allowed"}</t>.Value)
    End Select
End Function

Built-in Methods

' Get the request body as a string
Dim body = Await request.ReadBodyAsString
' Two built-in timestamp methods
MyAPI.GetTimeStamp13(60 * 60 * 1000) ' Get current 13-digit timestamp plus 1 hour validity (in milliseconds); no parameter for current time only
MyAPI.GetTimeStamp10(60 * 60) ' Get current 10-digit timestamp plus 1 hour validity (in seconds); no parameter for current time only
' Get key-value pairs from POST form data with the following method
Dim name = request.ParseForm()("name")

Chapter 2: Arsenal Extensions (Streaming & Long Connections)

Install these enhancement components when you need to handle large files, real-time monitoring, or intermittent notifications.

Common Methods

' Add a route for file download, restricted to GET method
MyAPI.AddRoute("/download", Function(req, resp) resp.SendFileAsync("E:\3 Life\DadFeeding.mp4"), "GET")
' Add a route for file upload, restricted to POST method; progress callback is an optional parameter
MyAPI.AddRoute("/upload", Function(req, resp) req.SaveFileAsync("E:\3 Life\FileUploadTest\123.data", Sub(cur, total) Console.WriteLine($"Progress: {cur / total}%")), "POST")

1. Video Playback & Preview

asAttachment is True by default (forces download). Set to False for previewing documents, videos and similar files.

' Suitable for video player calls
MyAPI.AddRoute("/mp4", Function(req, resp) resp.SendFileAsync("D:\movie.mp4", False), "GET")

2. Real-Time Live Stream Mode

isLive:=True indicates whether it is a live stream (file or stream). Setting to True enables Chunked transfer encoding with no caching, perfect for security monitoring forwarding.

MyAPI.AddRoute("/live", Function(req, resp)
    Dim fs = New FileStream("camera.mp4", FileMode.Open, FileAccess.Read, FileShare.ReadWrite)
    Return resp.SendStreamAsync(fs, "video/mp4", isLive:=True)
End Function, "GET")

3. Long Connections & File Uploads

' Long connection push: Be sure to call resp.Close() when finished
MyAPI.AddRoute("/notify", Function(req, resp) resp.WriteChunkAsync("Alarm Message"), "GET")

' File upload: Supports progress callback
MyAPI.AddRoute("/upload", Function(req, resp) req.SaveFileAsync("D:\up.dat", Sub(cur, total) Console.WriteLine($"Progress: {cur * 100 / total}%")), "POST")

Chapter 3: Security Guard (JWT & Middleware)

Intercept or allow requests with middleware before they reach your business logic.

1. Enable Interception and Verification

With just one line of code, automatically validate the Authorization field in the request header.

' Add simple Token verification middleware
MyAPI.AddSimpleTokenVerify("333") ' All routes require Token verification; the parameter is the Token value
' Or use JWT mode
MyAPI.AddJwtTokenVerify("micoroserver779") ' All routes require JWT Token verification; the parameter is the signature secret key

Two built-in identity authentication middlewares provide unified authentication for WebAPI, WebSocket, file uploads and downloads. Routes that do not require authentication can be added to the whitelist with MyAPI.RouteWhiteList.Add("/hello").

2. Identity Token Operations

Built-in timestamp tools let you generate Tokens that can be directly returned as responses.

' Universal method to get Token
Dim token = request.GetToken

' Generate a JWT valid for 1 hour (3600 seconds)
Dim exp = MyAPI.GetTimeStamp10(3600)
Dim jwttoken = MyAPI.JWT.GenerateToken(<t>{"user":"admin","exp":<%= exp %>}</t>.Value)

' Decode Token to get payload in routes
Dim payload = MyAPI.JWT.DecodePayload(request.GetToken)

Chapter 4: Real-Time Communication (WebSocket)

Enable the WebSocket server and client when low-latency, bidirectional data exchange is required.

WebSocket Server

1. Configuration & Enabling

MyAPI.enableWebSocket = True
MyAPI.WsOnConnectionChanged = AddressOf WsConnectChanged
MyAPI.WsOnMessage = AddressOf OnMessageReceived

2. State & Message Handling

Private Async Function OnMessageReceived(clientId As String, msg As String, sendReply As Func(Of String, Task)) As Task
    Console.WriteLine($"Received message from {clientId}: {msg}")
    ' Example: Reply to the client
    Await sendReply($"I have received: {msg}")
End Function

Private Sub WsConnectChanged(clientId As String, connected As Boolean)
    If connected Then
        Console.WriteLine($"WS Client {clientId} connected")
    Else
        Console.WriteLine($"WS Client {clientId} disconnected")
    End If
End Sub

Related Methods

' Get the list of IDs for all currently online WebSocket clients
MyAPI.WsGetOnlineClients()

WebSocket Client

1. Reference & Instance Declaration

Imports PicoServer
Module WebSocketTest
    Private wsClient As WebSocketClient ' WebSocket client instance
    ' Subsequent logic...
End Module

2. Initialization & Event Subscription

' Initialize the client and specify the server address
wsClient = New WebSocketClient("wss://echo.websocket.org/")

' Subscribe to core events
AddHandler wsClient.OnConnected, AddressOf OnConnected ' Connection succeeded
AddHandler wsClient.OnMessageReceived, AddressOf OnMessageReceived ' Message received
AddHandler wsClient.OnDisconnected, AddressOf OnDisconnected ' Connection disconnected
AddHandler wsClient.OnError, AddressOf OnError ' Exception triggered

3. Core Operations

Method	Description
`wsClient.StartConnect()`	Start the client and establish a connection to the server
`wsClient.SendMessageAsync(message)`	Asynchronously send a string message to the server
`wsClient.StopConnect()`	Actively disconnect the WebSocket connection

4. Event Callback Examples

' Connection succeeded
Private Sub OnConnected(sender As Object, e As EventArgs)
    Console.WriteLine("Connected successfully!")
End Sub

' Message received
Private Sub OnMessageReceived(sender As Object, message As String)
    Console.WriteLine($"Received message: {message}")
End Sub

' Connection disconnected
Private Sub OnDisconnected(sender As Object, e As EventArgs)
    Console.WriteLine("Connection disconnected!")
End Sub

' Exception handling
Private Sub OnError(sender As Object, e As WebSocketErrorEventArgs)
    Console.WriteLine($"Error: {e.ErrorCode}, {e.ErrorMessage}")
End Sub