.NET Core

System Requirements

  • ASP.NET Core 1.x or 2.x running on Windows
  • Support for ASP.NET Core 3.x and Linux coming soon

Installing the Agent

STEP 1 - Download the installer

Download the Raygun Agent on the server you would like to monitor

STEP 2 - Install the agent

Open the agent installer you downloaded and follow the on-screen prompts to install the agent

STEP 3 - Input your API key

Launch the Raygun Profiler Configuration. You’ll need an API key to register the agent. Create a new application in Raygun if you have not already, and navigate to the APM set up screen to find your API key.

Under the Agent tab set the Default API key and then Register the Agent.

STEP 4 - Attach to a .NET Core process

Open the .NET Core tab in the Raygun Profiler Configuration app.

If your .NET Core application is running then you can select it from the process list.

If your process is not listed then find the path to your process dll or exe and enter it into the assembly name field.

With your .NET Core process selected, click the Register button, then enter your Raygun application API Key into the dialog and click Save.

STEP 5 - Register the profiler

There are many ways in which a .NET Core application can be started, so we’ve listed some common methods along with the required environment variables needed to configure the Raygun APM profiler correctly. Click the Show Config button from the configuration screen to view this list.

STEP 6 - Update to the latest version of Raygun4Net

In your server side Visual Studio project(s) for this application, we recommended you update the Raygun4Net.AspNetCore NuGet package to the latest release in order to correlate data between Crash Reporting and APM.

You can do this by right clicking on the project, or by using the NuGet package manager console. Update the Raygun4Net package you have installed to the latest version.

Installing using the Raygun CLI tool

Another method for registering and profiling a .NET Core application is to use the Raygun CLI tool

1. Register your .NET Core process with the Raygun application API Key using the following command.

# Configure HelloWorldApp.dll with an API Key
rgc.exe -enable HelloWorldApp.dll -type dotnetcore -apikey xxx -startup 30 -norecycle

2. To start the process and automatically configure the correct environment variables you can bootstrap the execution of your .NET Core process using the following command.

# Start HelloWorldApp.dll process with profiler environment configured
rgc.exe -profile "%ProgramFiles%\dotnet\dotnet.exe" -arguments HelloWorldApp.dll -coreclr -apikey <APP-API-KEY> -startup 60

Integrating with Raygun4Net

By adding Raygun4Net.AspNetCore to your application Raygun APM unlocks advanced features and intelligence that helps to reduce the CPU overhead of the profiler.

If you’re already using Raygun4Net.AspNetCore in your web application then there is nothing more you need to do other than make sure you’re using version 6.2.0 or above.

For the full instructions on installing and configuring Raygun4Net.AspNetCore please refer to the Installation instructions for Crash Reporting.

Deregistering an application

1. To stop profiling a .NET Core application you’ll first need to remove the environment variables that were configured when your application starts. Once these have been removed, restart your application to stop profiling.

2. The final step is to remove the API Key configuration by going to the .NET Core tab in the Raygun Profiler Configuration tool. Select the configured process and click the Deregister button.


Experiencing high CPU

When restarting the application there is an overhead that could cause the CPU to spike, but this high usage shouldn’t persist. APM products will always have an overhead, but our goal is to ensure it’s the lowest overhead possible. 
The high CPU usage you’re experiencing is likely caused by a high method call count. We recommend setting up a blacklist for a selection of high count method calls and seeing if this improves the CPU usage.

If this issue persists, please reach out to our engineering support team via the contact page, or click contact us in the app.

Run status checks

Run some basic status checks by loading the “Raygun Profiler Configuration” application and switch to the “Help” tab. The basic status checks will automatically run and will display a traffic light for each check. Ensure that all status checks are showing green.

Alternatively you can run these same status checks using the CLI tool.

Running rgc.exe -status will produce a result that should look similar to this:

Running Raygun Agent status checks...
Agent status: Registered
Agent test: Connected to the Raygun Agent v1.0.*.0 on port 2790.
API test: Connected to the Raygun API at https://api2.raygun.com.
API key test: API key *** is valid
Profiler x86 test: 32-bit Profiler found at D:\home\Raygun\Profiler\1.0.*\x86\RaygunProfiler.dll.
Profiler x64 test: 64-bit Profiler found at D:\home\Raygun\Profiler\1.0.*\x64\RaygunProfiler.dll.

Run a profiler test

The “Raygun Profiler Configuration” tool has a function to run a test that will validate that a local test application can be executed and profiled. When this test is run the CLI tool is run in test mode and profiled. If the test is successful then a single trace will be sent to your Raygun application with a name of “Mindscape.Raygun.Agent.Cli.Program.Main”.

To run this test, open the “Raygun Profiler Configuration” tool, click on the “Help” tab and click on the “Run a profiler test” button.

Enabling detailed logging

The log files for the Raygun Agent are located under %ProgramData%\Raygun\AgentLogs\ on Windows.

To enable detailed logging for the Raygun Agent, simply add a configuration setting to %ProgramFiles(x86)%\Raygun\RaygunAgent\RaygunAgent.exe.config. Add a new element to the <appSettings> section like <add key="LogLevel" value="Verbose"/> (other options are Warning, Info, Verbose, Debug).

Save the configuration file changes and restart the “Raygun Agent” Windows service, e.g. sc stop RaygunAgent followed by sc start RaygunAgent.

Run a diagnostic session

Before running a diagnostic session you should enable debug mode for your application using the CLI. We also recommend that you deregister all applications other than the one you’re wanting to capture the diagnostic information for.

Running a diagnostics session will capture the following information and will help Raygun support to troubleshoot issues you’re having:

  • Snapshot of log files
  • Snapshot of agent settings and blacklist files
  • Agent log files with Log level of Debug automatically set
  • Trace package and source files generated during the session
  • A trace of data being sent from the profiler to the agent
  • Profiler log messages (only captured if debug mode is enabled)
# Register an app with debug mode enabled
rgc.exe -enable  -type IIS -apikey  -startup 0 -debugmode
# Start a diagnostics session that is uploaded to Raygun when complete
rgc.exe -auto-diagnostic 300

For more information on diagnostic command options, see the CLI documentation.

After you have run and uploaded a diagnostic session, please add the diagnostic session identifier to your Raygun Support case.

Still need help?

We are always happy to help with any questions you might have. If we can’t answer your technical enquiries through the documentation, please feel free to get in touch through our contact page.

Contact Us