iisnode

To run functional tests, ensure iisnode is installed for IIS 7.x/8.x.

Note: To ensure WebSocket tests pass, you must be running IIS 8.x on Windows 8 or Windows Server 2012.

Execute the following command from the repository root: test\functional\test.bat

To host Node.js applications on a standard IIS installation, download and install the appropriate MSI package based on your system's bitness (x86 or x64).

Prerequisites:

• Windows Vista, 7, 8, or Windows Server 2008/2012.
• IIS 7.x with IIS Management Tools and ASP.NET.
• URL Rewrite module for IIS.
• Latest Node.js build for Windows.

Setup Samples: After installation, you can set up sample applications by running the setup batch file from an administrative command prompt: %programfiles%\iisnode\setupsamples.bat

Once configured, you can access samples at http://localhost/node.

For local development using IIS Express or WebMatrix, follow these steps:

1. WebMatrix: Install WebMatrix using the Web Platform Installer. Open WebMatrix, select "Site from folder", and navigate to %localappdata%\iisnode\www to find and run iisnode samples.
2. IIS Express 8 on Windows x64: Since IIS Express 8 provides both 32-bit and 64-bit versions, you have two options:
   • Option A (Recommended): Install the full x64 version of iisnode. In Visual Studio, navigate to Tools > Options > Projects and Solutions > Web Projects and enable Use the 64 bit version of IIS Express. This allows a single installation to serve both IIS and IIS Express.
   • Option B: Separately install the specific iisnode express version.

To build iisnode, you must first set up a build environment using the Visual Studio Developer Command Prompt.

Prerequisites for building:

• All installation prerequisites.
• Visual Studio Express 2012 for Windows Desktop.
• WIX Toolset v3.6.
• Windows SDK for Windows 8.

Build Steps:

1. Open a command prompt using the Visual Studio environment: "%programfiles(x86)%\Microsoft Visual Studio 11.0\Common7\Tools\VsDevCmd.bat"
2. Run msbuild with the appropriate platform flag.

Output Locations:

• IIS 7.x/8.0: build\debug\{x64|x86}\iisnode-full.msi
• IIS Express 7.x: build\debug\x86\iisnode-express.msi

# For x86 build
msbuild /p:Platform=Win32 src\iisnode\iisnode.sln

# For x64 build
msbuild /p:Platform=x64 src\iisnode\iisnode.sln

Tracing in iisnode is categorized by an area and a verbosity level.

• Area: iisnode uses the WWWServerTraceProvider with the IISNODE area flag (0x8000).
• Verbosity: The level parameter passed to logging functions determines the verbosity. Tracing is only active if the current IIS trace configuration's verbosity is greater than or equal to the level being logged.

iisnode uses the following Provider GUID for its trace events: {3a2a4e84-4c21-4981-ae10-3fda0d9b0f83}

When hosting a Node.js application in IIS, the web server controls the base address of the application. IIS provides this address to your Node.js process via the process.env.PORT environment variable. You must use this variable when starting your HTTP server listener to ensure the application correctly binds to the port assigned by IIS.

var http = require('http');

http.createServer(function (req, res) {
    res.writeHead(200, {'Content-Type': 'text/html'});
    res.end('Hello, world!');
}).listen(process.env.PORT);

When hosting Node.js applications in IIS using iisnode, all stdout and stderr output (such as console.log) is automatically captured. This output is stored in files on the disk and can be accessed via an HTTP endpoint.

By default, if your application is hosted at http://localhost/node/logging/hello.js, the logs will be available at http://localhost/node/logging/iisnode/. Note that the log endpoint is typically only available after the application endpoint has been visited at least once.

Viewing Logs

If loggingEnabled is set to true, stdout and stderr are captured.

• Logs are stored in the directory specified by logDirectory (relative to the application file).
• An index.html is maintained in the log directory to view logs via HTTP.
• Default Access: If your app is at http://foo.com/bar.js, logs are at http://foo.com/iisnode.

Debugging

If debuggingEnabled is set to true, you can use the built-in Node.js debugger.

• Access: The debugger is available at [app-url]/[debuggerPathSegment] (default is debug).
• Requirement: Requires a WebKit-enabled browser.
• Example: For http://foo.com/bar/baz.js, access the debugger at http://foo.com/bar/baz.js/debug.

To allow IIS to serve a specific Node.js file (e.g., index.js) when a request URL does not specify a filename (e.g., http://localhost/node/defaultdocument/), use the <defaultDocument> element in your web.config.

Ensure that the file is also registered in the <handlers> section so that iisnode handles the request correctly.

<configuration>
  <system.webServer>
    <handlers>
      <add name="iisnode" path="index.js" verb="*" modules="iisnode" />
    </handlers>

    <defaultDocument enabled="true">
      <files>
        <add value="index.js" />
      </files>
    </defaultDocument>
  </system.webServer>
</configuration>

To host an Express.js application in IIS, you must configure a web.config file to map incoming requests to your entry point file (e.g., hello.js) using the iisnode handler.

Because IIS manages the URL space, you should use the IIS URL Rewrite module to redirect specific URL branches to your Node.js application. This ensures that requests like http://localhost/myapp/foo are correctly routed to your Express application's internal routing logic.

var express = require('express');

var app = express.createServer();

app.get('/node/express/myapp/foo', function (req, res) {
    res.send('Hello from foo! [express sample]');
});

app.get('/node/express/myapp/bar', function (req, res) {
    res.send('Hello from bar! [express sample]');
});

app.listen(process.env.PORT);

iisnode configuration can be managed in two ways:

1. web.config: Use the <iisnode /> element within the <system.webServer> section of your application's web.config file.
2. iisnode.yml: Create an iisnode.yml file in your application directory to provide overrides for the settings defined in web.config. The YAML format is a small subset of standard YAML (key: value pairs).

To register a Node.js file (e.g., hello.js) to be handled by iisnode, add a handler in your web.config:

<system.webServer>
  <handlers>
    <add name="iisnode" path="hello.js" verb="*" modules="iisnode" />
  </handlers>
</system.webServer>