Introduction to .NET agent install

This document gets you started with installing a New Relic .NET agent, and provides links to install instructions. New Relic has both a .NET core and a .NET Framework agent.

Compatibility and requirements

Compatibility and requirements: .NET Framework agent | .NET Core agent.

Install .NET agent

See the install instructions for your system:

For how to install both .NET agent types on the same server, see Install both agents.

Optional reading: A detailed install explanation

This is optional reading that gives a more in-depth explanation of what happens behind-the-scenes during a .NET agent install. For simple install instructions, see the install instructions above.

Install instructions will vary depending on your setup, but all .NET agent installs have the same underlying steps that must happen in order for an install to be successful. For installs on common frameworks, some of these steps will happen automatically. But understanding these underlying processes can help you troubleshoot or customize your install.

For a .NET agent to report data to your New Relic account, these things must happen:

  • A New Relic .NET agent is placed on your system.

  • Required environment variables are set. These allow the agent to attach to your application via the Microsoft Profiling API.

  • The user your application is running under is assigned read/write permissions for the directory where the .NET agent is installed.

  • .NET Framework agent only: applications you want to monitor must also be targeted. For IIS-hosted applications, this will happen automatically (except ASP.NET Core apps that target .NET Framework).

  • If the .NET agent doesn't automatically instrument your application (see framework support links below), you must custom instrument your app.

As mentioned, some of these steps will happen automatically for installs on common frameworks (like ASP.NET), but understanding these steps can help you troubleshoot or customize an install.

Related docs:

Install .NET Framework and .NET Core agents on same system

You can install a .NET Core agent and a .NET Framework agent on the same system, with the following requirements:

  • Separate directories: The .NET Core agent and .NET Framework agent must be installed in different directories.
  • Environment variables: The required environment variables are different for the .NET agents. Most install procedures will result in the environment variables being set for you but, depending on your set-up, you may need to set them manually.

For more help

Recommendations for learning more: