Skip to content

canhorn/EventHorizon.Blazor.TypeScript.Interop.Generator

Repository files navigation

Build Status codecov EventHorizon.Blazor.TypeScript.Interop.Generator

GitHub GitHub tag (latest SemVer pre-release)

EventHorizon.Blazor.TypeScript.Interop.Generator EventHorizon.Blazor.TypeScript.Interop.Generator.Model EventHorizon.Blazor.TypeScript.Interop.Generator.Writers.Project

EventHorizon.Blazor.TypeScript.Interop.Tool

About EventHorizon Blazor TypeScript Interop Generator

This project generates a C# Blazor Interop proxy using a TypeScript definition file.

Details

The generated project can be used with Blazor Wasm/Server to interface with JavaScript from C#, this gives most JavaScript libraries an easy to use interface from C#. It uses the JSRuntime to interop directly with the underlying JavaScript from C#, this is done with a custom interop abstraction.

The Wasm interop project can be found in the canhorn/EventHorizon.Blazor.Interop repository, it gives the generated code access to a common set of access patterns it then uses to interface with the JavaScript. The canhorn/EventHorizon.Blazor.Server.Interop repository contains the Blazor Server, async first, JavaScript access patterns.

Tech Used

Using the Tool

dotnet tool install -g EventHorizon.Blazor.TypeScript.Interop.Tool

Command Line Options

Identifier Details Required/Default
-s, --source <source> TypeScript Definition to generate from, can be a File or URL, accepts multiple or as Array REQUIRED
-c, --class-to-generate <class-to-generate> A Class to generate, accepts multiple or as Array REQUIRED
-a, --project-assembly <project-assembly> The project name of the Assembly that will be generated Default: "Generated.WASM"
-l, --project-generation-location <project-generation-location> The directory where the Generated Project assembly will be saved Default: "_generated"
-f, --force This will force generation, by deleting --project-generation-location Default: (False)
-p, --parser The type of TypeScript parser to use, Supported values: ("dotnet","nodejs") Default: ("dotnet")
-h, --host-type The host type the source should be generator for, Supported values: ("wasm","server"). Default: ("wasm")

More details in the Tool README.md.

TypeScript Parser

The generation relies heavily on the TypeScript Abstract Syntax Tree and so the code includes ways to parse the source files into a AST representation for easier generation.

The code has two supported parser types, .NET and NodeJS, to do realtime parsing of code. Using a .NET library it's able to do very quick parsing, but since it has not been maintained it can not handle complex or modern TypeScript syntax. But with the NodeJS TypeScript parser it can handle modern more complex TypeScript syntax, but with the trade off of in speed.

Having NodeJS installed is required to use the NodeJS TypeScript parser. (This is required when using the parser with the Tool)

Supported API's Generated

Below is a list of API that will be generated.

API Details Example Support
Constructor You can use the default constructor of Classes, causes new call in JavaScript. new BabylonJS.Engine() ✔️
Constructor with arguments Same as Constructor, but can also pass in arguments. new BabylonJS.Engine("canvas-window-id") ✔️
Property You can get or set properties supplied by the object. var isDisabled = engine.disableManifestCheck and engine.disableManifestCheck = true ✔️
Property You can set properties supplied by created objects. engine.disableManifestCheck = true ✔️
Static Property You can get Static properties of a Class. var isDisabled = Engine.ALPHA_DISABLE ✔️
Method You can call a method supplied by an object. var ratio = engine.getScreenAspectRatio() ✔️
Async Methods You can call a Task method and await the result. var ratio = await SceneLoader.LoadSceneAsync(...) ✔️
Static Method You can call a Static method provided by a Class. engine.DefaultLoadingScreenFactory(canvas) ✔️
Callback Method You can supply a callback action to a method supplied by an object. observer.add(() => doSomething()) ✔️
Static Callback Method You can call a Static method provided by a Class. Engine.AudioEngineFactory() ✔️
Get Instance Accessor You can have access to the get accessor on an object. var check = engine.disableManifestCheck ✔️
Set Instance Accessor You can use the set accessor on an objects. engine.onCanvasPointerOutObservable.add(() => doSomething()) ✔️
Action Callback You can run Async based code. meshLoader.OnSuccess(new ActionCallback<Mesh>(mesh => { return Task.CompletedTask; })) ✔️
Action Callback in Literal You can run Async based code. new HeightMapMesh({ onReady = new ActionCallback<Mesh>(mesh => { return Task.CompletedTask; }) }) ✔️
Action Result Callback You can run an action with a result to the caller. meshLoader.OnSuccess(new ActionResultCallback<Mesh, bool>(mesh => { return mesh != null; })) ✔️

Notes on the framework, it might not have the exact API supplied by a TypeScript definition file, in that it might transform the API into something more general and friendly to C#. I used C# as my main source of inspiration for the generated code.

Example

Checkout /Sample for a BabylonJS working example solution. The solution includes a BabylonJS generated proxy, with a working Blazor Wasm site. You can also checkout the website on this repository for deployed website using the generated BabylonJS. The Sample also includes a Blazor Server project, showing the same example as the Wasm but using Async/Await patterns.