edge-js-up
v21.7.2
Published
Edge.js: run .NET and Node.js in-process on Windows, Mac OS, and Linux
Downloads
108
Maintainers
Readme
Edge.js: .NET and Node.js in-process
This is a fork of a fork of Edge.js And Edge.js providing improvements and bug fixes that are not yet accepted into main Edge.js repo.
NPM package is published as edge-js-up
. https://www.npmjs.com/package/edge-js-up.
NuGet package is published as EdgeJs.
Usage is same as edge, replace require('edge-js')
with require('edge-js-up')
:
npm install edge-js-up
-var edge = require('edge-js');
+var edge = require('edge-js-up');
var helloWorld = edge.func(function () {/*
async (input) => {
return ".NET Welcomes " + input.ToString();
}
*/});
Migration to .NET Core 3.1 :exclamation:
Edge.Js C# code has been migrated to .NET 3.1. If your project is referencing EdgeJs.dll
and/or Edge.js.CSharp.dll
file locations have changed.
node_modules/edge-js/lib/bootstrap/bin/Release/netcoreapp3.1/EdgeJs.dll
node_modules/edge-js/lib/bootstrap/bin/Release/netcoreapp3.1/Edge.js.CSharp.dll
Main differences from edge
- Support for new versions of Node.Js.
- Support for .NET Core 3.1 - 8.x on Windows/Linux/macOS.
- Support for Mono runtime 4.8.x - 5.x.
- Fixes AccessViolationException when running Node.js code from C# PR #573.
- Fixes StackOverflowException PR #566 that occurs when underlying C# code throws complex exception.
- Numerous bug fixes and improvements.
Electron
For use with Electron refer to electron-edge-js
. https://github.com/agracio/electron-edge-js
Quick start
Sample app that shows how to work with .NET Core using inline code and compiled C# libraries.
https://github.com/agracio/edge-js-quick-start
Node.Js Support
| Version | Status | | ------- | ------------------- | | 16.x | Supported | | 18.x | Supported | | 20.x | Supported | | 21.x | Supported | | 22.x | Awaiting release |
Mono
Mono is no longer actively supported. Exisitng code will remain with no plans of removing it but focus will be on .NET Core. Mono tests are now excluded from CI.
F# Support
edge-fs
only supports .NET 4.x projects on Windows, does not support Core CLR on any plarform.
Node.js application packaging
When packaging your application using Webpack make sure that edge-js
is specified as external module.
externals: {
'edge-js': 'commonjs2 edge-js',
},
node: {
__dirname: true,
__filename: true,
},
Inline C# code execution
Latest changes restore support for inline C# code as well as .csx files however this functionality should be used for testing purposes only.
Requirements (Windows)
You must install Microsoft Visual C++ Redistributable (x86)
Original Edge.js readme
An edge connects two nodes. This edge connects Node.js and .NET. V8 and CLR/.NET Core/Mono - in process. On Windows, MacOS, and Linux.
| | .NET 4.5 | Mono 4.x | CoreCLR | | ------- | --------------- | --------------- | --------------- | | Windows | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | Linux | :x: | :heavy_check_mark: | :heavy_check_mark: | | macOS | :x: | :heavy_check_mark: | :heavy_check_mark: |
| | .NET 4.5 | Mono 4.x | CoreCLR | | ------- | --------------- | --------------- | --------------- | | Windows | :heavy_check_mark: | :x: | :x: | | Linux | :x: | :x: | :x: | | macOS | :x: | :x: | :x: |
You can script C# from a Node.js process:
ES5
var edge = require('edge-js');
var helloWorld = edge.func(function () {/*
async (input) => {
return ".NET Welcomes " + input.ToString();
}
*/});
helloWorld('JavaScript', function (error, result) {
if (error) throw error;
console.log(result);
});
ES6
In ES6 you can use template strings to write multiline C# code.
var edge = require('edge-js');
var helloWorld = edge.func(`
async (input) => {
return ".NET Welcomes " + input.ToString();
}
`);
helloWorld('JavaScript', function (error, result) {
if (error) throw error;
console.log(result);
});
You can also script Node.js from C#:
using System;
using System.Threading.Tasks;
using EdgeJs;
class Program
{
public static async Task Start()
{
var func = Edge.Func(@"
return function (data, callback) {
callback(null, 'Node.js welcomes ' + data);
}
");
Console.WriteLine(await func(".NET"));
}
static void Main(string[] args)
{
Start().Wait();
}
}
What problems does Edge.js solve?
Ah, whatever problem you have. If you have this problem, this solves it.
--Scott Hanselman (@shanselman)
Before you dive in
See the Edge.js overview.
Read the Edge.js introduction on InfoQ.
Listen to the Edge.js podcast on Herdingcode.
Contents
Introduction
Scripting CLR from Node.js
What you need
Windows
Linux
OSX
Docker
How to: C# hello, world
How to: integrate C# code into Node.js code
How to: specify additional CLR assembly references in C# code
How to: marshal data between C# and Node.js
How to: call Node.js from C#
How to: export C# function to Node.js
How to: script Python in a Node.js application
How to: script PowerShell in a Node.js application
How to: script F# in a Node.js application
How to: script Lisp in a Node.js application
How to: script T-SQL in a Node.js application
How to: support for other CLR languages
How to: exceptions
How to: app.config
How to: debugging
Performance
Building on Windows
Building on OSX
Building on Linux
Running tests
Scripting Node.js from CLR
What you need
How to: Node.js hello, world
How to: integrate Node.js into CLR code
How to: use Node.js built-in modules
How to: use external Node.js modules
How to: handle Node.js events in .NET
How to: expose Node.js state to .NET
How to: use Node.js in ASP.NET application
How to: debug Node.js code running in a CLR application
Building Edge.js NuGet package
Running tests of scripting Node.js in C#
Use cases and other resources
Contribution and derived work
Introduction
Edge.js allows you to run Node.js and .NET code in one process on Windows, MacOS, and Linux.
You can call .NET functions from Node.js and Node.js functions from .NET. Edge.js takes care of marshalling data between CLR and V8. Edge.js also reconciles threading models of single threaded V8 and multi-threaded CLR. Edge.js ensures correct lifetime of objects on V8 and CLR heaps. The CLR code can be pre-compiled or specified as C#, F#, Python, or PowerShell source: Edge.js can compile CLR scripts at runtime. Edge can be extended to support other CLR languages or DSLs.
Edge.js provides an asynchronous, in-process mechanism for interoperability between Node.js and .NET. You can use this mechanism to:
- script Node.js from a .NET application (console app, ASP.NET, etc.)
- script C# from a Node.js application on Windows, MacOS, and Linux
- access MS SQL from Node.js using ADO.NET more...
- use CLR multi-threading from Node.js for CPU intensive work more...
- write native extensions to Node.js in C# instead of C/C++
- integrate existing .NET components into Node.js applications
Read more about the background and motivations of the project here.
Follow @tjanczuk for updates related to the module.
Scripting CLR from Node.js
If you are writing a Node.js application, this section explains how you include and run CLR code in your app. It works on Windows, MacOS, and Linux.
What you need
Edge.js runs on Windows, Linux, and OSX and requires Node.js 8.x, 7.x, 6.x, as well as .NET Framework 4.5 (Windows), Mono 4.2.4 (OSX, Linux), or .NET Core 1.0.0 Preview 2 (Windows, OSX, Linux).
NOTE there is a known issue with Mono after 4.2.4 that will be addressed in Mono 4.6.
Windows
- Node.js 8.x, 7.x, or 6.x
- .NET 4.5 and/or .NET Core
- to use Python, you also need IronPython 2.7.3 or later
- to use F#, read Dave Thomas blog post
If you have both desktop CLR and .NET Core installed, read using .NET Core for how to configure Edge to use one or the other.
Linux
- Node.js 9.x, 8.x, 7.x, 6.x
- Mono 4.2.4, 5.x x64 and/or .NET Core
- Follow Linux setup instructions
OSX
- Node.js 9.x, 8.x, 7.x, 6.x
- Mono 4.2.4, 5.x x64 and/or .NET Core
- Follow OSX setup instructions
Docker
Edge.js is available as a Docker image on the tjanczuk/edgejs repository on Docker Hub. The image is based on Debian Trusty, and contains Node.js 6.3.0 x64, Mono 4.2.4 x64, .NET Core 1.0.0 Preview 2 x64 (dotnet-dev-1.0.0-preview2-003121), and Edge.js 6.5.1:
By default Edge uses Mono to execute CLR code:
> docker run -it tjanczuk/edgejs:6.5.1
> cd samples
> node 101_hello_lambda.js
.NET welcomes Node.js
Specify the EDGE_USE_CORECLR=1
environment variable to use .NET Core instead:
> docker run -it tjanczuk/edgejs:6.5.1
> cd samples
> EDGE_USE_CORECLR=1 node 101_hello_lambda.js
.NET welcomes Node.js
Alternatively, you can also specify EDGE_USE_CORECLR
when starting the container:
> docker run -it -e EDGE_USE_CORECLR=1 tjanczuk/edgejs:6.5.1
How to: C# hello, world
Follow setup instructions for your platform.
Install edge:
npm install edge-js
In your server.js:
var edge = require('edge-js');
var helloWorld = edge.func(function () {/*
async (input) => {
return ".NET Welcomes " + input.ToString();
}
*/});
helloWorld('JavaScript', function (error, result) {
if (error) throw error;
console.log(result);
});
Run and enjoy:
$>node server.js
.NET welcomes JavaScript
If you want to use .NET Core as your runtime and are running in a dual runtime environment (i.e. Windows with .NET 4.5 installed as well or Linux with Mono installed), you will need to tell edge to use .NET Core by setting the EDGE_USE_CORECLR
environment variable:
$>EDGE_USE_CORECLR=1 node server.js
.NET Welcomes JavaScript
How to: integrate C# code into Node.js code
Edge provides several ways to integrate C# code into a Node.js application. Regardless of the way you choose, the entry point into the .NET code is normalized to a Func<object,Task<object>>
delegate. This allows Node.js code to call .NET asynchronously and avoid blocking the Node.js event loop.
Edge provides a function that accepts a reference to C# code in one of the supported representations, and returns a Node.js function which acts as a JavaScript proxy to the Func<object,Task<object>>
.NET delegate:
var edge = require('edge-js');
var myFunction = edge.func(...);
The function proxy can then be called from Node.js like any asynchronous function:
myFunction('Some input', function (error, result) {
//...
});
Alternatively, if you know the C# implementation will complete synchronously given the circumstances, you can call this function as any synchronous JavaScript function as follows:
var result = myFunction('Some input', true);
The true
parameter instead of a callback indicates that Node.js expects the C# implementation to complete synchronously. If the CLR function implementation does not complete synchronously, the call above will result in an exception.
One representation of CLR code that Edge.js accepts is C# source code. You can embed C# literal representing a .NET async lambda expression implementing the Func<object,Task<object>>
delegate directly inside Node.js code:
var add7 = edge.func('async (input) => { return (int)input + 7; }');
In another representation, you can embed multi-line C# source code by providing a function with a body containing a multi-line comment. Edge extracts the C# code from the function body using regular expressions:
var add7 = edge.func(function() {/*
async (input) => {
return (int)input + 7;
}
*/});
Or if you use ES6 you can use template strings to define a multiline string:
var add7 = edge.func(`
async (input) => {
return (int)input + 7;
}
`);
If your C# code is more involved than a simple lambda, you can specify entire class definition. By convention, the class must be named Startup
and it must have an Invoke
method that matches the Func<object,Task<object>>
delegate signature. This method is useful if you need to factor your code into multiple methods:
var add7 = edge.func(function() {/*
using System.Threading.Tasks;
public class Startup
{
public async Task<object> Invoke(object input)
{
int v = (int)input;
return Helper.AddSeven(v);
}
}
static class Helper
{
public static int AddSeven(int v)
{
return v + 7;
}
}
*/});
If your C# code grows substantially, it is useful to keep it in a separate file. You can save it to a file with *.csx
or *.cs
extension, and then reference from your Node.js application:
var add7 = edge.func(require('path').join(__dirname, 'add7.csx'));
If you integrate C# code into your Node.js application by specifying C# source using one of the methods above, edge will compile the code on the fly. If you prefer to pre-compile your C# sources to a CLR assembly, or if your C# component is already pre-compiled, you can reference a CLR assembly from your Node.js code. In the most generic form, you can specify the assembly file name, the type name, and the method name when creating a Node.js proxy to a .NET method:
var clrMethod = edge.func({
assemblyFile: 'My.Edge.Samples.dll',
typeName: 'Samples.FooBar.MyType',
methodName: 'MyMethod' // This must be Func<object,Task<object>>
});
If you don't specify methodName, Invoke
is assumed. If you don't specify typeName, a type name is constructed by assuming the class called Startup
in the namespace equal to the assembly file name (without the .dll
). In the example above, if typeName was not specified, it would default to My.Edge.Samples.Startup
.
The assemblyFile is relative to the working directory. If you want to locate your assembly in a fixed location relative to your Node.js application, it is useful to construct the assemblyFile using __dirname
. If you are using .NET Core, assemblyFile can also be a project name or NuGet package name that is specified in your project.json
or .deps.json
dependency manifest.
You can also create Node.js proxies to .NET functions specifying just the assembly name as a parameter:
var clrMethod = edge.func('My.Edge.Samples.dll');
In that case the default typeName of My.Edge.Samples.Startup
and methodName of Invoke
is assumed as explained above.
How to: specify additional CLR assembly references in C# code
When you provide C# source code and let edge compile it for you at runtime, edge will by default reference only mscorlib.dll and System.dll assemblies. If you're using .NET Core, we automatically reference the most recent versions of the System.Runtime, System.Threading.Tasks, System.Dynamic.Runtime, and the compiler language packages, like Microsoft.CSharp. In applications that require additional assemblies you can specify them in C# code using a special hash pattern, similar to Roslyn. For example, to use ADO.NET you must reference System.Data.dll:
var add7 = edge.func(function() {/*
#r "System.Data.dll"
using System.Data;
using System.Threading.Tasks;
public class Startup
{
public async Task<object> Invoke(object input)
{
// ...
}
}
*/});
If you prefer, instead of using comments you can specify references by providing options to the edge.func
call:
var add7 = edge.func({
source: function() {/*
using System.Data;
using System.Threading.Tasks;
public class Startup
{
public async Task<object> Invoke(object input)
{
// ...
}
}
*/},
references: [ 'System.Data.dll' ]
});
If you are using .NET Core and are using the .NET Core SDK and CLI, you must have a project.json
file (specification here) that specifies the dependencies for the application. This list of dependencies must also include the Edge.js runtime package and, if you need to be able to dynamically compile your code, the package(s) for the compilers that you plan to use, like Edge.js.CSharp. You must have run the dotnet restore
(to restore the dependencies) and dotnet build
(to build your project and generate the dependency manifest) commands in that project's directory to generate a .deps.json
file under bin/[configuration]/[framework]
, i.e. bin/Release/netstandard1.6/MyProject.deps.json
. This .deps.json
file must either be in the current working directory that node
is executed in or you must specify its directory by setting the EDGE_APP_ROOT
environment variable. For example, if for a netstandard1.6
project in the c:\DotNet\MyProject
directory, you would run something like:
set EDGE_APP_ROOT=c:\DotNet\MyProject\bin\Release\netstandard1.6
node app.js
Edge.js also supports running published .NET Core applications on servers that do not have the .NET Core SDK and CLI installed, which is a common scenario in production environments. To do so, the .csproj
for your application should meet the following requirements:
- It should target the
netcoreapp2.x
,netstandard1.6
ornetstandard2.0
framework moniker. - It should reference
Microsoft.NETCore.DotNetHost
andMicrosoft.NETCore.DotNetHostPolicy
. This is required so that the publish process can provide all the native libraries required to create a completely standalone version of your application. <PreserveCompilationContext>true</PreserveCompilationContext>
and<CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>
should be present under<PropertyGroup>
. You can add an emptyMain()
implementation to your project to accommodate it; this method will not be called, but is just a requirement in order fordotnet publish
to generate a completely standalone app.
On your development machine, you would run dotnet publish -r [target runtime for your production server]
(i.e. dotnet publish -r ubuntu.14.04-x64
) to aggregate the package assemblies and native libraries necessary to run your application. You can copy the contents of the publish directory up to your SDK- and CLI-less server and use them directly in Edge.js by setting the EDGE_APP_ROOT
environment variable to the directory on the server that you copied the published application to.
How to: marshal data between C# and Node.js
Edge.js can marshal any JSON-serializable value between .NET and Node.js (although JSON serialization is not used in the process). Edge also supports marshalling between Node.js Buffer
instance and a CLR byte[]
array to help you efficiently pass binary data.
You can call .NET from Node.js and pass in a complex JavaScript object as follows:
var dotNetFunction = edge.func('Edge.Sample.dll');
var payload = {
anInteger: 1,
aNumber: 3.1415,
aString: 'foo',
aBoolean: true,
aBuffer: new Buffer(10),
anArray: [ 1, 'foo' ],
anObject: { a: 'foo', b: 12 }
};
dotNetFunction(payload, function (error, result) { });
In .NET, JavaScript objects are represented as dynamics (which can be cast to IDictionary<string,object>
if desired), JavaScript arrays as object[]
, and JavaScript Buffer
as byte[]
. Scalar JavaScript values have their corresponding .NET types (int
, double
, bool
, string
). Here is how you can access the data in .NET:
using System.Threading.Tasks;
public class Startup
{
public async Task<object> Invoke(dynamic input)
{
int anInteger = (int)input.anInteger;
double aNumber = (double)input.aNumber;
string aString = (string)input.aString;
bool aBoolean = (bool)input.aBoolean;
byte[] aBuffer = (byte[])input.aBuffer;
object[] anArray = (object[])input.anArray;
dynamic anObject = (dynamic)input.anObject;
return null;
}
}
Similar type marshalling is applied when .NET code passes data back to Node.js code. In .NET code you can provide an instance of any CLR type that would normally be JSON serializable, including domain specific types like Person
or anonymous objects. For example:
using System.Threading.Tasks;
public class Person
{
public int anInteger = 1;
public double aNumber = 3.1415;
public string aString = "foo";
public bool aBoolean = true;
public byte[] aBuffer = new byte[10];
public object[] anArray = new object[] { 1, "foo" };
public object anObject = new { a = "foo", b = 12 };
}
public class Startup
{
public async Task<object> Invoke(dynamic input)
{
Person person = new Person();
return person;
}
}
In your Node.js code that invokes this .NET method you can display the result object that the callback method receives:
var edge = require('edge-js');
var getPerson = edge.func(function () {/*
using System.Threading.Tasks;
public class Person
{
public int anInteger = 1;
public double aNumber = 3.1415;
public string aString = "foo";
public bool aBoolean = true;
public byte[] aBuffer = new byte[10];
public object[] anArray = new object[] { 1, "foo" };
public object anObject = new { a = "foo", b = 12 };
}
public class Startup
{
public async Task<object> Invoke(dynamic input)
{
Person person = new Person();
return person;
}
}
*/});
getPerson(null, function (error, result) {
if (error) throw error;
console.log(result);
});
Passing this .NET object to Node.js generates a JavaScript object as follows:
$>node sample.js
{ anInteger: 1,
aNumber: 3.1415,
aString: 'foo',
aBoolean: true,
aBuffer: <Buffer 00 00 00 00 00 00 00 00 00 00>,
anArray: [ 1, 'foo' ],
anObject: { a: 'foo', b: 12 } }
When data is marshalled from .NET to Node.js, no checks for circular references are made. They will typically result in stack overflows. Make sure the object graph you are passing from .NET to Node.js is a tree and does not contain any cycles.
WINDOWS ONLY When marshalling strongly typed objects (e.g. Person) from .NET to Node.js, you can optionally tell Edge.js to observe the System.Web.Script.Serialization.ScriptIgnoreAttribute. You opt in to this behavior by setting the EDGE_ENABLE_SCRIPTIGNOREATTRIBUTE
environment variable:
set EDGE_ENABLE_SCRIPTIGNOREATTRIBUTE=1
Edge.js by default does not observe the ScriptIgnoreAttribute to avoid the associated performance cost.
How to: call Node.js from C#
In addition to marshalling data, edge can marshal proxies to JavaScript functions when invoking .NET code from Node.js. This allows .NET code to call back into Node.js.
Suppose the Node.js application passes an add
function to the .NET code as a property of an object. The function receives two numbers and returns the sum of them via the provided callback:
var edge = require('edge-js');
var addAndMultiplyBy2 = edge.func(function () {/*
async (dynamic input) => {
var add = (Func<object, Task<object>>)input.add;
var twoNumbers = new { a = (int)input.a, b = (int)input.b };
var addResult = (int)await add(twoNumbers);
return addResult * 2;
}
*/});
var payload = {
a: 2,
b: 3,
add: function (data, callback) {
callback(null, data.a + data.b);
}
};
addAndMultiplyBy2(payload, function (error, result) {
if (error) throw error;
console.log(result);
});
The .NET code implements the addAndMultiplyBy2 function. It extracts the two numbers passed from Node.js, calls back into the add
function exported from Node.js to add them, multiplies the result by 2 in .NET, and returns the result back to Node.js:
$>node sample.js
10
The Node.js function exported from Node.js to .NET must follow the prescriptive async pattern of accepting two parameters: payload and a callback. The callback function accepts two parameters. The first one is the error, if any, and the second the result of the operation:
function (payload, callback) {
var error; // must be null or undefined in the absence of error
var result;
// do something
callback(error, result);
}
The proxy to that function in .NET has the following signature:
Func<object,Task<object>>
Using TPL in CLR to provide a proxy to an asynchronous Node.js function allows the .NET code to use the convenience of the await
keyword when invoking the Node.js functionality. The example above shows the use of the await
keyword when calling the proxy of the Node.js add
method.
How to: export C# function to Node.js
Similarly to marshalling functions from Node.js to .NET, Edge.js can also marshal functions from .NET to Node.js. The .NET code can export a Func<object,Task<object>>
delegate to Node.js as part of the return value of a .NET method invocation. For example:
var createHello = edge.func(function () {/*
async (input) =>
{
return (Func<object,Task<object>>)(async (i) => {
Console.WriteLine("Hello from .NET");
return null;
});
}
*/});
var hello = createHello(null, true);
hello(null, true); // prints out "Hello from .NET"
This mechanism in conjunction with a closure can be used to expose CLR class instances or CLR state in general to JavaScript. For example:
var createCounter = edge.func(function () {/*
async (input) =>
{
var k = (int)input;
return (Func<object,Task<object>>)(async (i) => { return ++k; });
}
*/});
var counter = createCounter(12, true); // create counter with 12 as initial state
console.log(counter(null, true)); // prints 13
console.log(counter(null, true)); // prints 14
How to: script Python in a Node.js application
NOTE This functionality requires IronPython and has been tested on Windows only.
Edge.js enables you to run Python and Node.js in-process.
In addition to platform specific prerequisites you need IronPython 2.7.3 to proceed.
Hello, world
Install edge and edge-py modules:
npm install edge-js
npm install edge-py
In your server.js:
var edge = require('edge-js');
var hello = edge.func('py', function () {/*
def hello(input):
return "Python welcomes " + input
lambda x: hello(x)
*/});
hello('Node.js', function (error, result) {
if (error) throw error;
console.log(result);
});
Run and enjoy:
$>node py.js
Python welcomes Node.js
The interop model
Your Python script must evaluate to a lambda expression that accepts a single parameter. The parameter represents marshalled input from the Node.js code. The return value of the lambda expression is passed back as the result to Node.js code. The Python script can contain constructs (e.g. Python functions) that are used in the closure of the lambda expression. The instance of the script with associated state is created when edge.func
is called in Node.js. Each call to the function referes to that instance.
The simplest echo Python script you can embed in Node.js looks like this:
lambda x: x
To say hello, you can use something like this:
lambda: x: "Hello, " + x
To maintain a running sum of numbers:
current = 0
def add(x):
global current
current = current + x
return current
lambda x: add(x)
Python in its own file
You can reference Python script stored in a *.py file instead of embedding Python code in a Node.js script.
In your hello.py file:
def hello(input):
return "Python welcomes " + input
lambda x: hello(x)
In your hello.js file:
var edge = require('edge-js');
var hello = edge.func('py', 'hello.py');
hello('Node.js', function (error, result) {
if (error) throw error;
console.log(result);
});
Run and enjoy:
$>node hello.js
Python welcomes Node.js
To sync or to async, that is the question
In the examples above Python script was executing asynchronously on its own thread without blocking the singleton V8 thread on which the Node.js event loop runs. This means your Node.js application remains responsive while the Python code executes in the background.
If you know your Python code is non-blocking, or if you know what you are doing, you can tell Edge.js to execute Python code on the singleton V8 thread. This will improve performance for non-blocking Python scripts embedded in a Node.js application:
var edge = require('edge-js');
var hello = edge.func('py', {
source: function () {/*
def hello(input):
return "Python welcomes " + input
lambda x: hello(x)
*/},
sync: true
});
console.log(hello('Node.js', true));
The sync: true
property in the call to edge.func
tells Edge.js to execute Python code on the V8 thread as opposed to creating a new thread to run Python script on. The true
parameter in the call to hello
requests that Edge.js does in fact call the hello
function synchronously, i.e. return the result as opposed to calling a callback function.
How to: script PowerShell in a Node.js application
NOTE This functionality only works on Windows.
Edge.js enables you to run PowerShell and Node.js in-process on Windows. Edge-PS connects the PowerShell ecosystem with Node.js.
You need Windows, Node.js, .NET 4.5, and PowerShell 3.0 to proceed.
Hello, world
Install edge and edge-ps modules:
npm install edge-js
npm install edge-ps
In your server.js:
var edge = require('edge-js');
var hello = edge.func('ps', function () {/*
"PowerShell welcomes $inputFromJS on $(Get-Date)"
*/});
hello('Node.js', function (error, result) {
if (error) throw error;
console.log(result[0]);
});
Run and enjoy:
C:\testEdgeps>node server
PowerShell welcomes Node.js on 05/04/2013 09:38:40
Tapping into PowerShell's ecosystem
Rather than embedding PowerShell directly, you can use PowerShell files, dot source them and even use Import-Module.
What you can do in native PowerShell works in Node.js.
Interop PowerShell and Python
Here you can reach out to IronPython from PowerShell from within Node.js on Windows. This holds true for working with JavaScript frameworks and C#.
var edge = require('edge-js');
var helloPowerShell = edge.func('ps', function () {/*
"PowerShell welcomes $inputFromJS"
*/});
var helloPython = edge.func('py', function () {/*
def hello(input):
return "Python welcomes " + input
lambda x: hello(x)
*/});
helloPython('Node.js', function(error, result){
if(error) throw error;
helloPowerShell(result, function(error, result){
if(error) throw error;
console.log(result[0]);
});
});
How to: script F# in a Node.js application
NOTE This functionality has not been tested on non-Windows platforms.
This section is coming up. In the meantime please refer to Dave Thomas blog post. This has been validated on Windows only.
var edge = require('edge-js');
var helloFs = edge.func('fs', function () {/*
fun input -> async {
return "F# welcomes " + input.ToString()
}
*/});
helloFs('Node.js', function (error, result) {
if (error) throw error;
console.log(result);
});
How to: script Lisp in a Node.js application
NOTE This functionality has not been tested on non-Windows platforms.
The edge-lsharp extension uses LSharp to compile and run Lisp to .NET.
Install edge and edge-lsharp modules:
npm install edge-js
npm install edge-lsharp
In your server.js:
var edge = require('edge-js');
var fact = edge.func('lsharp', function(){/*
;; Factorial
(def fact(n)
(if (is n 0) 1 (* n (fact (- n 1)))))
*/});
fact([5], function(err, answer){
console.log(answer);
// = 120
});
An LSharp filename can be passed in instead of the Lisp string/comment:
var edge = require('edge-js');
var lisp = edge.func('lsharp', 'lisp-func.ls');
lisp(['arg1', 'arg2'], function(err, result){
});
In Lisp you can specify either a function (as shown in the first example) or just return a value:
var edge = require('edge-js');
var lisp = edge.func('lsharp', '(+ 2 3)');
lisp([], function(err, answer){
console.log(answer);
// = 5
});
How to: script T-SQL in a Node.js application
NOTE This functionality has only been tested on Windows. Although ADO.NET exist in Mono, your mileage can vary.
The edge-ms-sql extension of Edge.js allows for accessing MS SQL databases by scripting T-SQL inside the Node.js application. The edge-ms-sql extension uses async ADO.NET SQL client to access MS SQL.
You need Windows, Node.js, and .NET 4.5. To run the sample code below you also need a connection string to the sample Northwind database that ships with MS SQL.
edge-ms-sql
differences from edge-sql
- Provides optional
commandTimeout
parameter to set SQL command timeout. SqlCommand.CommandTimeout - Attempts to treat all other types of SQL statements as
select
instead of throwing exception. This allows to execute complex SQL queries that declare variables and temp tables before runningselect
statement. - Supports returning multiple results from query.
Supported SQL statements
- select
- update
- insert
- delete
- exec
All other statements will be interpreted as select
and will try to use ExecuteReaderAsync
.NET method of SqlCommand
class instance.
Install edge and edge-ms-sql modules:
npm install edge-js
npm install edge-ms-sql
Set your SQL connection string using environment variable. For passing connection string as a parameter see code examples below.
set EDGE_SQL_CONNECTION_STRING=Data Source=localhost;Initial Catalog=Northwind;Integrated Security=True
In your server.js:
const edge = require('edge-js');
var getTop10Products = edge.func('ms-sql', function () {/*
select top 10 * from Products
*/});
getTop10Products(null, function (error, result) {
if (error) throw error;
console.log(result);
});
Parameterized queries
You can construct a parameterized query once and provide parameter values on a per-call basis:
SELECT
const edge = require('edge-js');
var getProduct = edge.func('ms-sql', function () {/*
select * from Products
where ProductId = @myProductId
*/});
getProduct({ myProductId: 10 }, function (error, result) {
if (error) throw error;
console.log(result);
});
UPDATE
const edge = require('edge-js');
var updateProductName = edge.func('ms-sql', function () {/*
update Products
set ProductName = @newName
where ProductId = @myProductId
*/});
updateProductName({ myProductId: 10, newName: 'New Product' }, function (error, result) {
if (error) throw error;
console.log(result);
});
Using parameterised function
const edge = require('edge-js');
var select = edge.func('ms-sql', {
source: 'select top 10 * from Products',
connectionString: 'SERVER=myserver;DATABASE=mydatabase;Integrated Security=SSPI',
commandTimeout: 100
});
select(null, function (error, result) {
if (error) throw error;
console.log(result);
});
Stored proc with input parameters
const edge = require('edge-js');
var storedProcParams = {inputParm1: 'input1', inputParam2: 25};
var select = edge.func('ms-sql', {
source: 'exec myStoredProc',
connectionString: 'SERVER=myserver;DATABASE=mydatabase;Integrated Security=SSPI'
});
select(storedProcParams, function (error, result) {
if (error) throw error;
console.log(result);
});
How to: support for other CLR languages
Edge.js can work with any pre-compiled CLR assembly that contains the Func<object,Task<object>>
delegate. Out of the box, Edge.js also allows you to embed C# source code in a Node.js application and compile it on the fly.
To enable compilation of other CLR languages (e.g. F#) at runtime, or to support domain specific languages (DSLs) like T-SQL, you can use the compiler composability model provided by Edge.js. Please read the add support for a CLR language guide to get started.
How to: exceptions
Edge.js marshals Node.js errors and exceptions to .NET as well as .NET exceptions to Node.js.
CLR exceptions thrown in .NET code invoked from Node.js are marshalled as the error
parameter to the Node.js callback function. Consider this example:
var edge = require('edge-js');
var clrFunc = edge.func(function () {/*
async (dynamic input) => {
throw new Exception("Sample exception");
}
*/});
clrFunc(null, function (error, result) {
if (error) {
console.log('Is Error?', error instanceof Error);
console.log('-----------------');
console.log(util.inspect(error, showHidden=true, depth=99, colorize=false));
return;
}
});
Running this Node.js application shows that the CLR exception was indeed received by the Node.js callback. The error
parameter contains an Error object having most of the properties of the Exceptions copied over:
Is Error? true
-----------------
{ [System.AggregateException: One or more errors occurred.]
message: 'One or more errors occurred.',
name: 'System.AggregateException',
InnerExceptions: 'System.Collections.ObjectModel.ReadOnlyCollection`1[[System.Exception, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089]]',
Message: 'One or more errors occurred.',
Data: 'System.Collections.ListDictionaryInternal',
InnerException:
{ [System.Exception: Sample exception]
message: 'Sample exception',
name: 'System.Exception',
Message: 'Sample exception',
Data: 'System.Collections.ListDictionaryInternal',
TargetSite: 'System.Reflection.RuntimeMethodInfo',
StackTrace: ' at Startup.<<Invoke>b__0>d__2.MoveNext() in c:\\Users\\User.Name\\Source\\Repos\\eCash2\\test\\edge2.js:line 7\r\n--- End of stack trace from previous location where exception was thrown ---\r\n at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task task)\r\n at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)\r\n at System.Runtime.CompilerServices.TaskAwaiter`1.GetResult()\r\n at Startup.<Invoke>d__4.MoveNext() in c:\\Users\\User.Name\\Source\\Repos\\eCash2\\test\\edge2.js:line 5',
Source: 'cp2luegt',
HResult: -2146233088 },
HResult: -2146233088 }
The exception is copied back as Error object like every normal result object from the .NET world to JavaScript. Therefore all properties and their values are available on the Error object.
Additionally, the following happens during the mapping:
- To represent the Exception type, its full name is stored as
name
. - To follow the JavaScript convention for Errors, the
Message
is also stored as the propertymessage
. System::Reflection::RuntimeMethodInfo
s are not copied to avoid stack overflows
$>node sample.js
Edge.js:58
edge.callClrFunc(appId, data, callback);
^
System.Reflection.TargetInvocationException: Exception has been thrown by the target of an invocation.
---> System.Exception: Sample exception
at Startup.Invoke(Object input) in sample.cs:line 12
JavaScript exceptions thrown in Node.js code invoked from .NET are wrapped in a CLR exception and cause the asynchronous Task<object>
to complete with a failure. Errors passed by Node.js code invoked from .NET code to the callback function's error
parameter have the same effect. Consider this example:
var edge = require('edge-js');
var multiplyBy2 = edge.func(function () {/*
async (dynamic input) => {
var aFunctionThatThrows = (Func<object, Task<object>>)input.aFunctionThatThrows;
try {
var aResult = await aFunctionThatThrows(null);
}
catch(Exception e)
{
Console.WriteLine(e);
}
return null;
}
*/});
var payload = {
someParameter: 'arbitrary parameter',
aFunctionThatThrows: function (data, callback) {
throw new Error('Sample JavaScript error');
}
};
multiplyBy2(payload, function (error, result) {
if (error) throw error;
console.log(result);
});
Running the code shows the .NET code receiving a CLR exception as a result of the Node.js function throwing a JavaScript error. The exception shows the complete stack trace, including the part that executed in the Node.js code:
$>node sample.js
System.Exception: Error: Sample JavaScript error
at payload.aFunctionThatThrows (sample.js:7:11)
at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task task)
at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
at Edge.Sample.Startup.<Invoke>d__0.MoveNext()
How to: app.config
When running C# code within Node.js app, the app config file is node.exe.config and should be located right next to the node.exe file.
How to: debugging
NOTE This is Windows-only functionality.
On Windows, you can debug the .NET code running as part of your Node.js application by attaching a managed code debugger (e.g. Visual Studio) to node.exe. You can debug .NET code in a pre-compiled CLR assembly as well C# literals embedded in the application and compiled by Edge.js at runtime.
Debugging pre-compiled .NET code
If you have integrated .NET code into a Node.js application using a pre-compiled CLR assembly like this:
var hello = edge.func('My.Assembly.dll');
then the best way to debug your .NET code is to attach a managed code debugger (e.g. Visual Studio) to the node.exe process. Since the node.exe process runs both native and managed code, make sure to select managed code type as target:
From there, you can set breakpoints in your .NET code and the debugger will stop when they are reached.
Debugging embedded C# code
Debugging embedded C# code (on Windows) requires that EDGE_CS_DEBUG
environment variable is set in the environment of the node.exe process:
set EDGE_CS_DEBUG=1
Without this setting (the default), Edge.js will not generate debugging information when compiling embedded C# code.
You can debug C# code embedded into a Node.js application using a reference to a *.cs or *.csx file:
var hello = edge.func('MyClass.cs');
You can also debug C# code embedded directly into a *.js file using the function comment syntax:
var hello = edge.func(function () {/*
async (input) =>
{
System.Diagnostics.Debugger.Break();
var result = ".NET welcomes " + input.ToString();
return result;
}
*/});
You cannot debug C# code embedded as a simple string literal:
var hello = edge.func('async (input) => { return 2 * (int)input; }');
After setting EDGE_CS_DEBUG=1
environment variable before starting node.exe and attaching the managed debugger to the node.exe process, you can set breakpoints in C# code (which may appear as a JavaScript comment), or use System.Diagnostics.Debugger.Break()
to break into the debugger from .NET code.
Performance
Read more about performance of Edge.js on the wiki. Here is the gist of the latency (smaller is better):
Building on Windows
You must have Visual Studio 2019* toolset, Python 3.6.x, and node-gyp installed for building.
To build and test the project against all supported versions of Node.js in x86 and x64 flavors, run the following:
tools\buildall.bat
test\testall.bat
To build one of the versions of Node.js officially released by Node.js, do the following:
cd tools
build.bat release 8.10.0
Note: the Node.js version number you provide must be version number corresponding to one of the subdirectories of http://nodejs.org/dist. The command will build both x32 and x64 architectures (assuming you use x64 machine). The command will also copy the edge_*.node executables to appropriate locations under lib\native directory where they are looked up from at runtime. The npm install
step copies the C standard library shared DLL to the location of the edge_*.node files for the component to be ready to go.
To build the C++\CLI native extension using the version of Node.js installed on your machine, issue the following command:
npm install -g node-gyp
node-gyp configure --msvs_version=2015
node-gyp build -debug
You can then set the EDGE_NATIVE
environment variable to the fully qualified file name of the built edge_*.node binary (edge_nativeclr.node if you're using the native CLR runtime or edge_coreclr.node if you're using .NET Core). It is useful during development, for example:
set EDGE_NATIVE=C:\projects\edge\build\Debug\edge_nativeclr.node
You can also set the EDGE_DEBUG
environment variable to 1 to have the edge module generate debug traces to the console when it runs.
Running tests
You must have mocha installed on the system. Then:
npm test
or, from the root of the enlistment:
mocha -R spec
NOTE in environments with both desktop CLR/Mono and .NET Core installed, tests will by default use desktop CLR/Mono. To run tests against .NET Core, use:
EDGE_USE_CORECLR=1 npm test
Node.js version targeting on Windows
NOTE this is Windows only functionality.
If you want to run tests after building against a specific version of Node.js that one of the previous builds used, issue the following command:
cd test
test.bat ia32 0.10.0
Which will run the tests using Node.js x86 v0.10.0. Similarly:
cd test
test.bat x64 0.8.22
Would run tests against Node.js 0.8.22 on x64 architecture.
Building on OSX
Prerequisities:
- Homebrew
- Mono x64 and/or .NET Core - see below
- Node.js x64 (tested with v4.1.1)
You can use Edge.js on OSX with either Mono or .NET Core installed, or both.
If you choose to install Mono, select the universal installer to make sure you get the x64 version. Edge.js requires Mono x64. If you choose to install .NET Core, follow the steps here
Then install and build Edge.js:
brew install pkg-config
npm install edge-js
NOTE if the build process complains about being unable to locate Mono libraries, you may need to specify the search path explicitly. This may be installation dependent, but in most cases will look like:
PKG_CONFIG_PATH=/Library/Frameworks/Mono.framework/Versions/Current/lib/pkgconfig \
npm install edge-js
If you installed both Mono and .NET Core, by default Edge will use Mono. You opt in to using .NET Core with the EDGE_USE_CORECLR
environment variable:
EDGE_USE_CORECLR=1 node myapp.js
Building on OSX (advanced)
To build edge from a clone of the repository or source code:
node-gyp configure build
To build a debug build instead of release, you need to:
node-gyp configure build -debug
export EDGE_NATIVE=/Users/tomek/edge/build/Debug/edge_nativeclr.node
Building on Linux
For a normative set of steps to set up Edge.js on Linux with both Mono and CoreCLR please refer to the Dockerfile. You can also use the ready-made Docker image.
Using .NET Core
If you have only .NET Core installed on your system and not Mono, you can run Edge with no changes. However, if you have both runtimes installed, Edge will automatically use Mono unless directed otherwise. To use .NET Core in a dual-runtime environment, set the EDGE_USE_CORECLR=1
environment variable when starting node, i.e.
EDGE_USE_CORECLR=1 node sample.js
Edge will try to find the .NET Core runtime in the following locations:
- The path in the
CORECLR_DIR
environment variable, if provided - The current directory
- The directory containing
edge_*.node
- Directories in the
PATH
environment variable. Once a directory containing thedotnet
executable is located, we then do the following to decide which version of the framework (you can have several installed at once) to load- If the
CORECLR_VERSION
environment variable was specified, we try to load that version - Else, if the project.json/*.deps.json has a reference to
Microsoft.NETCore.App
, indicating that it was built for a specific framework version, we try to load that version - Otherwise, we pick the maximum installed version
- If the
So, if the CLR is another location or you want to use a version of the CLR other than the default that you've set, the best way to specify that is through the CORECLR_DIR
or CORECLR_VERSION
environment variables, i.e.
EDGE_USE_CORECLR=1 \
CORECLR_DIR=/usr/share/dotnet/dnx-coreclr-linux-x64.1.0.0-beta6-11944 \
node sample.js
Scripting Node.js from CLR
If you are writing a CLR application (e.g. a C# console application or ASP.NET web app), this section explains how you include and run Node.js code in your app. Currently it works on Windows using desktop CLR, but support for MacOS, and Linux as well as .NET Core is coming soon.
What you need
You need Windows with:
- .NET 4.5
- Edge.js NuGet package
- Node.js (optional, if you want to use additional NPM packages)
Edge.js support for scripting Node.js ships as a NuGet Package called Edge.js
. It comes with everything you need to get started writing applications for x86 and x64 architectures. However, if you want to use additional Node.js packages from NPM, you must separately install Node.js runtime to access the NPM package manager. The latest Edge.js NuGet package has been developed and tested with Node.js v8.10.0. Older Edge.js packages exist for prior versions of Node.js. If you choose a different version of Node.js to install NPM packages, your mileage can vary.
NOTE you cannot use native Node.js extensions when scripting Node.js from CLR using Edge.
You can install the Edge.js NuGet package using the Visual Studio built-in NuGet package management functionality or using the stand-alone NuGet client.
How to: Node.js hello, world
Create a .NET 4.5 Console Application in Visual Studio. Add the Edge.js NuGet package to the project. Then in your code:
using System;
using System.Threading.Tasks;
using EdgeJs;
class Program
{
public static async Task Start()
{
var func = Edge.Func(@"
return function (data, callback) {
callback(null, 'Node.js welcomes ' + data);
}
");
Console.WriteLine(await func(".NET"));
}
static void Main(string[] args)
{
Start().Wait();
}
}
Compile and run:
C:\project\sample\bin\Debug> sample.exe
Node.js welcomes .NET
How to: integrate Node.js code into CLR code
The Edge.js NuGet package contains a single managed assembly EdgeJs.dll
with a single class EdgeJs.Edge
exposing a single static function Func
. The function accepts a string containing code in Node.js that constructs and returns a JavaScript function. The JavaScript function must have the signature required by Edge.js's prescriptive interop pattern: it must accept one parameter and a callback, and the callback must be called with an error and one return value:
var func = Edge.Func(@"
return function (data, callback) {
callback(null, 'Hello, ' + data);
}
");
Edge.js creates a Func<object,Task<object>>
delegate in CLR that allows .NET code to call the Node.js function asynchronously. You can use the standard TPL mechanisms or the async/await keywords to conveniently await completion of the asynchornous Node.js function:
var result = await func(".NET");
// result == "Hello, .NET"
Note that the Node.js code snippet is not a function definition. Instead it must create and return a function instance. This allows you to initialize and maintain encapsulated Node.js state associated with the instance of the created function. The initialization code will execute only once when you call Edge.Func
. Conceptually this is similar to defining a Node.js module that exports a single function (by returning it to the caller). For example:
var increment = Edge.Func(@"
var current = 0;
return function (data, callback) {
current += data;
callback(null, current);
}
");
Console.WriteLine(await increment(4)); // outputs 4
Console.WriteLine(await increment(7)); // outputs 11
Using multiline C# string literals is convenient for short Node.js code snippets, but you may want to store larger Node.js code in its own *.js
file or files.
One pattern is to store your Node.js code in a myfunc.js
file:
return function (data, callback) {
callback(null, 'Node.js welcomes ' + data);
}
And then load such file into memory with File
:
var func = Edge.Func(File.ReadAllText("myfunc.js"));
Another pattern is to define a Node.js module that itself is a function:
module.exports = function (data, callback) {
callback(null, 'Node.js welcomes ' + data);
};
And then load and return this module with a short snippet of Node.js:
var func = Edge.Func(@"return require('./../myfunc.js')");
(Note the relative location of the file).
How to: use Node.js built-in modules
You can use Node.js built-in modules out of the box. For example, you can set up a Node.js HTTP server hosted in a .NET application and call it from C#:
var createHttpServer = Edge.Func(@"
var http = require('http');
return function (port, cb) {
var server = http.createServer(function (req, res) {
res.end('Hello, world! ' + new Date());
}).listen(port, cb);
};
");
await createHttpServer(8080);
Console.WriteLine(await new WebClient().DownloadStringTaskAsync("http://localhost:8080"));
How to: use external Node.js modules
You can use external Node.js modules, for example modules installed from NPM.
Note: Most Node.js modules are written in JavaScript and will execute in Edge as-is. However, some Node.js external modules are native binary modules, rebuilt by NPM on module installation to suit your local execution environment. Native binary modules will not run in Edge unless they are rebuilt to link against the NodeJS dll that Edge uses.
To install modules from NPM, you must first install Node.js on your machine and use the npm
package manager that comes with the Node.js installation. NPM modules must be installed in the directory where your build system places the Edge.js NuGet package (most likely the same location as the rest of your application binaries), or any ancestor directory. Alternatively, you can install NPM modules globally on the machine using npm install -g
:
C:\projects\websockets> npm install ws
...
[email protected] node_modules\ws
├── [email protected]
├── [email protected]
├── [email protected]
└── [email protected]
You can then use the installed ws
module to create a WebSocket server inside of a .NET application:
class Program
{
public static async void Start()
{
var createWebSocketServer = Edge.Func(@"
var WebSocketServer = require('ws').Server;
return function (port, cb) {
var wss = new WebSocketServer({ port: port });
wss.on('connection', function (ws) {
ws.on('message', function (message) {
ws.send(message.toUpperCase());
});
ws.send('Hello!');
});
cb();
};
");
await createWebSocketServer(8080);
}
static void Main(string[] args)
{
Task.Run((Action)Start);
new ManualResetEvent(false).WaitOne();
}
}
This WebSocket server sends a Hello message to the client when a new connection is established, and then echos a capitalized version of every message it receives back to the client. You can test this webserver with the wscat
tool included with the ws
module. To make it convenient to use, first install the ws
module globally:
npm install ws -g
Then start the .NET application conatining the WebSocket server and establish a connection to it with wscat
:
C:\projects\websockets> wscat -c ws://localhost:8080/
connected (pr