Install .NET Core SDK

Getting the .NET Core SDK

The .NET Core SDK can be added to your project using the AppOptics.Instrumentation NuGet package. In addition to the AppOptics.Instrumentation .NET Core assemblies, the nuget package also includes some dependent libraries and the agent.config file that contains configuration options.

  • Add the AppOptics.Instrumentation NuGet package to your .NET Core project.
  • The service key must be configured in the agent.config file. The agent.config file is included in the AppOptics.Instrumentation nuget package. Alternatively, the service key can be set using the environment variable APPOPTICS_SERVICE_KEY.
  • After adding the nuget package to your project you can add the AppOptics.Instrumentation ASP.NET Middleware (see below) or add SDK methods <../sdk> to your application to start traces, report spans and custom metrics or both.
  • All the files in the AppOptics.Instrumentation nuget package must be deployed with your application.
  • The nuget package for Windows platforms can also be downloaded from https://files.appoptics.com/dotnet/DotNetCoreSDK.zip
  • The nuget package for Linux platforms can also be downloaded from https://files.appoptics.com/dotnet/dotnet-core-package.tgz

Note

The .NET Core SDK package contains a native shared library oboe_<major>_<minor>_<patch>.dll for Windows platforms and oboe_<major>_<minor>_<patch>.so for Linux platforms. At runtime, the .NET Core SDK must be able to find and load the native shared library and its dependencies.

On Windows platforms, the .NET Core Runtime looks for this shared library under the <published-dotnet-core-app>/runtimes/win-x64/native/ or <published-dotnet-core-app>/runtimes/win-x86/native/ directory depending on if the application is 64 bit or 32 bit. If the location of this runtime directory is changed, then the PATH environment variable must be updated with the new location.

On Linux platforms, the .NET Core Runtime looks for this shared library under the <published-dotnet-core-app>/runtimes/linux-x64/native/ or <published-dotnet-core-app>/runtimes/linux-x86/native/ directory depending on if the application is 64 bit or 32 bit. If the location of this runtime directory is changed, then the LD_LIBRARY_PATH environment variable must be updated with the new location. See the troubleshooting page for more details.

Adding the AppOptics.Instrumentation ASP.NET Middleware

The .NET Core SDK provides an ASP.NET Core middleware which can be added to your ASP.NET Core application to automatically start traces and report metrics.

To use it, add the line app.UseAppopticsApm(); to the Startup.cs file in your ASP.NET Core project. See the Startup.cs example below:

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;

public class Startup
{
    public void Configure(IApplicationBuilder app)
    {
        app.UseAppopticsApm(); // Add the AppOptics.Instrumentation middleware
        app.UseMvcWithDefaultRoute();
    }
}

Note

The AppOptics middleware needs to intercept the request before it is processed by the first MVC middleware, so should be added before the first MVC middleware in Startup.cs. See ASP.NET Core middleware order for more information on how order is defined and its implications.

Troubleshooting

After installing the agent if traces and metric data do not appear in the AppOptics dashboard, please review the Troubleshooting page for tips on how to resolve.

Log File Locations

The AppOptics .NET Core SDK logs detailed information about problems it runs into, which can provide helpful information during troubleshooting.

  • Records of running instrumentation are in C:\Windows\TEMP\AppOptics\DotNetAgentLog*. On Linux platforms, the records can be found in /var/tmp/appoptics/DotNetAgentLog*.