Skip to content

Latest commit

 

History

History
127 lines (92 loc) · 5.86 KB

MODULE_CREATION.md

File metadata and controls

127 lines (92 loc) · 5.86 KB
Raw

🔧 Creation of WinRT Modules

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 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:

const { Geolocator } = require('windows.devices.geolocation')
const locator = new Geolocator()

locator.getGeopositionAsync((error, result) => {
  if (error) {
    console.error(error)
    return
  }

  const { coordinate } = result
  const { longitude, latitude } = coordinate

  console.info(longitude, latitude)
})

Table of Contents

Prerequisites

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 2019, 2017, or 2015 for generating Windows 10 compatible modules
  • Visual Studio 2013 or 2012 for generating Windows 8.1/8 compatible modules respectively.
  • Windows SDK for the version of Windows your are using:
  • node.js (version > 8.*) - 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:

Windows.Devices.Geolocation NodeRT module contents

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 CLI

If you prefer a command line interface, modules can be created with 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" --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 [Vs2019|Vs2017|Vs2015|Vs2013|Vs2012] Optional, VS version to use, default is Vs2019

 --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