digideskio / nodert

Winrt APIs-node.js modules generator

NodeRT

[New!] NodeRT modules are now available as npm packages under the nodert-win10 scope!

[New!] Now supporting Windows 10 and latest versions of node.js + Electron!

WinRT modules generator for node.js

NodeRT is a tool that automatically generates node.js Native add-on wrappers for UWP/WinRT APIs.

NodeRT automatically exposes Microsoft’s UWP/WinRT APIs to the node.js environment by generating node modules. This enables node.js developers to write code that consumes native Windows capabilities. The generated modules' APIs are (almost) the same as the UWP/WinRT APIs listed in MSDN. NodeRT can be used to generate node.js modules both from command line (NodeRTCmd) and from its UI tool (NodeRTUI).

NodeRT is developed and released by a group of node.js enthusiasts at Microsoft.

Here is an example of using NodeRT windows.devices.geolocation module to retrieve the current location:

var geolocation = require('windows.devices.geolocation');
var locator = new geolocation.Geolocator();

locator.getGeopositionAsync( function(err, res) {
  if (err) {
    console.error(err);
    return;
  }

  console.info('(', res.coordinate.longitude, ',',  res.coordinate.latitude, ')');
});

In general, any WinRT/UWP API that can be called by a desktop app can by called by node.js/Electron using NodeRT. For more details about of desktop supported WinRT/UWP APIs, please visit this page.

For more examples of what NodeRT can do, check out our samples section.

---

Documentation

NodeRT Prerequisites

Generating a NodeRT module using the UI

Generating a NodeRT module using the cmd line interface

Building for Electron

Consuming a NodeRT module in node.js/Electron

License

Attributions

Contribute

---

NodeRT Prerequisites

First, in order to use WinRT you must be running on a Windows environment that supports WinRT- meaning Windows 10, Windows 8.1, Windows 8, or Windows Server 2012.

In order to use NodeRT, make sure you have the following installed:

• Visual Studio 2015, or VS 2015 Express for Windows Desktop, for generating Windows 10 compatible modules, or Visual Studio 2013/2012 for generating Windows 8.1/8 compatible modules repsectively.
  
• Windows SDK for the version of Windows your are using:
  • Windows 10 SDK
  • Windows 8.1 SDK
  • Windows 8
• node.js (version > 10.*) - from nodejs.org
  
• node-gyp - make sure to get the latest version from npm by running:

npm install -g node-gyp

Next, download the latest NodeRT release from here, or clone this repository to your machine and build the NodeRT solution using Visual Studio.

---

Generating a NodeRT module using the UI

First, launch the UI tool by running NodeRTUI.exe:

Then, follow this short list of steps in order to create a NodeRT module:

• Choose a WinMD file:
  
  • For Windows 10 SDK:
    

  c:\Program Files (x86)\Windows Kits\10\UnionMetadata\Windows.winmd
  

  • For Windows 8.1 SDK:
    

  c:\Program Files (x86)\Windows Kits\8.1\References\CommonConfiguration\Neutral\Windows.winmd
  

  • For Windows 8.0 SDK:
    

  c:\Program Files (x86)\Windows Kits\8.0\References\CommonConfiguration\Neutral\Windows.winmd
  

• Choose a namespace to generate from the list of namespaces.
  
• Select whether you are generating a Windows 10 compatible module using VS 015, Windows 8.1 compatible module using VS2013 or a Windows 8.0 compatible module using VS2012.
  
• Choose the output directory in which the module will be created, or just stick with the default ones.
• You're good to go, hit the Generate & Build button! A message box with (hopefully) a success message should appear shortly.
  

---

Generating a NodeRT module using the cmd line interface

NodeRT modules generation is available via a cmd-line interface using the NodeRTCmd tool.

An example of generating the Windows.Devices.Geolocation namespace from the Windows 10 Windows.winmd:

NodeRTCmd.exe --winmd "c:\Program Files (x86)\Windows Kits\10\UnionMetadata\Windows.winmd" --codegendir c:\NodeRT\codegen --outdir c:\NodeRT\output --namespace Windows.Devices.Geolocation

Note that omitting the --namespace option will generate all of the namespaces in the Winmd file.

The following is the list of options that the tool supports:

 --winmd [path]              File path to winmd file from which the module
                             will be generated

 --namespaces                Lists all of the namespaces in the winmd file
                             (only needs --winmd)

 --namespace [namespace]     The namespace to generate from the winmd when
                             not specified , all namespaces will be generated

 --outdir [path]             The output dir in which the compiled NodeRT module
                             will be created in

 --vs [Vs2015|Vs2013|Vs2012] Optional, VS version to use, default is Vs2015
 
 --winver [10|8.1|8]         Optional, Windows SDK version to use, default is 10

 --npmscope                  Optional, the scope that will be specified for the generated
                             npm package

 --npmversion                Optional, the version that will be specified for the generated
                             npm package
							   
 --nodefgen                  Optional, specifying this option will reult in
                             skipping the generation of TypeScript and
                             JavaScript definition files

 --nobuild                   Optional, specifying this option will result in
                             skipping the build process for the NodeRT module	
			     
 --verbose                   Optional, specifying this option will result in
                             verbose output for the module build operation

 --help                      Print this help screen

---

Building for Electron

In order to build the generated NodeRT module for Electron, you can follow the instructions in here.

The easiest way to build the module for Electron, is probably to run node-gyp directly from the module folder with the appropriate cmd-line arguments.

For example, opening the cmd-line, cd-ing to the generated module directory and running:

node-gyp rebuild --target=1.3.1 --arch=x64 --dist-url=https://atom.io/download/atom-shell

Just make sure to use the correct Electron version for the "target" argument (here we used 1.3.1).

After rebuilding the module - you can copy it to your Electron app node_modules directory (in case you havn't done that already) and use it like every other node.js/Electron module.

---

Consuming a NodeRT module in node.js/Electron

Requiring a generated NodeRT module is just like requiring any other node.js module - if for example, you've just generated Windows.Devices.Geolocation, copy the generated windows.devices.geolocation directory from the output folder to a node_modules folder near you (or use a full path), and run:

var geolocation = require('windows.devices.geolocation');

If you are working in the node console (AKA REPL), then entering geolocation will result in printing the contents of the namespace:

Creating a new WinRT object is done with the new operator. In order to inspect the method and properties of the object, you can print its prototype: For example, creating a new Geolocator object in REPL:

var locator = new geolocation.Geolocator();
//print the prototype
locator.__proto__

And the output will be:

(Note that property values are fetched on the fly, and hence have undefined values when printing the prototype)

Classes and fields naming

We use the same convention used for WinRT javascript applications:

• Class/Enum names have the first letter in upper-case

• Class/Enum fields, that is properties, methods, and events, both member and static have the first letter in lower-case, the rest of the name is according to MSDN.

• Enums are just javascript objects with keys corresponding to the enum fields and values to the enum fields numeric values.

Properties

Using Properties of an object is just straight-forward javascript, for example:

locator.reportInterval = 2000;
console.info(locator.reportInterval);

Synchronous methods

Again, straight-forward javascript, just make the call with the appropriate arguments. If there are several WinRT overloads for the method, make the call with the right set of arguments and the correct overload of the method will be called:

var xml = require('windows.data.xml.dom');
var xmlDoc = new xml.XmlDocument();
toastXml.loadXml('<node>some text here</node>');

Asynchronous methods

Each async method accepts the same variables as are listed in the MSDN, with the addition of a completion callback as the last argument.
This callback will be called when the function has finished, and will receive an error as the first argument, and the result as the second argument:

locator.getGeopositionAsync( function(err, res) {
  // result is of type geoposition
  if (err) {
    console.error(err);
    return;
  }

  console.info('(',res.coordinate.longitude, res.coordinate.latitude, ')');
});

Events

Registering to events is done using the class' on method (which is equivalent to addListener), which receives the event name (case insensitive) and the event handler function. For example:

var handler = function handler(sender, eventArgs) {
  console.info('status is:', eventArgs.status); 
};
locator.on('statusChanged', handler);

Unregistering from an event is done the same way, using the class's off or removeListener methods. Just make sure to store the event handler in order to be able to use it.

// using same event handler as in the example above
locator.off('statusChanged', handler);

Separation into namespaces and cross namespace usage

Each NodeRT module represents a single namespace.
For instance, windows.storage will have a NodeRT module, and windows.storage.streams will have another NodeRT module.
The reason for this separation is strictly due to performance considerations.
(We didn't want to have a huge NodeRT module that will cause the memory of node.js to blow up while most of the namespaces probably won't be used in each script).

This architecture means that in case you are using a NodeRT module which contains a function, property, or event which returns an object from another namespace, then you will need to require that namespace before calling that function/property/event.

For example:

var capture = require('windows.media.capture');
// we also require this module in order to be able to access device controller properties
var devices = require('windows.media.devices');

var capture = new capture.MediaCapture();
capture.initializeAsync(function (err, res) {
  if (err) {
    return console.info(err);
  }
  
  // get the device controller, its type (VideoDeviceController) is defined in the 
  // windows.media.devices namespace -  so, we had to require that namespace as well
  var deviceController = capture.videoDeviceController;
  
  // we can now use the VideoDeviceController regularly
  deviceController.brightness.trySetValue(-1);
});

Class inheritance and objects casting

Since some WinRT classes inherit from other classes, you might need to cast an object of a certain type to another type.

In order to do so, each NodeRT object has a static method named castFrom which accepts another object and tries to cast it to the class' type.

The following example casts an IXmlNode object to an XmlElement:

var xml = require('windows.data.xml.dom');

...

// obtain a list of nodes:
var nodesList = ....

var xmlNode = nodesList.getAt(0);

// cast xmlNode to XmlElement
var xmlEle = xml.XmlElement.castFrom(xmlNode);

// we can now use XmlElement functions
xmlEle.setAttribute('attr', 'value')

Using WinRT streams in node.js

In order to support the use of WinRT streams in node.js, we have created the nodert-streams module, which bridges between WinRT streams and node.js streams.

This bridge enable the conversion of WinRT streams to node.js streams, such that WinRT streams could be used just as regular node.js streams.

---

License

NodeRT is released under the Apache 2.0 license. For more information, please take a look at the license file.

---

Attributions

In order to build NodeRT we used these 2 great libraries: * RazorTemplates - https://github.com/volkovku/RazorTemplates * RX.NET - https://github.com/Reactive-Extensions/Rx.NET/

---

Contribute

You are welcome to send us any bugs you may find, suggestions, or any other comments. Before sending anything, please go over the repository issues list, just to make sure that it isn't already there.

You are more than welcome to fork this repository and send us a pull request if you feel that what you've done should be included.