❗️

This adaptor is currently in beta. Please contact us at [email protected].

Our Observability Adapter for .NET applications allows you to monitor your live API traffic from .NET, without configuring API calls manually in the APImetrics platform. By deploying this adapter, APImetrics can read API calls that are coming from .NET, and automatically build your API Inventory. Once integrated, you can compare your live API traffic against your OAS spec, and set up synthetic endpoint monitoring automatically.

We have two different versions of our .NET adaptor, one for versions of .NET 6 onwards and one for versions of .NET 4.7.2.

.NET 6 Onwards

Include the Adaptor in Your .Net Application Source

Download the .NET 6 adaptor, Darkspark.Dotnet.Core.Plug.1.0.0.nupkg, and unzip the package into your project directory.

To integrate with APImetrics, you will need to create a new API Key by following the tutorial here and choosing Ingress as your Access Level.

Set the Configuration Values

Configuration values can be set in standard .NET configuration locations. See Microsoft documentation for full documentation and precedence order.

Required:

• API_KEY - The APImetrics API Key for this application.

Optional:

• NODE_LOCATION - The location of the node executable on the system.
  • Default set to "node".
• SCRIPT_LOCATION - As part of the build process, the relevant script file is placed in a APImetrics folder relative to the bin files. If you wish to locate the script file elsewhere, it can be specified here.
  • Default set to ./Darkspark/darkspark_core.js.

Example configuration for appsettings.json:

{
  "Darkspark": {
    "API_KEY": "key-abcdef",
    "NODE_LOCATION": "c:\\temp\\node.exe",
    "SCRIPT_LOCATION": "./ExternalScripts/ds.js"
  }
}

Example configuration for the environment variables:

🚧

Note: The required Darkspark__ prefix

export Darkspark__API_KEY=key-abc
export Darkspark__NODE_LOCATION=mySpecialNode
export Darkspark__SCRIPT_LOCATION=../scripts/here.js

Enable Request Buffering

To allow the APImetrics .NET 6 adaptor to work, it is necessary to enable request buffering so that the body can be read more than once. This is done by adding the following to the configure method of the startup.cs (or equivalent). Note in this context, the app is an IApplicationBuilder.

app.Use(async (context, next) =>
{
    context.Request.EnableBuffering();
    await next();
});

Decorate the Controllers/Methods to Enable Observations

To enable observation, it is simply a case of adding the [Darkspark] attribute at either the controller level or at an individual method.

Optional: Set the Logging Level

Logging can be set on the Darkspark namespace if a level other than the application default is required. For example, to enable DEBUG level logging, use the following:

"Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Darkspark": "Debug"
    }
}

.NET 4.7.2

📘

Note: This plug only builds on Windows.

This adaptor runs on .NET Framework 4.7.2. Special CI pipelines dotnet4-check and dotnet4-publish test and build this component on GitHub Actions Windows runners. The project can also be built correctly in Visual Studio 16 or 17.

The .NET adaptor uses nodejs. A download link for nodejs can be found here.

Using the Adaptor in a .NET Framework Project

A valid APImetrics API key is required to start observing in a .NET Framework project, a tutorial for creating an API Key can be found here and choose Ingress as your Access Level.

Download the .NET 4.7.2 adaptor, Darkspark.Dotnet.Plug.1.0.0.nupkg. Once the NuGet package is installed in the project, to enable APImetrics, a few additional lines are required in the WebApiConfig.cs file.

• A call to Darkspark.Dotnet.Plug.Helpers.SetupHelper.Register takes the API key and an optional Logging.LogLevel (defaults to Information).
• A call to config.MessageHandles.Add registers the Darkspark observer to look at any calls made on any ApiController in the application.

Here's an example using an API key "key-valid" and setting the logging level to Debug:

// Darkspark setup
Darkspark.Dotnet.Plug.Helpers.SetupHelper.Register("key-valid", Microsoft.Extensions.Logging.LogLevel.Debug);
config.MessageHandlers.Add(new Darkspark.Dotnet.Plug.Delegates.ObserveDelegate());