How to invoke Node.js code from .Net

With the Microsoft.AspNetCore.NodeServices NuGet package, a customer application can invoke Node.js code from .Net. This can, for example, be used to generate page and block thumbnails on the server side. Then you avoid doing it in the browser, which has some limitations and known issues.

Requirements

1. Node.js:

• For installation in server environments we recommend the LTS version of Node.js.
• Make sure that node and npm are available as environment variables so that .Net can find and invoke them.

2. Litium 7.4 or later

• Node services are included in Litium 7.4 and later versions. 

Installation

Litium automatically installs, deploys and configures everything by default. No additional action is required. The JavaScript files are deployed to Src\Files\NodeServices, under a folder named after the Litium version in question. Litium also executes npm install against that folder to make sure all dependencies are installed. The feature generateThumbnailsAtServerSide is also activated be default.

This behavior can be customized and NodeServices can be installed manually.

Manual installation

As mentioned above, the default installation deploys JavaScript files to Src\Files\NodeServices, under a folder named after the current Litium version. To use another folder:

1. Copy the NodeServices folder in packages\Litium.Web.Setup.Core.7.4.X\tools to the desired folder.

2. Open the command prompt and navigate to this folder, which should contain package.json files. Then you execute the command npm install. Be careful and make sure you do this correctly.

3. Make sure AppPool is running under an account that has read-permission to the folder.

4. Configure projectPath in web.config to point to the folder:

<nodeServices generateThumbnailsAtServerSide="true" projectPath="path\to\NodeServices\folder\that\contains\packagejson" />

Configuration

Deactivate generateThumbnailsAtServerSide

This feature is activated by default. To deactivate it, find the nodeServices configuration in Web.config and set generateThumbnailsAtServerSide to false:

<nodeServices generateThumbnailsAtServerSide="false" invocationTimeoutMilliseconds="60000" />

invocationTimeoutMilliseconds

invocationTimeoutMilliseconds is the maximum duration in milliseconds that .NET code should wait for Node.js RPC calls to return. If Node.js does not return within this time, the .Net application will throw an exception. The default value is 60 seconds. This is to make sure the request has enough time for the cold-start of the website, in order to render it and capture the thumbnail.

navigationTimeoutMilliseconds

navigationTimeoutMilliseconds is the maximum navigation time in milliseconds that Node.js should wait for a browser to finish a navigation. If the load event is not fired within this time, an exception will be thrown. The default value is 30 seconds. Pass 0 to disable.

projectPath

This path should be used to have one common NodeServices folder for multiple web instances. The value of projectPath should be the path to the folder that contains the package.json file. Make sure all required steps are covered as described in Manual installation.

Note: the content of NodeServices should match the Litium version, since they depend on each other. Running mismatched versions may lead to unexpected errors.

browserExecutablePath

Path to a Chromium or Chrome executable to run instead of the bundled Chromium. This should be used in case you want to use a specific version of Chrome, or Chromium. One particular case is when you need to generate thumbnails for Video at the server side. Litium uses Puppeteer under the hood to generate pages and blocks' thumbnails. There is an issue where MP4 video for example, cannot be played on Chromium. Some other features might not work with Chromium, as described here.

In order to be able to generate thumbnails for video, at the server side using NodeServices, we can configure Puppeteer to use Chrome instead, for example:

<nodeServices generateThumbnailsAtServerSide="true" invocationTimeoutMilliseconds="60000" browserExecutablePath="C:\Program Files (x86)\Google\Chrome\Application\chrome.exe" />

Make sure the compatible version of Chrome is used as described in this article. To check what version of Chrome we have, open chrome://version/ in Chrome. For example, this says we are using Chrome 75:

Then edit Src\Files\NodeServices/package.json file, or the one in your custom folder if Manual installation was used, to remove puppeteer dependency, then execute this command to install puppeteer-core which is compatible with Chrome 75:

npm install puppeteer-core@chrome-75

Note: if browserExecutablePath is not used, by setting it as empty, puppeteer should be used instead of puppeteer-core.

Troubleshooting

Debug and error messages can be found in the Event log page, or the log file. Common problems are:

• node or npm could not be found: make sure they can be found by setting the system environment variable PATH correctly.
• Unable to create or access folder: make sure Application Pool is running under an account that has read and write permission to the projectPath folder. Running Application Pool under ApplicationPoolIdentity can be a problem when the npm command is executed.
• Error: EPERM: operation not permitted, mkdir 'C:\Windows\system32\config\systemprofile\AppData\Roaming\npm': make sure Load User Profile is enabled for ApplicationPool.

If an error occurs during the installation process, NodeServices will be disabled, generateThumbnailsAtServerSide will be set to false and thumbnails will be generated by the browser.