1. Home
  2. Product Guides
  3. APM
  4. Profiler Setup
  5. .NET on Windows

.NET on Windows

Raygun APM profiles ASP.NET, ASP.NET MVC, Web Forms, Web API, ASP.NET Core, and supported .NET Windows services on 64-bit Windows Server 2016 or newer.

Install the Raygun APM Agent for Windows before configuring an application.

Each application needs its own Raygun application API key. The key tells the Agent which Raygun application receives that process's traces. Configuration takes effect only after the IIS application pool or Windows service restarts. The CLR then loads the profiler and, for CoreCLR, the managed startup hook.

Open Raygun Configuration Utility from the Start menu, or run:

& 'C:\Program Files\Raygun\RaygunAgent\Agent3\Config\RaygunConfigurationUtil.exe'

The Configuration Utility is the recommended setup method for IIS. It configures selected application pools with their Raygun application API key and the correct profiler environment.

  1. Open the IIS / .NET Process tab.
  2. Select the application pool.
  3. Choose Register or Configure and enter the Raygun application API key for that application.
  4. Apply the change.
  5. Recycle the application pool or restart the site so the next worker process loads the profiler and, for CoreCLR, the startup hook.
  6. Generate application traffic and confirm traces appear in Raygun.

The configured profiler paths use stable latest selectors:

C:\Program Files\Raygun\RaygunProfiler\latest\x64\RaygunProfiler.dll
C:\Program Files (x86)\Raygun\RaygunProfiler\latest\x86\RaygunProfiler.dll

For ASP.NET Core and other modern .NET applications, Raygun also adds this stable startup-hook path to DOTNET_STARTUP_HOOKS:

C:\Program Files\Raygun\RaygunAgent\Agent3\Raygun.Apm.StartupHook.dll

The hook supplies automatic ASP.NET Core request identity across async execution. It does not require Raygun middleware, an application package, or source-code changes. Raygun preserves non-Raygun startup-hook entries when it adds or removes its path.

Do not replace the profiler paths with a version-specific directory.

If one application pool hosts more than one site, all sites in that pool inherit the same profiler environment and API key. Use a dedicated pool when the sites must report to different Raygun applications.

The current Agent includes an authenticated command line in RaygunAgent.exe. It does not use the retired rgc.exe workflow.

  1. Start the site and send it one request so its IIS worker process exists.
  2. Open an elevated PowerShell prompt.
  3. Discover the worker process:
$agent = 'C:\Program Files\Raygun\RaygunAgent\Agent3\RaygunAgent.exe'
& $agent app discover --web-only
  1. Register the required process. The command prompts for the API key without echoing it:
& $agent app register --process-id 1234
  1. Apply the saved configuration and recycle the application pool:
& $agent app enable --process-id 1234

Replace 1234 with the discovered worker process ID. A shared application pool requires explicit --allow-shared-pool consent on the register command. See the Raygun Agent command-line reference for noninteractive input, JSON output, unregistering, and recycle control.

Use this fallback only when the Configuration Utility and Agent command line cannot be used. Back up IIS configuration first:

& "$env:SystemRoot\System32\inetsrv\appcmd.exe" add backup BeforeRaygunAPM

Open the following file as Administrator:

C:\Windows\System32\inetsrv\config\applicationHost.config

Find the existing application-pool <add> element under system.applicationHost/applicationPools. The examples show the complete pool element for context. Copy the environmentVariables child into the existing pool; if that collection already exists, merge the listed variables into it. Do not create a second application-pool element or a second environmentVariables collection.

For a 64-bit ASP.NET Core or modern .NET pool, use:

<add name="MyApplicationPool" managedRuntimeVersion="">
  <environmentVariables>
    <add name="COMPLUS_ProfAPI_ProfilerCompatibilitySetting" value="EnableV2Profiler" />
    <add name="PROTON_API_KEY" value="YOUR_RAYGUN_APPLICATION_API_KEY" />
    <add name="PROTON_USE_MULTICAST" value="0" />
    <add name="PROTON_NETWORK_MODE" value="Udp" />
    <add name="CORECLR_ENABLE_PROFILING" value="1" />
    <add name="CORECLR_PROFILER" value="{e2338988-38cc-48cd-a6b6-b441c31f34f1}" />
    <add name="CORECLR_PROFILER_PATH" value="C:\Program Files\Raygun\RaygunProfiler\latest\x64\RaygunProfiler.dll" />
    <add name="CORECLR_PROFILER_PATH_32" value="C:\Program Files (x86)\Raygun\RaygunProfiler\latest\x86\RaygunProfiler.dll" />
    <add name="CORECLR_PROFILER_PATH_64" value="C:\Program Files\Raygun\RaygunProfiler\latest\x64\RaygunProfiler.dll" />
    <add name="DOTNET_STARTUP_HOOKS" value="C:\Program Files\Raygun\RaygunAgent\Agent3\Raygun.Apm.StartupHook.dll" />
  </environmentVariables>
</add>

If the pool already has a DOTNET_STARTUP_HOOKS value, append the Raygun path with a semicolon instead of replacing the existing startup hooks.

For a 64-bit .NET Framework 4 application pool, use:

<add name="MyApplicationPool" managedRuntimeVersion="v4.0">
  <environmentVariables>
    <add name="COMPLUS_ProfAPI_ProfilerCompatibilitySetting" value="EnableV2Profiler" />
    <add name="PROTON_API_KEY" value="YOUR_RAYGUN_APPLICATION_API_KEY" />
    <add name="PROTON_USE_MULTICAST" value="0" />
    <add name="PROTON_NETWORK_MODE" value="Udp" />
    <add name="COR_ENABLE_PROFILING" value="1" />
    <add name="COR_PROFILER" value="{e2338988-38cc-48cd-a6b6-b441c31f34f1}" />
    <add name="COR_PROFILER_PATH" value="C:\Program Files\Raygun\RaygunProfiler\latest\x64\RaygunProfiler.dll" />
    <add name="COR_PROFILER_PATH_32" value="C:\Program Files (x86)\Raygun\RaygunProfiler\latest\x86\RaygunProfiler.dll" />
    <add name="COR_PROFILER_PATH_64" value="C:\Program Files\Raygun\RaygunProfiler\latest\x64\RaygunProfiler.dll" />
  </environmentVariables>
</add>

For a pool with Enable 32-Bit Applications set to True, change the unsuffixed CORECLR_PROFILER_PATH or COR_PROFILER_PATH value to the x86 path. Keep both the _32 and _64 values.

Save the file, then recycle only the configured pool:

Import-Module WebAdministration
Restart-WebAppPool -Name 'MyApplicationPool'

The API key is stored in IIS configuration and inherited by the worker process. Protect access to applicationHost.config, backups, and any deployment templates that contain it.

Use the Raygun Agent command line to discover, register, and enable a supported running .NET Windows service. Restart the service after configuration so its CLR loads the profiler and, for CoreCLR, the startup hook.

Do not add the Raygun profiler variables to the RaygunAgent service itself. The Agent must not profile its own process.

For IIS, remove the application from profiling in the Configuration Utility. For a Windows service, use the Agent command line. Then restart or recycle the application. A running process keeps its already-loaded profiler and startup hook until the process exits.

Removing an application from profiling does not uninstall the Agent and does not affect other configured applications.

Confirm the Agent is healthy:

Get-Service -Name RaygunAgent
Invoke-RestMethod http://127.0.0.1:18100/status

After recycling the pool and sending it a request, confirm that its worker loaded the profiler:

Get-Process -Name w3wp -Module -ErrorAction SilentlyContinue |
  Where-Object ModuleName -eq 'RaygunProfiler.dll'

For an ASP.NET Core application, also confirm that its environment contains the stable Raygun path in DOTNET_STARTUP_HOOKS. Finally, generate traffic through real application routes and check the Raygun Traces page. Seeing the Agent service running proves only that the Agent is available; it does not prove that a particular application loaded the profiler and startup hook.

If traces do not appear, follow Windows troubleshooting.

On this page: