Skip to content
moonolgerdPublic

About

Windows 10/11 desktop application with WPF/WebView2

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

23 Commits

Folders and files

Repository files navigation

Bermuda

A Windows 10/11 desktop application built with a WPF/WebView2 native host, a .NET Aspire orchestrator, a Hot Chocolate GraphQL API, and a React + Relay frontend.

Tech Stack React TypeScript GraphQL

Architecture

┌─────────────────────────────────────────┐
│  WPF Host  (Bermuda — net10.0-windows)  │
│  ┌───────────────────────────────────┐  │
│  │   WebView2 (chromium embedded)    │  │
│  │                                   │  │
│  │   React + Relay frontend          │  │
│  │   react-leaflet map               │  │
│  └───────────────────────────────────┘  │
│  Dark Win32 title bar (DWM)             │
└──────────────────┬──────────────────────┘
                   │ GraphQL (HTTP)
┌──────────────────▼──────────────────────┐
│  Bermuda.Api  (ASP.NET Core / .NET 10)  │
│  Hot Chocolate GraphQL                  │
│  Incidents with Priority, Status, Map   │
└─────────────────────────────────────────┘
          orchestrated by
┌─────────────────────────────────────────┐
│  Bermuda.AppHost  (.NET Aspire 13)      │
│  • Vite dev server (port 5555)          │
│  • Relay watch compiler                 │
│  • Aspire dashboard (port 18888)        │
└─────────────────────────────────────────┘

Features

  • Dark theme — dark Win32 title bar via DWMWA_USE_IMMERSIVE_DARK_MODE
  • GraphQL + Relay — type-safe queries with auto-generated TypeScript types
  • FDC3 2.2 Desktop Agent — standard window.fdc3 in every host window: user/app/private channels, intents, open, an App Directory (see FDC3)

Prerequisites

Getting started

aspire run

The Aspire dashboard opens at https://localhost:18888. The WPF window launches automatically once the Vite dev server is ready.

Project structure

src/
├── Bermuda/               # WPF host (WebView2, IPC bridge, dark title bar)
│   └── fdc3-appd.json     # FDC3 App Directory
├── Bermuda.Api/           # ASP.NET Core + Hot Chocolate GraphQL API
│   └── GraphQL/
│       ├── Incident.cs    # Incident record + enums (Status, Priority)
│       ├── IncidentRepository.cs
│       └── IncidentQuery.cs
├── Bermuda.AppHost/       # .NET Aspire orchestration
├── Bermuda.Fdc3/          # FDC3 Desktop Agent (channels, context, intents)
├── Bermuda.Fdc3.Tests/    # xUnit tests for the agent (dotnet test)
├── Bermuda.ServiceDefaults/
└── Bermuda.Web/           # Vite + React + TypeScript frontend
    ├── src/
    │   ├── bridge/        # WebView2 IPC wrapper (bermudaHost.invoke)
    │   ├── fdc3/          # window.fdc3 over the IPC bridge
    │   ├── components/
    │   │   ├── ChannelPicker.tsx        # FDC3 user channel selector
    │   │   ├── IncidentsDashboard.tsx   # Relay query root, selection state
    │   │   ├── IncidentsTable.tsx       # Sortable table
    │   │   └── IncidentMap.tsx          # react-leaflet map
    │   ├── ipc/__generated__/ # ipc.d.ts from Bermuda.IpcContract.SourceGenerator
    │   └── __generated__/ # Relay-generated TypeScript types
    └── e2e/               # Playwright E2E tests (CDP, no web server needed)

E2E tests

Tests connect to the running WebView2 process via Chrome DevTools Protocol — no separate browser is launched.

cd src/Bermuda.Web
pnpm e2e          # run all 25 tests
pnpm e2e:ui       # open Playwright UI mode

FDC3

Full behavioral spec: docs/fdc3.md.

The host is an FDC3 2.2 Desktop Agent. Every host window's page is one connected app instance and gets a standard window.fdc3 (an fdc3Ready event fires once it's installed), so any FDC3 code works unchanged. The host injects it into every page it shows, before the page's own scripts run (AddScriptToExecuteOnDocumentCreatedAsync with src/Bermuda/Preload/fdc3-preload.js), so App Directory apps need no Bermuda code — public/fdc3-probe.html is a plain-HTML sample:

await window.fdc3.joinUserChannel('fdc3.channel.1')
await window.fdc3.broadcast({ type: 'bermuda.incident', id: { incidentId: '7' } })
const resolution = await window.fdc3.raiseIntent('ViewIncident', context)
  • Where it lives — the agent is src/Bermuda.Fdc3/DesktopAgent.cs (one per process, shared by all windows). src/Bermuda.Web/src/fdc3/ implements the @finos/fdc3-standard DesktopAgent interface by calling fdc3.* invoke() commands (the IFdc3Commands interface, generated from Bermuda.Fdc3.Proto/Protos/fdc3.proto into Bermuda.IpcContract/Generated/Fdc3Contract.g.cs, implemented per app instance by Fdc3Connection, so their TS types are generated like everything else) and dispatching the host's fdc3.context / fdc3.intent / fdc3.event pushes to registered handlers.
  • Supported — the 8 recommended user channels, app channels, private channels (with their events), broadcast/addContextListener/getCurrentContext, findIntent/findIntentsByContext/raiseIntent/raiseIntentForContext/addIntentListener with results (context or channel), open, findInstances, getAppMetadata, getInfo, and the userChannelChanged event. Not yet: Desktop Agent Bridging, or the Web Connection Protocol for browser apps outside the host.
  • Preload bundle — fdc3-preload.js is built from src/Bermuda.Web/src/fdc3/preload.ts by pnpm build:preload (part of pnpm build) and committed, like ipc.d.ts, so the host builds without Node; CI fails if it's out of date. Re-run pnpm build:preload after touching anything under src/fdc3/.
  • App Directory — src/Bermuda/fdc3-appd.json uses the AppD v2 applications shape; relative details.urls resolve against WEB_URL. fdc3.open (or raising an intent at an app that isn't running) opens the app in a new host window and resolves once the app has connected (and, if you passed a context, registered a listener for it), or rejects with AppTimeout. Intent results the raiser never collects are dropped after 10 minutes.
  • No resolver UI yet — when an intent has several possible targets the agent picks the single running instance with a listener, else the single App Directory app to launch; anything more ambiguous rejects with ResolverUnavailable, so pass a target app ({ appId, instanceId }) to disambiguate.
  • In the app — the channel picker in the header joins/leaves a user channel. Selecting an incident broadcasts a bermuda.incident context; incidents broadcast by other apps on the same channel, or raised via the ViewIncident intent, get selected.

Other useful commands

# Build a self-contained MSIX installer (needs the winapp CLI: winget install Microsoft.winappcli --source winget)
dotnet msbuild src/Bermuda -t:CreateMsix -p:Configuration=Release
# Output: artifacts/msix/

# The package also contains the native FDC3 side apps listed in src/Bermuda/fdc3-appd.json (type "native").

Releases and auto-update

Pushing a v1.2.3.4 tag runs the publish job. It attaches the .msix, Bermuda.appinstaller and Bermuda.cer (the public half of the signing certificate) to the GitHub Release, and a pages job publishes a landing page, the .appinstaller and the .cer to GitHub Pages at https://<owner>.github.io/<repo>/. The MSIX stays on the release (it is too large for Pages); the .appinstaller on Pages always points at the newest one, so that one link installs and updates the app.

One-time setup for Pages:

  1. Settings → Pages → Source: GitHub Actions.
  2. Settings → Environments → github-pages → deployment branches and tags: add the tag rule v* (the default only allows main, which blocks tag-triggered deploys).
  3. Using a custom domain? Set the PAGES_BASE_URL repository variable to its address.

If the certificate is self-signed, each machine must trust it once before installing (admin PowerShell):

Import-Certificate -FilePath .\Bermuda.cer -CertStoreLocation Cert:\LocalMachine\TrustedPeople

The host checks for a newer version on startup (checkForUpdate command, UpdateBanner in the UI) and installs it on request (applyUpdate). Both report unsupported unless the app was installed from the .appinstaller.

IPC — Web ↔ Host

The frontend calls the WPF host via bermudaHost.invoke(command, payload) (fire-and-forget or request/response with UUID correlation). The host pushes events back with CoreWebView2.PostWebMessageAsJson. The request/response envelopes are [IpcType]-marked records (IpcRequest, HostResponse in Bermuda.IpcContract) generated into ipc.d.ts like everything else in this section — MainWindow reads and writes every message with JsonSerializerOptions.Web (camelCase out, case-insensitive in) so the wire format matches those generated (camelCase) shapes.

Web                              WPF Host
 │── postMessage({id, cmd}) ────▶│
 │◀─ postMessage({id, result}) ──│  (response)
 │◀─ postMessage({type, ...}) ───│  (push event)

Window control

MainWindow projects a small WindowScriptHost object into the page via CoreWebView2.AddHostObjectToScript. Unlike the invoke() channel above, this doesn't round-trip through HostBridge — WebView2 itself maps WindowScriptHost's public methods/properties onto identically named (PascalCase) promises at chrome.webview.hostObjects.windowController, so call it directly for anything with no extra logic on the JS side:

const wc = window.chrome.webview.hostObjects.windowController;

await wc.Minimize();
await wc.Maximize();
await wc.ToggleMaximize();
await wc.Resize(1280, 800);
await wc.Move(100, 100);
await wc.Hide();
const left = await wc.Left; // properties resolve as promises too

bridge/index.ts's bermudaHost.window only wraps the handful of calls that need real JS-side logic — combining multiple calls, defaulting a param, or narrowing a type:

import { bermudaHost } from './bridge';

// Combines 7 property reads into one Promise.all + reshapes the result
const state = await bermudaHost.window.getState(); // { bounds, isMaximized, isMinimized, isFocused }

// Badge the taskbar icon (WPF TaskbarItemInfo.Overlay under the hood); description defaults to ''
bermudaHost.window.setOverlay(pngDataUrl, '3 critical incidents open');
window.chrome.webview.hostObjects.windowController.ClearOverlayIcon();

// Taskbar progress bar (WPF TaskbarItemInfo.ProgressState / .ProgressValue); state is
// narrowed to a literal union here instead of the generated method's raw `string`
bermudaHost.window.setProgressState('indeterminate'); // 'none' | 'indeterminate' | 'normal' | 'error' | 'paused'
window.chrome.webview.hostObjects.windowController.SetProgressValue(0.6); // 0–1

invoke() commands are allow-listed on the host (only methods of [IpcCommands] interfaces are reachable, with the payload bound to the method's parameter type) and return { error } when unknown. Window control has no allow-list to maintain — only the members declared on WindowScriptHost are ever reachable from script.

IncidentsDashboard uses setOverlay/ClearOverlayIcon to badge the taskbar icon with the count of open critical incidents (bridge/overlayBadge.ts renders the badge to a PNG data URL via <canvas>), so it stays visible even when the app isn't focused. App/IncidentsDashboard also set an indeterminate taskbar progress bar while the initial incidents query is loading, clearing it once data is ready.

Contract + codegen

Bermuda.IpcContract is the single source of truth for all three: [IpcCommands("prefix")] marks an interface whose methods are invoke() commands — the signature is the contract (single parameter = payload, return type = result, Task<T> unwrapped, name = prefix.camelCaseMethod minus Async), e.g. IHostCommands.Ping() → ping and IFdc3Commands.RaiseIntentAsync(Fdc3RaiseIntentRequest) → fdc3.raiseIntent, implemented by HostBridge and Fdc3Connection respectively and dispatched by IpcCommand.InvokeAsync; [IpcHostObject] marks a class projected via AddHostObjectToScript (e.g. WindowScriptHost), and [IpcType] marks a plain record/enum whose shape should be generated even though no command references it (records a command's parameter or result reaches are emitted automatically) — e.g. WindowStateSnapshot (what getState() assembles by hand, since WebView2 host-object methods can't return nested structured data directly) or TaskbarProgressState (the valid strings for SetProgressState, converted by name to WPF's own enum in MainWindow). Bermuda.IpcContract.SourceGenerator runs as an analyzer on the Bermuda project, reads all three, and writes src/Bermuda.Web/src/ipc/__generated__/ipc.d.ts on every build (deliberately not Relay's src/__generated__/ artifact directory, which relay-compiler prunes of files it didn't generate) — that file is committed (it's small, and it lets the frontend build without needing a prior dotnet build, e.g. in CI's MSIX publish job).

If you're touching any hand-written type in bridge/index.ts that mirrors a C# shape, check whether it can be [IpcType]-generated instead — that's how IpcRequest/HostResponse/WindowStateSnapshot/TaskbarProgressState all ended up there, replacing what used to be hand-duplicated (and, in one case — HostResponse's casing — actually mismatched) interfaces.

About

Windows 10/11 desktop application with WPF/WebView2

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Contributors

Languages