Skip to main content

Configure the .NET Framework agent

The standard configuration uses this order of precedence.

Configure the .NET Framework agent:


Use the Contrast agent configuration editor to create or upload a YAML configuration file, validate YAML and get setting recommendations.

.NET Framework agent-specific settings for Azure App Service

You can configure the .NET Framework agent for Azure App Service in the Azure Portal in three ways:

  • Use the environment variable convention of agent configuration. Add all settings to the Application Settings section of the Configuration blade in the Azure Portal using environment variable syntax.

  • Specify application configuration options in an application's web.config file. For the agent to pick up customized application settings, you must place these settings in the application web.config file's root configuration appSettings section. See application-specific settings for Windows for more details.

  • Instead of setting individual options in the Azure Portal, you may use a YAML configuration file containing Contrast settings. First, upload the file to your Azure web application by including it in your application deployment or using the Kudu console. Then add an application setting, CONTRAST_CONFIG_PATH, that points to this file.

    For example, To use the contrast_security.yaml file in the root of your application, add an application setting with key CONTRAST_CONFIG_PATH and value D:\Home\site\wwwroot\contrast_security.yaml. Application files in Azure App Service are deployed to D:\home\site\wwwroot.

Configure .NET Framework with web.config file

You can specify the configuration options in an application's web.config file or using YAML configuration. For the agent to pick up customized application settings with web.config, you must place these settings in the application web.config file's root configuration appSettings section.

For example, two applications hosted in the same application pool will report as different servers if you configure the property in the appSettings in each application's web.config file. Or, you could use web.config to configure the, like this:

     <add key="" value="MyWebAppName" />
     <add key="contrast.application.version" value="1.2.3" />

See the .NET Framework YAML template for a description of other available properties.

If your agent version is earlier than 21.1.4, only some properties can be configured with web.config as listed here.


Introduced with this .NET Framework agent version




















If is not specified, the .NET Framework agent will use the application's virtual path as an application name. If the application is hosted in the root of a site (meaning, the virtual path is /), the .NET Framework agent will use the site's name as the application name.


Starting with agent version 21.1.4, users can set most agent configuration settings either with the application's web.config file or with a contrast_security.yaml file in the same directory as the application. For example, two applications hosted in the same application pool can now report as different servers by setting in the appSettings in each application's web.config file.

The following configuration settings are applied at the process level and cannot be customized separately for each application. You cannot set these properties using web.config and must set these configurations another way (like with YAML).

  • agent.dotnet.app_pool_denylist

  • agent.dotnet.app_pool_allowlist

  • agent.dotnet.enable_instrumentation_optimizations

  • agent.dotnet.enable_jit_inlining

  • agent.dotnet.enable_transparency_checks

  • agent.dotnet.enable_struct_dataflow

  • assess.enable_control_detection

Additionally, the agent's profiler component uses the process-level settings for the following keys, while the agent's sensor component will use the application-specific settings (if specified):

  • agent.logger.level

  • agent.logger.stdout

.NET Framework YAML template

Configure the .NET Framework agent using a YAML configuration file.

The contrast_security.yaml file is copied to the agent's data directory by the installer (C:\ProgramData\Contrast\dotnet\contrast_security.yaml by default). The installer does not copy the YAML file if it already exists at the destination.

The template below contains all valid YAML options for this agent. For example, you can use the file to set the server name reported by the .NET Framework agent. To do this, update the contrast_security.yaml file, add a new line and the code below, and then continue the installation as normal.

  name: MyServerName

Certificate exceptions

If you see certificate exception messages and feel that it's safe to ignore them, add this setting to the YAML configuration file:

    ignore_cert_errors: true

icon-external-link.svgLearn more about managing certificate issues.