Note: This tutorial is aimed at advanced developers.
The techniques shown here are intended for very specific use cases and require in-depth knowledge of programming,
particularly in the areas of .NET, JavaScript and web technologies.
For most GuiXT projects these communication paths are not necessary.
The examples in this tutorial are intentionally kept simple, as these structures can quickly become considerably
more complex in practice.
It is therefore recommended to use these approaches only when there is no simpler alternative.
This tutorial shows three fundamental architectures through which GuiXT, JavaScript, .NET and WebAssembly (WASM) can communicate with each other.
Each architecture defines which component takes control and which connections are direct or indirect.
The following overview diagram shows all possible connections at a glance.
A solid line represents a direct connection, a dashed line an optional one and a dotted line an indirect one.
GuiXT can communicate directly with JavaScript (via CallJS) and with .NET (via CallVB).
JavaScript can communicate directly with WASM and optionally also with .NET (e.g. via a COM object).
WASM, however, has no native direct connection to GuiXT and always depends on an intermediary.
The three sections below each show a concrete communication path with example code.
GuiXT as Translator
In this architecture GuiXT acts as the central intermediary between JavaScript and .NET.
JavaScript and .NET are unaware of each other; all data flows exclusively through GuiXT commands.
The process is fully sequential and is always triggered by a user action in GuiXT.
1. The Screen Layout
The GuiXT script creates a WebView that loads a local HTML page (TestPage.html)
and a pushbutton that runs the input script greeting.txt when clicked.
The WebView command opens the HTML page in the specified area and assigns it the internal name testview.
Using this name GuiXT can later call JavaScript functions in exactly this WebView.
The pushbutton triggers the input script; only then does communication begin.
2. The Flow: greeting.txt
The input script contains exactly three lines and describes the complete communication path:
Line 1:CallJS jsval = <testview>.sendText
GuiXT calls the JavaScript function sendText() in the WebView and stores the return value in the GuiXT variable jsval.
In this example the function returns the string "Hello from JS!".
Line 2:CallVB netval = Greetings.Greeter.receiveGreeting "&V[jsval]"
GuiXT passes the value just received (&V[jsval] is replaced by the variable's content) to the .NET method receiveGreeting
and stores the response in netval.
Line 3:CallJS <testview>.receiveText "&V[netval]"
GuiXT sends the .NET response as an argument to the JavaScript function receiveText(),
which then updates the text in the WebView.
3. The .NET Class
The .NET class Greeter contains a single method receiveGreeting that takes a string and returns a string.
It checks whether the input value is exactly "Hello from JS!" and responds accordingly.
Any other input returns "Invalid Greeting", making it clearly visible whether the data was transferred correctly.
Namespace Greet
Public Class Greeter
Public Function receiveGreeting(text As String) As String
If text = "Hello from JS!" Then
Return "Hello from .NET!"
End If
Return "Invalid Greeting"
End Function
End Class
End Namespace
namespace Greet
{
public class Greeter
{
public string receiveGreeting(string text)
{
if (text == "Hello from JS!")
{
return "Hello from .NET!";
}
return "Invalid Greeting";
}
}
}
4. The WebView Content: TestPage.html
The HTML page defines two JavaScript functions that GuiXT can call via CallJS:
HTML
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>TestPage</title>
</head>
<body>
<script>
function receiveText(text) {
if (text === "Hello from .NET!") {
let node = document.getElementById("hellotext")
node.innerText = "Received Hello from .NET :)"
}
}
function sendText() {
return "Hello from JS!"
}
</script>
<p id="hellotext">No hello :(</p>
</body>
</html>
sendText() is the data source: it simply returns the fixed string "Hello from JS!",
which GuiXT picks up in line 1 of the script.
receiveText(text) is the receiver: GuiXT calls it in line 3 with the .NET response.
If the value is correct the function replaces the placeholder text of the <p> element with "Received Hello from .NET :)".
5. Result
After clicking the pushbutton GuiXT runs all three lines of the input script.
The WebView then displays the confirmation message:
Advantages
• Simplest setup: no additional configuration needed, as GuiXT supports CallJS and CallVB out of the box.
• Clear, easy-to-follow data flow: every step is a single GuiXT line.
• Well suited for simple request-response scenarios without state management.
Disadvantages
• GuiXT is the bottleneck: every interaction must be triggered by a GuiXT script.
• No direct communication between JS and .NET possible; both sides are isolated from each other.
• The flow is strictly synchronous; asynchronous patterns (e.g. events, callbacks) cannot be implemented this way.
Communication Triangle between GuiXT, JS and .NET
In this architecture all three components (GuiXT, JavaScript and .NET) can communicate directly with each other.
The key is a COM object provided by .NET whose reference GuiXT passes once to JavaScript.
After that JavaScript can call the .NET methods directly without GuiXT needing to intervene again.
For the reverse direction (from .NET to JavaScript) a polling pattern is used:
.NET writes commands into an internal queue that JavaScript queries regularly.
1. The COM Object (.NET)
For GuiXT to create a .NET object via CallVB and pass the reference to JavaScript,
the class must be visible as a COM object.
The interface IStringContainer is marked with [ComVisible(true)] and [InterfaceType(ComInterfaceType.InterfaceIsDual)].
InterfaceIsDual means the interface is accessible both via COM Dispatch (late binding, as used by GuiXT and older scripting languages)
and via vtable (early binding).
Each method receives a fixed [DispId] so the mapping stays stable even if the order of methods in the source code changes.
The class StringContainer implements this interface and contains the following methods:
• Store(s): stores a string in the object and returns it.
• Read(): returns the stored string in lowercase (demonstrates real .NET processing).
• Create(): creates a new instance and stores it statically in _instance. GuiXT calls this method to initialise the object.
• polfunc(): returns the next entry from the internal queue, or an empty string if the queue is empty. JavaScript calls this method in the polling interval.
• WriteLine(s): adds a writeln:<text> command to the queue, allowing .NET to instruct JavaScript to write text into the document.
Imports System.Collections.Generic
Imports System.Runtime.InteropServices
<ComVisible(True)>
<InterfaceType(ComInterfaceType.InterfaceIsDual)>
Public Interface IStringContainer
<DispId(1)>
Function Store(s As String) As String
<DispId(2)>
Function Read() As String
<DispId(3)>
Function Create() As IStringContainer
<DispId(4)>
Function polfunc() As String
End Interface
<ComVisible(True)>
<ClassInterface(ClassInterfaceType.None)>
Public Class StringContainer
Implements IStringContainer
Private mycontent As String = ""
Private queue As New Queue(Of String)()
Private Shared _instance As StringContainer
Public Function Store(s As String) As String Implements IStringContainer.Store
mycontent = s
Return mycontent
End Function
Public Function Read() As String Implements IStringContainer.Read
Return mycontent.ToLower()
End Function
Public Function Create() As IStringContainer Implements IStringContainer.Create
_instance = New StringContainer()
Return _instance
End Function
Public Function polfunc() As String Implements IStringContainer.polfunc
If queue.Count > 0 Then
Return queue.Dequeue()
Else
Return ""
End If
End Function
Public Sub Test()
Dim command As String = "console"
Dim msg As String = "Success!"
_instance.queue.Enqueue(command & ":" & msg)
End Sub
Public Sub WriteLine(s As String)
Dim command As String = "writeln"
Dim msg As String = s
_instance.queue.Enqueue(command & ":" & msg)
End Sub
End Class
using System.Collections.Generic;
using System.Runtime.InteropServices;
[ComVisible(true)]
[InterfaceType(ComInterfaceType.InterfaceIsDual)]
public interface IStringContainer
{
[DispId(1)]
string Store(string s);
[DispId(2)]
string Read();
[DispId(3)]
IStringContainer Create();
[DispId(4)]
string polfunc();
}
[ComVisible(true)]
[ClassInterface(ClassInterfaceType.None)]
public class StringContainer : IStringContainer
{
private string mycontent = "";
private Queue<string> queue = new Queue<string>();
private static StringContainer _instance;
public string Store(string s)
{
mycontent = s;
return mycontent;
}
public string Read()
{
return mycontent.ToLower();
}
public IStringContainer Create()
{
_instance = new StringContainer();
return _instance;
}
public string polfunc()
{
if (queue.Count > 0)
return queue.Dequeue();
else
return "";
}
public void Test()
{
string command = "console";
string msg = "Success!";
_instance.queue.Enqueue(command + ":" + msg);
}
public void WriteLine(string s)
{
string command = "writeln";
string msg = s;
_instance.queue.Enqueue(command + ":" + msg);
}
}
2. The WebView Content: HTML & JavaScript
The HTML page contains the JavaScript logic for three tasks: receiving the object, using it directly and processing incoming messages.
HTML
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<title>GuiXT JavaScript functions, package myhtml</title>
</head>
<body>
<script>
// .NET object
var dotnetobject = null;
function receiveObject(objname) {
dotnetobject = guixthost.get(objname);
}
function saveString(s) {
dotnetobject.Store(s);
}
function displayString() {
document.body.innerHTML = dotnetobject.Read();
}
function dotnetHandler(i) {
let arr = i.split(":");
switch (arr[0]) {
case "writeln": console.log("wrote line");
document.body.innerHTML += arr[1]; break;
case "console": console.log(arr[1]); break;
default: console.log("Unsupported operation: " + i);
}
}
setInterval(function () {
if (dotnetobject == null)
return;
let i;
do {
i = dotnetobject.polfunc();
if (i !== "")
dotnetHandler(i);
} while (i !== "")
}, 30);
</script>
</body>
</html>
receiveObject(objname) is called by GuiXT via CallJS.
The parameter objname is the internal name of the COM instance (here "sc").
guixthost.get(objname) is a GuiXT-specific function available in the WebView context
that returns the stored .NET object reference by name.
From this point on JavaScript can call all methods of the .NET object directly, without involving GuiXT.
saveString(s) and displayString() demonstrate exactly that: they call dotnetobject.Store(s)
and dotnetobject.Read() directly.
Read() returns the stored string in lowercase; the .ToLower() is executed in the .NET process, not in the browser.
The setInterval at 30 ms is the polling mechanism for the reverse direction (.NET to JS).
As long as dotnetobject is set, JavaScript calls polfunc() every round.
If the method returns a string, dotnetHandler processes it:
a writeln: prefix appends text to the document, a console: prefix writes to the browser console.
The loop continues until the queue is empty (return value "").
3. GuiXT Scripts
The layout script opens the WebView and the trigger button, exactly as in section 1:
The input script sets up the communication channel and then shows how GuiXT and JavaScript use the .NET object together:
GuiXT
CallVB sc = JavaScriptCom.stringcontainer.create
//Queues commands
CallVB JavaScriptCom.stringcontainer.WriteLine "1"
CallVB JavaScriptCom.stringcontainer.WriteLine "2"
CallVB JavaScriptCom.stringcontainer.WriteLine "3"
// pass .NET object to JS
CallJS <testview>.receiveObject "sc"
// set string as content into .NET object
CallJS <testview>.saveString "Hello from .NET!"
// display string in lowercase, string read from .NET object
CallJS <testview>.displayString
Line 1:CallVB sc = JavaScriptCom.stringcontainer.create
GuiXT calls the COM method Create(), which creates a new StringContainer instance, stores it internally as _instance and returns it.
GuiXT registers the object internally under the name sc.
Lines 3–5:CallVB ... WriteLine "1" etc.
Before JavaScript knows about the object, GuiXT adds three entries to the queue.
This demonstrates that .NET can send messages ahead of time; JavaScript will find them on its first polling pass.
Line 8:CallJS <testview>.receiveObject "sc"
GuiXT passes the name "sc" to JavaScript. There guixthost.get("sc") retrieves the reference to the .NET object;
from now on the polling timer runs and JavaScript can address the object directly.
Lines 11 and 14 demonstrate direct access from JS to .NET:
saveString writes "Hello from .NET!" into the object via Store(),
and displayString reads it back with Read(). The browser displays the text in lowercase
because Read() internally calls .ToLower().
Advantages
• JavaScript and .NET can communicate directly without every message having to be routed through a GuiXT script.
• The polling pattern allows .NET to send messages to JavaScript at any time, creating a simple asynchronous channel.
• Flexible setup: GuiXT only handles the initial wiring; after that JS and .NET operate largely independently.
Disadvantages
• Higher setup effort: the .NET assembly must be registered as a COM object ([ComVisible(true)], COM registration).
• Polling causes constant overhead, as the timer runs every 30 ms even when no messages are pending.
• COM is a Windows-specific technology; this approach cannot be ported to other platforms.
• Debugging is more demanding as data flows through multiple layers and an asynchronous mechanism.
JavaScript as Translator
In this architecture .NET runs entirely in the browser, as a WebAssembly module.
C# code is compiled to WASM; the browser runs it at near-native speed without requiring a server.
JavaScript acts as the intermediary: it starts the WASM runtime, provides it with browser functions ([JSImport])
and makes C# methods accessible to HTML events ([JSExport]).
GuiXT only needs to open the finished HTML page in a WebView.
C# is recommended for .NET WASM.
While VB.NET is technically supported by the WASM runtime, it is not intended for production use
and should only be used if absolutely necessary.
All examples in this section are therefore in C# only.
1. Prerequisites: Installing .NET WASM
First check that the .NET SDK is available in a current version.
.NET WASM requires at least .NET 7; .NET 10 is recommended:
Next check which workloads are already installed.
The command dotnet workload list shows all active SDK extensions:
If wasm-tools does not yet appear in the list, install it with the following command.
This workload contains the WASM compiler and all required build targets:
Then install the WASM project templates.
The package Microsoft.NET.Runtime.WebAssembly.Templates adds three new templates to the dotnet new command;
the relevant one for this example is wasmbrowser (WebAssembly Browser App):
2. Creating and Building the Project
Use dotnet new wasmbrowser -o MyWasmApp to create a new project from the template.
The template already includes the complete stopwatch example with Program.cs, main.js and index.html:
dotnet build -c Release MyWasmApp compiles the C# code into a WASM assembly.
The result is a .dll file that is passed to the browser runtime.
The -c Release parameter produces an optimised, smaller output:
dotnet publish -c Release MyWasmApp generates the finished static folder under
MyWasmApp\bin\Release\net10.0\publish\wwwroot\.
This folder contains index.html, main.js and the subfolder _framework\
with the WASM runtime (dotnet.js, dotnet.wasm and the compiled assembly).
Copy this folder to the GuiXT websites path:
3. The C# Code: Program.cs
Program.cs contains all the stopwatch logic in a single partial class StopwatchSample.
The entry point is the implicit Main method at the top of the file:
WASM (C#)
using System;
using System.Diagnostics;
using System.Runtime.InteropServices.JavaScript;
using System.Threading.Tasks;
Console.WriteLine("Hello, Browser!");
if (args.Length == 1 && args[0] == "start")
StopwatchSample.Start();
while (true)
{
StopwatchSample.Render();
await Task.Delay(1000);
}
partial class StopwatchSample
{
private static Stopwatch stopwatch = new();
public static void Start() => stopwatch.Start();
public static void Render() => SetInnerText("#time",
stopwatch.Elapsed.ToString(@"mm\:ss"));
[JSImport("dom.setInnerText", "main.js")]
internal static partial void SetInnerText(string selector,
string content);
[JSExport]
internal static bool Toggle()
{
if (stopwatch.IsRunning)
{
stopwatch.Stop();
return false;
}
else
{
stopwatch.Start();
return true;
}
}
[JSExport]
internal static void Reset()
{
if (stopwatch.IsRunning)
stopwatch.Restart();
else
stopwatch.Reset();
Render();
}
[JSExport]
internal static bool IsRunning() => stopwatch.IsRunning;
}
The code starts with the argument "start" (passed by JavaScript via .withApplicationArguments("start"))
and then calls Render() every 1000 ms in an infinite loop, so the display is updated every second.
[JSImport("dom.setInnerText", "main.js")] declares that C# may call the JavaScript function dom.setInnerText
registered in main.js. This function sets the text of a DOM element via a CSS selector.
C# calls it like a normal static method; the WASM interop layer translates the call automatically.
[JSExport] makes C# methods callable from JavaScript.
Toggle() starts or stops the stopwatch and returns whether it is currently running.
JavaScript uses this return value to switch the button text between "Pause" and "Start".
Reset() resets the stopwatch and immediately updates the display.
4. The JavaScript Entry Point: main.js
main.js is an ES module and handles bootstrapping the WASM runtime and wiring up the buttons:
JavaScript
// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
import { dotnet } from './_framework/dotnet.js'
const { setModuleImports, getAssemblyExports, getConfig, runMain }
= await dotnet
.withApplicationArguments("start")
.create();
setModuleImports('main.js', {
dom: {
setInnerText: (selector, time) =>
document.querySelector(selector).innerText = time
}
});
const config = getConfig();
const exports = await getAssemblyExports(config.mainAssemblyName);
document.getElementById('reset').addEventListener('click', e => {
exports.StopwatchSample.Reset();
e.preventDefault();
});
const pauseButton = document.getElementById('pause');
pauseButton.addEventListener('click', e => {
const isRunning = exports.StopwatchSample.Toggle();
pauseButton.innerText = isRunning ? 'Pause' : 'Start';
e.preventDefault();
});
// run the C# Main() method and keep the runtime process running
// and executing further API calls
await runMain();
dotnet.create() loads and initialises the .NET WASM runtime from the _framework/ folder.
.withApplicationArguments("start") is equivalent to passing args[0] to the C# Main method.
setModuleImports registers the JavaScript implementation for all [JSImport] declarations in C#.
Here dom.setInnerText is defined as a simple arrow function that sets document.querySelector(selector).innerText.
C# can then call this function like a native method.
getAssemblyExports returns a JavaScript object containing all C# methods marked with [JSExport].
The button listeners call exports.StopwatchSample.Reset() and exports.StopwatchSample.Toggle() directly,
as if they were normal JavaScript functions, even though the actual code runs in C#.
runMain() starts the C# Main method and keeps the runtime running.
Since Main contains a while(true) loop the render timer runs continuously
and further [JSExport] calls remain available at any time.
5. The HTML Page: index.html
The HTML is intentionally minimal; the logic lives entirely in C# and JavaScript:
HTML
<!DOCTYPE html>
<!-- Licensed to the .NET Foundation under one or more agreements. -->
<!-- The .NET Foundation licenses this file to you under the MIT license. -->
<html>
<head>
<title>WASMTest</title>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="preload" id="webassembly" />
<script type="importmap"></script>
<script type='module' src="main#[.{fingerprint}].js"></script>
</head>
<body>
<h1>Stopwatch</h1>
<p>
Time elapsed in .NET is <span id="time"><i>loading...</i></span>
</p>
<p>
<button id="pause">Pause</button>
<button id="reset">Reset</button>
</p>
</body>
</html>
The key element is <script type='module' src="main#[.{fingerprint}].js">:
type='module' is mandatory since main.js uses ES module syntax (import).
The {fingerprint} placeholder is replaced at publish time with a build-generated hash for cache busting: the filename changes with every rebuild.
The <span id="time"> is the target selector that C# fills via SetInnerText("#time", ...).
6. GuiXT Embeds the Page
In this architecture GuiXT only needs to open the wwwroot/ folder as a WebView.
All communication between C# and JavaScript runs inside the browser; GuiXT is not involved:
After the WebView opens the WASM runtime starts automatically, loads the C# assembly
and begins the per-second time display. The Start/Pause and Reset buttons call C# methods directly:
Advantages
• All logic runs in the browser; no server-side .NET required. GuiXT only needs to open a WebView.
• Strong type safety between C# and JavaScript thanks to [JSExport] and [JSImport]; no manual string conversions.
• Modern, forward-looking architecture: .NET WASM is platform-independent and actively developed.
• C# can access browser APIs directly without GuiXT acting as an intermediary.
• WASM is not limited to .NET: other languages such as Rust, Python, Go or C++ can also be compiled to WASM and run in the browser. The same approach can therefore be applied to many technology stacks.
Disadvantages
• Highest setup effort: a .NET WASM project must be built and deployed as static files (_framework/dotnet.js etc.).
• The first page load is slow as the WASM runtime (several megabytes) must be loaded into the browser.
• WASM cannot communicate directly with GuiXT; every interaction with GuiXT must go through JavaScript as a bridge.
• Debugging is more demanding as C# code runs in a browser context and requires dedicated tools (e.g. browser devtools with WASM support).
Combined Architecture: WASM, JS, .NET and GuiXT
Warning: This architecture is the most complex of those shown here
and in practice almost always unnecessary. It is shown here solely for completeness.
Before considering this approach it should be carefully verified
whether one of the three simpler paths from the preceding sections is not sufficient.
This diagram combines the communication triangle approach from section 2 with the WASM approach from section 3.
All four components are active simultaneously: GuiXT orchestrates the SAP interface,
.NET handles the GuiXT-adjacent logic via the COM object,
JavaScript acts as the central hub
and WASM handles computationally intensive or purely browser-side tasks.
Why Two Separate .NET Runtimes?
The decisive reason this architecture exists at all is a fundamental technical difference:
.NET in GuiXT is based on the .NET Framework and communicates via guinet.dll,
which acts as the bridge between GuiXT scripts and .NET code.
.NET WASM on the other hand uses .NET Core (from .NET 5 onwards), a completely separate runtime
that cannot run in the same process as .NET Framework.
Both runtimes are incompatible and cannot communicate directly with each other.
If a project therefore needs both GuiXT access via guinet.dll (.NET Framework) and
computations or DOM operations in WASM (.NET Core), this four-component architecture
is technically the only way to use both simultaneously.
JavaScript is the only component that can speak to all others.
Possible Division of Responsibilities
• WASM: computationally intensive tasks (e.g. data processing, mathematical calculations),
complex DOM manipulations in the WebView or functions that should intentionally remain in the browser.
It is worth noting that .NET Framework can in principle also perform DOM manipulations,
for example via the polling pattern shown in section 2; however this requires that the JavaScript code
for each desired DOM operation must first be explicitly written and registered in the queue,
which is considerably more effort for many or complex operations than the direct WASM solution.
• JavaScript: central hub; forwards results from WASM to GuiXT (via return values in CallJS)
or to .NET (via the COM object through guixthost.get).
• .NET Framework: handles all operations that require guinet.dll,
meaning direct GuiXT interaction, SAP field manipulation and similar GuiXT-specific tasks.
• GuiXT: controls the overall workflow of the SAP interface and triggers communication as needed.
Conclusion
This structure is technically possible, but it combines the complexity of all three preceding sections simultaneously.
The maintenance effort, debugging across four different runtimes and the depth of understanding required for all involved technologies
make this approach barely practical in real projects.
In almost all cases the actual problem can be solved with one of the simpler architectures from the preceding sections
without needing all four components simultaneously.
Recommendations: Which Architecture for Which Use Case?
Section 1 (GuiXT as Translator) is the recommended starting point for most use cases.
When GuiXT needs to exchange data between JavaScript and .NET and the flow is clearly sequential,
this approach is fully sufficient. It is easy to understand, requires no additional setup effort
and can be implemented quickly. For simple request-response scenarios between a WebView and .NET it is the first choice.
Section 2 (Communication Triangle) is useful when JavaScript and .NET need to communicate
regularly and independently without every interaction having to be triggered by a GuiXT script.
The polling pattern allows .NET to send messages into the WebView at any time,
which is useful for scenarios with continuous data exchange or asynchronous feedback from .NET.
This approach requires more setup than section 1 but remains manageable.
Section 3 (JavaScript as Translator / WASM) is particularly interesting
when computationally intensive tasks or complex data processing need to be handled entirely on the browser side
without requiring a .NET server.
A further advantage is language variety: since JavaScript itself can directly access many functions of guinet.dll,
other programming languages such as Rust, Python or Go can be indirectly connected to GuiXT via the WASM bridge.
WASM compiles the respective language into a browser-compatible module and JavaScript forwards the results to GuiXT.
This approach requires solid knowledge of the WASM toolchain and involves higher setup effort,
but can be a valuable tool in specialised scenarios.
Section 4 (Combined Architecture) should not be used
unless there is a compelling, technically verified necessity to run all four components simultaneously.
In practice almost every problem can be solved with one of the first three approaches.
The complexity involved in simultaneously operating .NET Framework, .NET Core WASM, JavaScript and GuiXT
far outweighs the benefit in the vast majority of cases.