Instrument a .NET Worker Role on Azure Cloud Service

A Worker Role is a non-web process run as an Azure Cloud Service. This describes the process for monitoring a Worker Role.

In order to install the .NET agent, you must have Administrator rights in your Windows admin group. You can be logged in as an administrator user, be a member of the Administrators group, or (on newer operating systems) provide elevation credentials when prompted.


To instrument a Worker Role, you must meet these basic requirements:

  • The New Relic NuGet package for Cloud Services must be installed.
  • Custom transactions must be created. The .NET agent automatically instruments external calls and database calls, but instruments no default methods for transactions. By creating custom transactions, data will appear in the the New Relic APM Overview and Transactions pages under the Non-web category.


The NuGet installer automatically adds the NewRelic.AppName parameter to the application config, which appears as <YOUR_WORKER_ROLE_NAME>.dll.config in E:\approot. The agent also automatically instruments WaWorkerHost.exe, which is the name of the actual Worker Role process.

Custom Transaction Example

This is a custom transaction example for a worker role. It creates a custom transaction named ProcessMessage. The transaction begins when the ProcessMessage method is entered, and ends when the method returns.

In the following example MyWorkerRole is used as the name space. If you do not specify a name, it will default to the solution name.

Assume the following code:

namespace MyWorkerRole
    public class NotificationQueue
        public bool ProcessMessage(Message message) {
            // code to process message

Here is the custom instrumentation file for the code above:

<?xml version="1.0" encoding="utf-8"?>
<extension xmlns="urn:newrelic-extension">
    <tracerfactory name="NewRelic.Agent.Core.Tracer.Factories.BackgroundThreadTracerFactory" metricName="Custom/ProcessMessage">
      <match assemblyname="MyWorkerRole" classname="MyWorkerRole.NotificationQueue">
        <exactmethodmatcher methodName="ProcessMessage" />

On a local installation, this instrumentation file will go in C:\ProgramData\New Relic\.NET Agent\Extensions.

Optional: send the file up with Azure Cloud Service

To send the file up with an Azure Cloud Service deployment:

  1. In your Azure Cloud project, add the instrumentation file to your Worker Role inside the Roles folder.
  2. After installing the New Relic .NET agent NuGet package, locate newrelic.cmd in your Worker Role project.
  3. Find the statement IF %ERRORLEVEL% EQU 0 within the :INSTALL_NEWRELIC_AGENT block and add the following statement to the conditional:

          copy /Y "%RoleRoot%\approot\MyInstrumentation.xml" "%NR_HOME%\extensions" >> %RoleRoot%\nr.log
        ) ELSE (

    In this example, the newrelic.cmd batch file copies the custom instrumentation file to the Extensions folder in D:\ProgramData\New Relic\.NET Agent\, or %NR_HOME%. MyInstrumentation.xml was used in this example, but any name will work as long as the filename and copy command match, and the file is valid XML.

  4. After the Worker Role starts up and the method executes, transaction information will appear in the Non-web category for your APM application.

For more help

Additional documentation resources include:

Join the discussion about .NET monitoring in the New Relic Online Technical Community! The Technical Community is a public platform to discuss and troubleshoot your New Relic toolset.

If you need additional help, get support at