Skip to main content

Install the .NET agent manually with NuGet

In some instances, you may prefer to manually install the .NET agent using NuGet. For example, this can be useful if you are unable to access the Azure App Service site extension or if you prefer to include the .NET agent as a dependency.

Before you begin

Single-file deployments are not supported when you install the .NET agent manually with NuGet.

Important

When redeploying a web application that has a Contrast agent running, you may run into an error that says "Files in use" on ContrastProfiler.dll. This happens because the agent DLL files are locked by .NET, and can't be overwritten while the application is still running.

Steps

<NOTE TO REVIEWERS: THERE ARE MANY DISCREPANCIES BETWEEN THE .NET CORE AND .NET FRAMEWORK TOPICS - NEED HELP FIGURING OUT WHAT APPLIES TO BOTH AND WHAT NEEDS TO BE CALLED OUT SEPARATELY>

  1. Add the Contrast NuGet package to your application.

    Using dotnet command line:

    dotnet add package Contrast.Agent

    Using Visual Studio:

    • Under the application project in the Solution Explorer, right-click on References and select Manage NuGet Packages.

    • Search for the Contrast.Agent package, select it and add it to your project.

    • Build your application. Confirm that a contrastsecurity folder appears in your project. When the application is published, this folder also appears in the build output directory.

  2. Set environment variables so that the .NET runtime loads the agent’s profiler component: <NOTE TO REVIEWERS - DO THESE APPLY TO .NET CORE ONLY? NOT SHOWN N .NET FRAMEWORK TOPIC>

    Windows:

    CORECLR_ENABLE_PROFILING: 1
CORECLR_PROFILER: {8B2CE134-0948-48CA-A4B2-80DDAD9F5791}
CORECLR_PROFILER_PATH_32: <application directory>\contrast\runtimes\win-x86\native\ContrastProfiler.dll
CORECLR_PROFILER_PATH_64: <application directory>\contrast\runtimes\win-x64\native\ContrastProfiler.dll

    Linux x64:

    CORECLR_ENABLE_PROFILING: 1
CORECLR_PROFILER: {8B2CE134-0948-48CA-A4B2-80DDAD9F5791}
CORECLR_PROFILER_PATH: <application directory>/contrast/runtimes/linux-x64/native/ContrastProfiler.so

    Linux ARM64:

    CORECLR_ENABLE_PROFILING: 1
CORECLR_PROFILER: {8B2CE134-0948-48CA-A4B2-80DDAD9F5791}
CORECLR_PROFILER_PATH: <application directory>/contrast/runtimes/linux-arm64/native/ContrastProfiler.so

  3. Set the basic configuration either with the YAML configuration file or with environment variables. For example:

    CONTRAST_CONFIG_PATH: [Path to yaml config file]

    At minimum, the following environment variables are required:

    CONTRAST__API__URL: [IF USING ANOTHER SERVER THAN THE DEFAULT: https://app.contrastsecurity.com]
CONTRAST__API__USER_NAME: [REPLACE WITH YOUR AGENT USERNAME]
CONTRAST__API__SERVICE_KEY: [REPLACE WITH YOUR AGENT SERVICE KEY]
CONTRAST__API__API_KEY: [REPLACE WITH YOUR AGENT API KEY]

  4. Deploy your application with the environment variables from the previous step.

  5. Once the application has loaded, use the application and then verify that the server and application are active in Contrast, and that any expected vulnerabilities appear.

In this section: