Install the .NET Library on Azure App Service

The .NET Library provides detailed insight and distributed tracing for .NET Framework 4.6.2+ and .NET 8+ applications running in Azure App Service. The .NET Library can be installed using the SolarWinds Observability SaaS Azure Site Extension or using the SolarWindsAPM.OpenTelemetry.Agent NuGet package.

Before you start

Verify the following to ensure the library can collect and transmit data:

• The platform where your APM library will be installed is supported.

• Your application components are supported by the library.

• Your firewall configuration permits TCP/HTTPS/TLS outbound connections to otel.collector.xx-yy.cloud.solarwinds.com and apm.collector.xx-yy.cloud.solarwinds.com port 443, where xx-yy is determined by the URL you use to access SolarWinds Observability SaaS, described in Data centers and endpoint URIs. See Firewall or access control requirements.

  If your firewall or access control requirements do not allow such connections, configure the library to send data through a proxy.

Do not run other APM libraries alongside the SolarWinds Observability .NET Library. See Do you have another profiler installed?.

Install the .NET Library using the SolarWindsAPM OpenTelemetry Azure App Services Site Extension (Windows only)

The SolarWindsAPM.Agent.AzureAppServices.Extension has been deprecated and will be delisted. The SolarWindsAPM.OpenTelemetry.Agent.AzureAppServices.Extension should be used.

To install the SolarWinds Observability .NET Library SolarWindsAPM OpenTelemetry Azure App Services Site Extension Package in your Azure Web App:

1. Ensure that Application Insights is disabled. This can be checked under the Settings > Application Insights section for the App Service.

2. In the Development Tools section of the Azure Web App, click Extensions.

3. Click the Add button and select SolarWindsAPM .NET Agent OpenTelemetry Azure App Services Extension(version)--SolarWindsAPM from the list.

4. To configure the .NET Library, navigate to the Application Settings in the configuration settings. Add the following application global environment variables:

   .NET 8+

   Environment variable	Environment variable value
   SW_APM_SERVICE_KEY	For Azure App Services, the Service key is used to identify your account. It is shown in the Add Data dialog when you add the new service.  It is in the form of YourApiToken:YourServiceName. Replace YourApiToken with the SolarWinds Observability API token (ingestion type) generated for this service, and the YourServiceName will only be a placeholder if OpenTelemetry is enabled for the App Service. When OpenTelemetry is enabled, the service name will be set to the name of the Azure App Service. This configuration can also be set as the ServiceKey key in the solarwinds_apm.config file. To override the service name when OpenTelemetry is enabled, the OTEL_SERVICE_NAME environment variable can be used to set the service name.
   SW_APM_HOME_DOTNET	C:\home\SiteExtensions\SolarWindsAPM.OpenTelemetry.Agent.AzureAppServices.Extension\SolarWindsAPM
   SW_APM_COLLECTOR	Set the APM collector endpoint corresponding to your tenant. To determine the correct value, see Data centers and endpoint URIs. This configuration can also be set as the ApmCollector key in the solarwinds_apm.config file.
   CORECLR_ENABLE_PROFILING	1
   CORECLR_PROFILER	{AAAA7777-11FE-4F94-8EDA-312C0EDF4141}
   SW_APM_OPEN_TELEMETRY	Enabled
   CORECLR_PROFILER_PATH_32	C:\home\SiteExtensions\SolarWindsAPM.OpenTelemetry.Agent.AzureAppServices.Extension\SolarWindsAPM\x86\solarwinds_apm_profiler.dll
   CORECLR_PROFILER_PATH_64	C:\home\SiteExtensions\SolarWindsAPM.OpenTelemetry.Agent.AzureAppServices.Extension\SolarWindsAPM\x64\solarwinds_apm_profiler.dll

   .NET Framework

   Environment variable	Environment variable value
   SW_APM_SERVICE_KEY	For Azure App Services, the Service key is used to identify your account. It is shown in the Add Data dialog when you add the new service. It is in the form of YourApiToken:YourServiceName. Replace YourApiToken with the SolarWinds Observability API token (ingestion type) generated for this service, and the YourServiceName will only be a placeholder if OpenTelemetry is enabled for the App Service. When OpenTelemetry is enabled, the service name will be set to the name of the Azure App Service. This configuration can also be set as the ServiceKey key in the solarwinds_apm.config file. To override the service name when OpenTelemetry is enabled, the OTEL_SERVICE_NAME environment variable can be used to set the service name.
   SW_APM_HOME_DOTNET	C:\home\SiteExtensions\SolarWindsAPM.OpenTelemetry.Agent.AzureAppServices.Extension\SolarWindsAPM
   SW_APM_COLLECTOR	Set the APM collector endpoint corresponding to your tenant. To determine the correct value, see Data centers and endpoint URIs. This configuration can also be set as the ApmCollector key in the solarwinds_apm.config file.
   COR_ENABLE_PROFILING	1
   COR_PROFILER	{AAAA7777-11FE-4F94-8EDA-312C0EDF4141}
   SW_APM_OPEN_TELEMETRY	Enabled
   COR_PROFILER_PATH_32	C:\home\SiteExtensions\SolarWindsAPM.OpenTelemetry.Agent.AzureAppServices.Extension\SolarWindsAPM\x86\solarwinds_apm_profiler.dll
   COR_PROFILER_PATH_64	C:\home\SiteExtensions\SolarWindsAPM.OpenTelemetry.Agent.AzureAppServices.Extension\SolarWindsAPM\x64\solarwinds_apm_profiler.dll
   COMPLUS_LoaderOptimization	1

   The .NET Library is installed in the <system_drive>:\home\SiteExtensions directory, where <system_drive> is the system drive of your App Service. The examples above assume the system drive is C:.

   For both .NET 8+ and .NET Framework applications, log files can be found in <system_drive>:\home\LogFiles\SolarWinds.

   The solarwinds_apm.config file for the extension is located at: C:\home\SiteExtensions\SolarWindsAPM.Agent.AzureAppServices.Extension\SolarWindsAPM\solarwinds_apm.config.

5. Restart the Web App application.

Uninstall the .NET Library from Azure AppServices

To uninstall the .NET Library from the Azure AppServices:

1. From the Azure Web App, remove the .NET Library environment variables that were previously added. Navigate to the Application Settings in the configuration settings and remove the following environment variables:
   • .NET 8+
     • SW_APM_HOME_DOTNET
     • CORECLR_ENABLE_PROFILING
     • CORECLR_PROFILER
     • CORECLR_PROFILER_PATH_32
     • CORECLR_PROFILER_PATH_64
   • .NET Framework
     • SW_APM_HOME_DOTNET
     • COR_ENABLE_PROFILING
     • COR_PROFILER
     • COR_PROFILER_PATH_32
     • COR_PROFILER_PATH_64
     • COMPLUS_LoaderOptimization
2. Restart the Web App application.
3. In the Azure Web App, in the Development Tools section, click Extensions.
4. Select the SolarWindsAPM .NET Agent OpenTelemetry Azure App Services Site Extension, and click the Delete button.

Install the .NET Library using the SolarWindsAPM.OpenTelemetry.Agent NuGet package (Windows and Linux)

1. Ensure that Application Insights is disabled. This can be checked under the Settings > Application Insights section for the App Service.

2. Open the official SolarWindsAPM.OpenTelemetry.Agent NuGet package page to view details about the latest release of the library, and add the library using your preferred package installation method.

   To add the library to your package using the .NET command line, enter the following at the command line:

   SolarWindsAPM.OpenTelemetry.Agent package:

   dotnet add ProjectName.csproj package SolarWindsAPM.OpenTelemetry.Agent --version VersionNumber

3. Replace ProjectName with your project's file name and VersionNumber with the latest available version number found on the official SolarWindsAPM.OpenTelemetry.Agent NuGet package.

4. Publish the Web App to Azure. The following is an example of a publish command:

   dotnet publish ProjectName.csproj /p:PublishProfile='ProfileName'

   Where ProjectName is your project's file name and ProfileName is a unique name to represent the publish profile.

5. To configure the SolarWinds Observability .NET Library, navigate to the Application Settings in the configuration settings. Add the following application global environment variables:

   For Windows

   The paths below assume that the system drive for the App Service is C:\. To determine the drive of your App Service, either open the App Service Console window, or go to the Advanced tools and locate the Debug console to open CMD or PowerShell.

   .NET 8+

   Environment variable	Environment variable value
   SW_APM_SERVICE_KEY	For Azure App Services, the Service key is used to identify your account. It is shown in the Add Data dialog when you add the new service.  It is in the form of YourApiToken:YourServiceName. Replace YourApiToken with the SolarWinds Observability API token (ingestion type) generated for this service, and the YourServiceName will only be a placeholder if OpenTelemetry is enabled for the App Service. When OpenTelemetry is enabled, the service name will be set to the name of the Azure App Service. This configuration can also be set as the ServiceKey key in the solarwinds_apm.config file. To override the service name when OpenTelemetry is enabled, the OTEL_SERVICE_NAME environment variable can be used to set the service name.
   SW_APM_COLLECTOR	Set the APM collector endpoint corresponding to your tenant. To determine the correct value, see Data centers and endpoint URIs. This configuration can also be set as the ApmCollector key in the solarwinds_apm.config file.
   SW_APM_HOME_DOTNET	C:\home\site\wwwroot
   CORECLR_ENABLE_PROFILING	1
   CORECLR_PROFILER	{AAAA7777-11FE-4F94-8EDA-312C0EDF4141}
   SW_APM_OPEN_TELEMETRY	Enabled
   Target Runtime Not Selected:
   CORECLR_PROFILER_PATH_64	C:\home\site\wwwroot\x64\native\solarwinds_apm_profiler.dll
   CORECLR_PROFILER_PATH_32	C:\home\site\wwwroot\x86\native\solarwinds_apm_profiler.dll
   or Target Runtime Selected:
   CORECLR_PROFILER_PATH	C:\home\site\wwwroot\solarwinds_apm_profiler.dll

   .NET Framework

   Environment variable	Environment variable value
   SW_APM_SERVICE_KEY	For Azure App Services, the Service key is used to identify your account. It is shown in the Add Data dialog when you add the new service. It is in the form of YourApiToken:YourServiceName. Replace YourApiToken with the SolarWinds Observability API token (ingestion type) generated for this service, and the YourServiceName will only be a placeholder if OpenTelemetry is enabled for the App Service. When OpenTelemetry is enabled, the service name will be set to the name of the Azure App Service. This configuration can also be set as the ServiceKey key in the solarwinds_apm.config file. To override the service name when OpenTelemetry is enabled, the OTEL_SERVICE_NAME environment variable can be used to set the service name.
   SW_APM_COLLECTOR	Set the APM collector endpoint corresponding to your tenant. To determine the correct value, see Data centers and endpoint URIs. This configuration can also be set as the ApmCollector key in the solarwinds_apm.config file.
   SW_APM_HOME_DOTNET	C:\home\site\wwwroot
   COR_ENABLE_PROFILING	1
   COR_PROFILER	{AAAA7777-11FE-4F94-8EDA-312C0EDF4141}
   SW_APM_OPEN_TELEMETRY	Enabled
   COR_PROFILER_PATH_32	C:\home\site\wwwroot\SolarWindsAPM\x86\solarwinds_apm_profiler.dll
   COR_PROFILER_PATH_64	C:\home\site\wwwroot\SolarWindsAPM\x64\solarwinds_apm_profiler.dll
   COMPLUS_LoaderOptimization	1

   For both .NET 8+ and .NET Framework applications, the log files can be found in C:\home\LogFiles\SolarWinds.

   The solarwinds_apm.config file is located at: 

   • Windows .NET 8+: C:\home\site\wwwroot\solarwinds_apm.config

   • Windows .NET Framework: C:\home\site\wwwroot\solarwinds_apm.config

   For Linux and Alpine

   Environment variable	Environment variable value
   SW_APM_SERVICE_KEY	For Azure App Services, the Service key is used to identify your account. It is shown in the Add Data dialog when you add the new service.  It is in the form of YourApiToken:YourServiceName. Replace YourApiToken with the SolarWinds Observability API token (ingestion type) generated for this service, and the YourServiceName will only be a placeholder if OpenTelemetry is enabled for the App Service. When OpenTelemetry is enabled, the service name will be set to the name of the Azure App Service. This configuration can also be set as the ServiceKey key in the solarwinds_apm.config file. To override the service name when OpenTelemetry is enabled, the OTEL_SERVICE_NAME environment variable can be used to set the service name.
   SW_APM_HOME_DOTNET	/home/site/wwwroot/runtimes
   CORECLR_ENABLE_PROFILING	1
   CORECLR_PROFILER	{AAAA7777-11FE-4F94-8EDA-312C0EDF4141}
   Target Runtime Not Selected:
   Linux x64 CORECLR_PROFILER_PATH	/home/site/wwwroot/runtimes/linux-x64/native/solarwinds_apm_profiler.so
   Alpine x64 CORECLR_PROFILER_PATH	/home/site/wwwroot/runtimes/linux-musl-x64/native/solarwinds_apm_profiler.so
   Linux arm64 CORECLR_PROFILER_PATH	/home/site/wwwroot/runtimes/linux-arm64/native/solarwinds_apm_profiler.so
   Alpine arm64 CORECLR_PROFILER_PATH	/home/site/wwwroot/runtimes/linux-musl-arm64/native/solarwinds_apm_profiler.so
   Target Runtime Selected:
   CORECLR_PROFILER_PATH	/home/site/wwwroot/solarwinds_apm_profiler.so

   Log files are in /home/LogFiles/SolarWinds.

   The solarwinds_apm.config file is located at:

   • Linux: /home/site/wwwroot/solarwinds_apm.config

6. Restart the Web App application.

Disable the .NET Library

To disable the .NET Library:

1. In the Azure Web App, navigate to the Application Settings in the configuration settings.

2. Set the application global environment variables:

   • For .NET 8+, set CORECLR_ENABLE_PROFILING to 0.

   • For .NET Framework, set COR_ENABLE_PROFILING to 0.

3. Restart the Web App application.

Add Custom Instrumentation

See Manual Instrumentation for more information on how to add custom instrumentation.

The scripts are not supported under any SolarWinds support program or service. The scripts are provided AS IS without warranty of any kind. SolarWinds further disclaims all warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The risk arising out of the use or performance of the scripts and documentation stays with you. In no event shall SolarWinds or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the scripts or documentation.