.NET Tests

CI Visibility is not available in the selected site () at this time.

Compatibility

Supported .NET versions:

  • .NET Framework 4.6.1 and above
  • .NET Core 2.1, 3.1, .NET 5, and .NET 6

Supported test frameworks:

  • xUnit 2.2 and above
  • NUnit 3.0 and above
  • MsTestV2 14 and above

Prerequisites

Install the Datadog Agent to collect tests data.

Agentless mode is in beta. To test this feature, follow the instructions on this page.

Installing the .NET tracer CLI

Install or update the dd-trace command using one of the following ways:

Instrumenting tests

To instrument your test suite, prefix your test command with dd-trace ci run, providing the name of the service or library under test as the --dd-service parameter, and the environment where tests are being run (for example, local when running tests on a developer workstation, or ci when running them on a CI provider) as the --dd-env parameter. For example:

By using dotnet test

dd-trace ci run --dd-service=my-dotnet-app --dd-env=ci -- dotnet test

By using VSTest.Console.exe

dd-trace ci run --dd-service=my-dotnet-app --dd-env=ci -- VSTest.Console.exe {test_assembly}.dll

All tests are automatically instrumented.

Configuration settings

You can change the default configuration of the CLI by using command line arguments or environment variables. For a full list of configuration settings, run:

dd-trace ci run --help

The following list shows the default values for key configuration settings:

--dd-service
Name of the service or library under test.
Environment variable: DD_SERVICE
Default: The repository name
Example: my-dotnet-app
--dd-env
Name of the environment where tests are being run.
Environment variable: DD_ENV
Default: none
Examples: local, ci
--agent-url
Datadog Agent URL for trace collection in the form http://hostname:port.
Environment variable: DD_TRACE_AGENT_URL
Default: http://localhost:8126

All other Datadog Tracer configuration options can also be used.

Collecting Git metadata

Datadog uses Git information for visualizing your test results and grouping them by repository, branch, and commit. Git metadata is automatically collected by the test instrumentation from CI provider environment variables and the local .git folder in the project path, if available.

If you are running tests in non-supported CI providers or with no .git folder, you can set the Git information manually using environment variables. These environment variables take precedence over any auto-detected information. Set the following environment variables to provide Git information:

DD_GIT_REPOSITORY_URL
URL of the repository where the code is stored. Both HTTP and SSH URLs are supported.
Example: git@github.com:MyCompany/MyApp.git, https://github.com/MyCompany/MyApp.git
DD_GIT_BRANCH
Git branch being tested. Leave empty if providing tag information instead.
Example: develop
DD_GIT_TAG
Git tag being tested (if applicable). Leave empty if providing branch information instead.
Example: 1.0.1
DD_GIT_COMMIT_SHA
Full commit hash.
Example: a18ebf361cc831f5535e58ec4fae04ffd98d8152
DD_GIT_COMMIT_MESSAGE
Commit message.
Example: Set release number
DD_GIT_COMMIT_AUTHOR_NAME
Commit author name.
Example: John Smith
DD_GIT_COMMIT_AUTHOR_EMAIL
Commit author email.
Example: john@example.com
DD_GIT_COMMIT_AUTHOR_DATE
Commit author date in ISO 8601 format.
Example: 2021-03-12T16:00:28Z
DD_GIT_COMMIT_COMMITTER_NAME
Commit committer name.
Example: Jane Smith
DD_GIT_COMMIT_COMMITTER_EMAIL
Commit committer email.
Example: jane@example.com
DD_GIT_COMMIT_COMMITTER_DATE
Commit committer date in ISO 8601 format.
Example: 2021-03-12T16:00:28Z

Custom instrumentation

Note: Your custom instrumentation setup depends on the dd-trace version. To use the custom instrumentation, you must keep the package versions for dd-trace and Datadog.Trace NuGet packages in sync.

To use the custom instrumentation in your .NET application:

  1. Execute dd-trace --version to get the version of the tool.
  2. Add the Datadog.Trace NuGet package with the same version to your application.
  3. In your application code, access the global tracer through the Datadog.Trace.Tracer.Instance property to create new spans.

For more information about how to add spans and tags for custom instrumentation, see the .NET Custom Instrumentation documentation.

Agentless (Beta)

To instrument your test suite without requiring an Agent, configure the following environment variables:

DD_CIVISIBILITY_AGENTLESS_ENABLED (Required)
Enables or disables Agentless mode.
Default: false
DD_API_KEY (Required)
The Datadog API key used to upload the test results.
Default: (empty)

Then, prefix your test command with dd-trace ci run. Use the --dd-service parameter to provide the name of the service or library. Use the --dd-env parameter to provide the environment where tests are being run (local when running tests on a developer workstation, ci when running them on a CI provider, etc.) For example:

dd-trace ci run --dd-service=my-dotnet-app --dd-env=ci -- dotnet test

Alternatively, you can provide the Datadog API key using the --api-key parameter, for example:

dd-trace ci run --api-key <API KEY> --dd-service=my-dotnet-app --dd-env=ci -- dotnet test

When the --api-key is set, Agentless mode is automatically enabled.

Additionally, configure which Datadog site to which you want to send data. Your Datadog site is: .

DD_SITE (Required)
The Datadog site to upload results to.
Default: datadoghq.com
Selected site:

Further reading