Install - vFunction Monolithic and Distributed .NET Framework Agents running on a Windows x86 Host

Overview

Microsoft .NET Applications have a limitation that only one Agent can be hooked into the Application at a time. To work around this limitation, the Datadog Multiplexer can be used as the Base Agent. This Datadog Multiplexer includes a configuration file that allows you to define additional .NET Agents to run simultaneously on the Application without conflict.

At a high level, you’ll need to:

  1. Download and install the vFunction Monolithic .NET Agent
  2. Download and install the vFunction Distributed .NET Agent
  3. Install the Datadog .NET Multiplexer and add the vFunction Monolithic and Distributed .NET Agents as Profilers
  4. Restart the Application

.NET Core Compatibility

vFunction supports C# .NET Core version 3.x and .NET 6.x, 7.x and 8.x applications. Please see the full vFunction Compatibility Matrix.

Installation Steps

At a high level, you’ll need to:

vFunction Monolithic Agent Installation

The steps below ensure that the vFunction Monolithic Agent’s configuration files are set for your environment. These steps alone do not hook the vFunction Monolithic Agent into the Application.

  1. Ensure vFunction Monolithic Agent Prerequisites are met
  2. Download the vFunction Windows Controller Installation ZIP for the vFunction Monolithic Agent
  3. RDP to the Windows Server as the user who runs the Application
  4. Move the vFunction Windows Controller Installation ZIP to the location on the Windows Server where the vFunction Agent should run
  5. Unzip the vFunction Installation Package to, for example, C:\vfunction
  6. Add the configuration settings for the vFunction Monolithic Agent either as Option A: Manually Created User Environment Variables, as Option B: an installation.yaml or Option C: PowerShell Created User Environment Variables
Option A: Manually Created User Environment Variables

Take the following steps to add configuration settings via User Environment Variables:

  1. Log into the vFunction Server’s UI in a browser
  2. In the top-left corner, click the dropdown and select the relevant Application
  3. In the top-center menu bar, click the “Learning” tab
  4. On the left-side, click the “Select Controllers” link
  5. On the left-side, click the “Install Controller” link
  6. In the dialog box, find the YAML-formatted text box that contains the following details. You’ll need these details at a later stage below:
controller:
  name: {display name for this controller}
  host: $your_VF_Server_address
  org_id: 93af7f38-0000-0000-0000-bd9516798497
  app_id: 9fb228fc-0000-0000-0000-db8e83427e14
  client_id: caeadcd1-0000-0000-0000-9c9b37a9e119
  client_secret: 68cb85eb-0000-0000-0000-fb9e7f1d9240
  1. On the machine where the Application runs, open the Windows Start Menu and search for, “environment variables”
  2. Select the search results to edit the environment variables
  3. On the “System Properties” dialog box, make sure the “Advanced” tab is selected
  4. Select the “Environment Variables” button at the bottom of this page
  5. In the Environment Variables dialog box, find the top section for “User variables”
  6. Click the “New…” button and create the following Variables and Values

Note that the Variable Names below are accurate but the Values are not. Use the values for your environment retrieved from Step #6 above

Variable
Value
VF_CONTROLLER_DEFAULT_DOTNET_CONTROLLER_NAME Create your own display name for this controller such as QA-Windows-1
VF_CONTROLLER_DEFAULT_DOTNET_CONTROLLER_HOST $your_VF_Server_address such as https://demo.vfunction.com
VF_CONTROLLER_DEFAULT_DOTNET_CONTROLLER_ORG_ID 93af7f38-0000-0000-0000-bd9516798497 as an example
VF_CONTROLLER_DEFAULT_DOTNET_CONTROLLER_APP_ID 9fb228fc-0000-0000-0000-db8e83427e14 as an example
VF_CONTROLLER_DEFAULT_DOTNET_CONTROLLER_CLIENT_ID caeadcd1-0000-0000-0000-9c9b37a9e119 as an example
VF_CONTROLLER_DEFAULT_DOTNET_CONTROLLER_CLIENT_SECRET 68cb85eb-0000-0000-0000-fb9e7f1d9240 as an example
VF_CONTROLLER_DEFAULT_DOTNET_CONTROLLER_INSTANCE_ID Create your own display name for this controller such as QA-Windows-1
VF_CONTROLLER_DEFAULT_DOTNET_AGENT_ENABLE_REJIT true
Option B: An Installation.yaml

Take the following steps to add configuration settings via an installation.yaml:

  1. Log into the vFunction Server’s UI in a browser
  2. In the top-left corner, click the dropdown and select the relevant Application
  3. In the top-center menu bar, click the “Learning” tab
  4. On the left-side, click the “Select Controllers” link
  5. On the left-side, click the “Install Controller” link
  6. In the dialog box, find the YAML-formatted text box that contains the following details. You’ll need these details at a later stage below:
controller:
  name: {display name for this controller}
  host: $your_VF_Server_address
  org_id: 93af7f38-0000-0000-0000-bd9516798497
  app_id: 9fb228fc-0000-0000-0000-db8e83427e14
  client_id: caeadcd1-0000-0000-0000-9c9b37a9e119
  client_secret: 68cb85eb-0000-0000-0000-fb9e7f1d9240
  1. On the machine where the Application runs, open the installation.yaml at the location relevant to where you unpacked the vFunction Controller Installation ZIP, such as C:\vfunction\config\installation\instances\default-dotnet\installation.yaml
################### AFTER COPYING FROM STEP #6 ABOVE ###################
controller:
  name: Create your own display name for this controller such as QA-Windows-1
  instance_id: Add this field with the same name you used in the key above
  host: $your_VF_Server_address such as https://demo.vfunction.com
  org_id: 93af7f38-0000-0000-0000-bd9516798497 as an example
  app_id: 9fb228fc-0000-0000-0000-db8e83427e14 as an example
  client_id: caeadcd1-0000-0000-0000-9c9b37a9e119 as an example
  client_secret: 68cb85eb-0000-0000-0000-fb9e7f1d9240 as an example
  type: dotnet
  instrconf_additions:
    inclusions:
#      - a.b.c.
    exclusions:
#      - a.b.c.
  tags:
#    - tag1

server_application:
#  name:
#  include_classes: com.
#  allowed_users:
#  new_user_default_password:

agent:
  # optional versions: framework, dotnet
  ################### Change this value to be dotnet ################### 
  version: dotnet
  # optional environments: iis, service, command
  environment: iis
#  application_name:
#  architecture: x86
#  application_command:
### Set the log level for the agent (trace, debug, info, warning, error, critical). The default is debug.
#  log_level: info
### Add process ID to log file name (true/false). Default is false ###
#  add_pid_to_log_file: false
################### The comment needs to be removed from this enable_rejit field ################### 
  enable_rejit: true
Option C: PowerShell Created User Environment Variables

Take the following steps to add configuration settings via PowerShell:

  1. Log into the vFunction Server’s UI in a browser
  2. In the top-left corner, click the dropdown and select the relevant Application
  3. In the top-center menu bar, click the “Learning” tab
  4. On the left-side, click the “Select Controllers” link
  5. On the left-side, click the “Install Controller” link
  6. In the dialog box, find the YAML-formatted text box that contains the following details. You’ll need these details at a later stage below:
controller:
  name: {display name for this controller}
  host: $your_VF_Server_address
  org_id: 93af7f38-0000-0000-0000-bd9516798497
  app_id: 9fb228fc-0000-0000-0000-db8e83427e14
  client_id: caeadcd1-0000-0000-0000-9c9b37a9e119
  client_secret: 68cb85eb-0000-0000-0000-fb9e7f1d9240
  1. On the machine where the Application runs, open PowerShell
# The Keys below have Values that are going to be environmentally-specific
# Review and modify this list
[System.Environment]::SetEnvironmentVariable('VF_CONTROLLER_DEFAULT_DOTNET_CONTROLLER_NAME', 'Create your own display name for this controller such as QA-Windows-1', 'Machine')

[System.Environment]::SetEnvironmentVariable('VF_CONTROLLER_DEFAULT_DOTNET_CONTROLLER_HOST', 'https://vfunction.mycompany.com', 'Machine')

[System.Environment]::SetEnvironmentVariable('VF_CONTROLLER_DEFAULT_DOTNET_CONTROLLER_ORG_ID', '93af7f38-0000-0000-0000-bd9516798497', 'Machine')

[System.Environment]::SetEnvironmentVariable('VF_CONTROLLER_DEFAULT_DOTNET_CONTROLLER_APP_ID', '9fb228fc-0000-0000-0000-db8e83427e14', 'Machine')

[System.Environment]::SetEnvironmentVariable('VF_CONTROLLER_DEFAULT_DOTNET_CONTROLLER_CLIENT_ID', 'caeadcd1-0000-0000-0000-9c9b37a9e119', 'Machine')

[System.Environment]::SetEnvironmentVariable('VF_CONTROLLER_DEFAULT_DOTNET_CONTROLLER_CLIENT_SECRET', '68cb85eb-0000-0000-0000-fb9e7f1d9240', 'Machine')

[System.Environment]::SetEnvironmentVariable('VF_CONTROLLER_DEFAULT_DOTNET_CONTROLLER_INSTANCE_ID', 'Create your own display name for this controller such as QA-Windows-1', 'Machine')

[System.Environment]::SetEnvironmentVariable('VF_CONTROLLER_DEFAULT_DOTNET_AGENT_ENABLE_REJIT', 'true', 'Machine')
  1. After following Option A, Option B or Option C to add the configuration settings for the vFunction Dynamic Agent, launch PowerShell as an Administrator and run the vFunction Monolithic Agent installation script
### Replace $BASE_DIR with the Windows location where the vFunction Installation ZIP was unzipped
dir -Path "$BASE_DIR" -Recurse | Unblock-File

powershell -NoProfile -ExecutionPolicy unrestricted -Command "$BASE_DIR\controller-installation\install.ps1 -instance default-dotnet"
  1. Add User Environment Variables for the vFunction Monolithic Agent either manually using the UI or via PowerShell
Manually using the UI
  1. On the machine where the Application runs, open the Windows Start Menu and search for, “environment variables”
  2. Select the search results to edit the environment variables
  3. On the “System Properties” dialog box, make sure the “Advanced” tab is selected
  4. Select the “Environment Variables” button at the bottom of this page
  5. In the Environment Variables dialog box, find the top section for “System variables”
  6. Click the “New…” button and create the following Variables and Values. Note that the $BASE_DIR needs to be replaced with the actual installation location
Variable
Value
VF_AGENT_CONF_LOCATION $BASE_DIR\config\agent\instances\default-dotnet\conf.json
COMPlus_TailCallOpt 0
Using PowerShell
  1. On the Windows machine where the Application runs, open PowerShell
# Modify the $BASE_DIR based on the location of the VF Agent installation, such as C:\vfunction
[System.Environment]::SetEnvironmentVariable('VF_AGENT_CONF_LOCATION', '$BASE_DIR\config\agent\instances\default-dotnet\conf.json', [System.EnvironmentVariableTarget]::Machine)

[System.Environment]::SetEnvironmentVariable('COMPlus_TailCallOpt', '0', [System.EnvironmentVariableTarget]::Machine)
  1. The vFunction Monolithic Agent is installed (all configuration files are set) but is not hooked into the Application. Use the steps below to install the vFunction Distributed Agent.
Install the vFunction Distributed Agent

Take the following steps to install the vFunction Distributed Agent and configure it to send traces to the vFunction Server:

  1. Gather the vFunction Server UI’s UUID for the vFunction Distributed Application
  1. Log into the vFunction Server UI
  2. In the top-left corner, click the dropdown
  3. Click Add Application from the dropdown menu
  4. Type a name for the Application in the Application Name text field
  5. Toggle the slider to Distributed
  6. Click the blue Create button
  7. In the dialog box that launches, toggle the tabs to .NET
  8. In the text box with OTEL Environment Variables, find the OTEL_EXPORT_OTLP_ENDPOINT and OTEL_EXPORTER_OTLP_HEADER. These will be used at a later stage of the installation
  1. Download the OpenTelemetry .NET AutoInstrumentation ZIP. Note that, as an alternative, PowerShell Modules can be downloaded to accomplish this same goal
  2. Extract the downloaded opentelemetry-dotnet-instrumentation-windows.zip to a location on the Application’s filesystem, such as C:\otel.
  3. Create User Environment Variables for the User that runs the Application. Note that this can be done manually in Windows or via PowerShell. Both workflows are outlined below:
Setting User Environment Variables Manually in Windows
  1. On the machine where the Application runs, open the Windows Start Menu and search for, “environment variables”
  2. Select the search results to edit the environment variables
  3. On the System Properties dialog box, make sure the Advanced tab is selected
  4. Select the Environment Variables button at the bottom of this page
  5. In the Environment Variables dialog box, find the top section for User variables
  6. Click the New… button and create the following Variables and Values

Note that the Variable Names below are accurate but the Values are not. Use the values relevant to where the OpenTelemetry Instrumentation ZIP was extracted, such as C:\otel

Variable
Value
OTEL_DOTNET_AUTO_INSTALL_DIR C:\otel
DOTNET_ADDITIONAL_DEPS C:\otel\AdditionalDeps
DOTNET_SHARED_STORE C:\otel\store
DOTNET_STARTUP_HOOKS C:\otel\net\OpenTelemetry.AutoInstrumentation.StartupHook.dll
OTEL_DOTNET_AUTO_HOME C:\otel
OTEL_EXPORTER_OTLP_PROTOCOL http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINT https://vfunction.mycompany.com/api/unauth/otlp as an example
OTEL_TRACES_EXPORTER otlp
OTEL_METRICS_EXPORTER none
OTEL_LOGS_EXPORTER none
OTEL_EXPORTER_OTLP_HEADERS 93af7f38-0000-0000-0000-bd9516798497 as an example

Some additional flags can be added if the Services talks to a SQL Server or an Oracle Database. These are optional Environment Variables.

Variable
Value
Optional for Microsoft SQL Server: OTEL_DOTNET_AUTO_SQLCLIENT_SET_DBSTATEMENT_FOR_TEXT true
Optional for Oracle: OTEL_DOTNET_AUTO_ORACLEMDA_SET_DBSTATEMENT_FOR_TEXT true
Setting User Environment Variables via PowerShell
  1. On the machine where the Application runs, open PowerShell and run the following commands. Note the comments to modify the Values for some of the Keys
# The Keys below have Values that are going to be environmentally-specific 
# Such as C:\otel and vfunction.mycompany.com and the App's VF UUID
# Review and modify this list
[System.Environment]::SetEnvironmentVariable('OTEL_DOTNET_AUTO_INSTALL_DIR', 'C:\otel', [System.EnvironmentVariableTarget]::User)

[System.Environment]::SetEnvironmentVariable('DOTNET_ADDITIONAL_DEPS', 'C:\otel\AdditionalDeps', [System.EnvironmentVariableTarget]::User)

[System.Environment]::SetEnvironmentVariable('DOTNET_SHARED_STORE', 'C:\otel\store', [System.EnvironmentVariableTarget]::User)

[System.Environment]::SetEnvironmentVariable('DOTNET_STARTUP_HOOKS', 'C:\otel\net\OpenTelemetry.AutoInstrumentation.StartupHook.dll', [System.EnvironmentVariableTarget]::User)

[System.Environment]::SetEnvironmentVariable('OTEL_DOTNET_AUTO_HOME', 'C:\otel', [System.EnvironmentVariableTarget]::User)

[System.Environment]::SetEnvironmentVariable('OTEL_EXPORTER_OTLP_ENDPOINT', 'https://vfunction.mycompany.com/api/unauth/otlp as an example', [System.EnvironmentVariableTarget]::User)

[System.Environment]::SetEnvironmentVariable('OTEL_EXPORTER_OTLP_HEADERS', '93af7f38-0000-0000-0000-bd9516798497 as an example', [System.EnvironmentVariableTarget]::User)

# The Keys below have Values that do not need to be modified
[System.Environment]::SetEnvironmentVariable('OTEL_EXPORTER_OTLP_PROTOCOL', 'http/protobuf', [System.EnvironmentVariableTarget]::User)

[System.Environment]::SetEnvironmentVariable('OTEL_TRACES_EXPORTER', 'otlp', [System.EnvironmentVariableTarget]::User)

[System.Environment]::SetEnvironmentVariable('OTEL_METRICS_EXPORTER', 'none', [System.EnvironmentVariableTarget]::User)

[System.Environment]::SetEnvironmentVariable('OTEL_LOGS_EXPORTER', 'none', [System.EnvironmentVariableTarget]::User)
Install the DataDog Multiplexer

Take the following steps to install the DataDog Multiplexer:

  1. RDP to the Windows Server where the Application runs
  2. Create a directory for the DataDog Multiplexer, such as C:\multiplexer
  3. Download the DataDog Multiplexer Agent to this directory
  4. Download the DataDog Multiplexer Configuration File to the same directory
  5. Modify the DataDog Multiplexer’s loader.conf Configuration File. Note that the folder paths may need to be adjusted for your environment:
################# AFTER CHANGES #################
#Profiler
#PROFILER;{918728DD-259F-4A6A-AC2B-B85E1B658318};win-x64;C:\otel\win-x64\OpenTelemetry.AutoInstrumentation.Native.dll
PROFILER;{918728DD-259F-4A6A-AC2B-B85E1B658318};win-x86;C:\otel\win-x86\OpenTelemetry.AutoInstrumentation.Native.dll
#PROFILER;{918728DD-259F-4A6A-AC2B-B85E1B658318};linux-x64;/home/user/.otel-dotnet-auto/linux-x64/OpenTelemetry.AutoInstrumentation.Native.so
#PROFILER;{918728DD-259F-4A6A-AC2B-B85E1B658318};linux-musl-x64;/home/user/.otel-dotnet-auto/linux-musl-x64/OpenTelemetry.AutoInstrumentation.Native.so
#PROFILER;{918728DD-259F-4A6A-AC2B-B85E1B658318};linux-arm64;/home/user/.otel-dotnet-auto/linux-arm64/OpenTelemetry.AutoInstrumentation.Native.so
#PROFILER;{918728DD-259F-4A6A-AC2B-B85E1B658318};linux-musl-arm64;/home/user/.otel-dotnet-auto/linux-musl-arm64/OpenTelemetry.AutoInstrumentation.Native.so

#Tracer
#TRACER;{cd7d4b53-96c8-4552-9c11-6e41df8eab8a};win-x64;C:\vfunction\agent\vfagent.net.dll
#TRACER;{cd7d4b53-96c8-4552-9c11-6e41df8eab8a};win-arm64;C:\vfunction\agent\vfagent.net.arm64.dll
TRACER;{cd7d4b53-96c8-4552-9c11-6e41df8eab8a};win-x86;C:\vfunction\agent\vfagent.net.x86.dll
#TRACER;{cd7d4b53-96c8-4552-9c11-6e41df8eab8a};linux-x64;/home/user/vfunction/opt/vfunction/agent/libvfagent.net.so
#TRACER;{cd7d4b53-96c8-4552-9c11-6e41df8eab8a};linux-musl-x64;/home/user/vfunction/opt/vfunction/agent/libvfagent.net.musl.so
#TRACER;{cd7d4b53-96c8-4552-9c11-6e41df8eab8a};linux-arm64;/home/user/vfunction/opt/vfunction/agent/libvfagent.net.arm64.so
#TRACER;{cd7d4b53-96c8-4552-9c11-6e41df8eab8a};linux-musl-arm64;/home/user/vfunction/opt/vfunction/agent/libvfagent.net.musl-arm64.so
#TRACER;{cd7d4b53-96c8-4552-9c11-6e41df8eab8a};osx-x64;/home/user/vfunction/opt/vfunction/agent/libvfagent.net.dylib
#TRACER;{cd7d4b53-96c8-4552-9c11-6e41df8eab8a};osx-arm64;/home/user/vfunction/opt/vfunction/agent/libvfagent.net.dylib

#Custom
Add Hooks to the Application for the DataDog Multiplexer

Use Option A: Manually Created User Environment Variables or Option B: PowerShell Created User Environment Variables to hook the DataDog Multiplexer into the running Application and to then feed trace information to both the vFunction Runtime Agent and Dynatrace OneAgent.

Option A: Manually Created User Environment Variables
  1. On the machine where the Application runs, open the Windows Start Menu and search for, “environment variables”
  2. Select the search results to edit the environment variables
  3. On the “System Properties” dialog box, make sure the “Advanced” tab is selected
  4. Select the “Environment Variables” button at the bottom of this page
  5. In the Environment Variables dialog box, find the top section for “User variables”
  6. Click the “New…” button and create the following Variables and Values
Key
Value
COR_ENABLE_PROFILING 1
COR_PROFILER {846F5F1C-F9AE-4B07-969E-05C26BC060D8}
COR_PROFILER_PATH C:\multiplexer\Datadog.Trace.ClrProfiler.Native.dll
Option B: PowerShell Created User Environment Variables
  1. On the Windows machine where the Application runs, open PowerShell
[System.Environment]::SetEnvironmentVariable('COR_ENABLE_PROFILING', '1', [System.EnvironmentVariableTarget]::User)

[System.Environment]::SetEnvironmentVariable('COR_PROFILER', '{846F5F1C-F9AE-4B07-969E-05C26BC060D8}', [System.EnvironmentVariableTarget]::User)

[System.Environment]::SetEnvironmentVariable('COR_PROFILER_PATH', 'C:\multiplexer\Datadog.Trace.ClrProfiler.Native.dll', [System.EnvironmentVariableTarget]::User)

Confirm Functionality

  1. Restart the .NET Application
  2. Confirm the Application functions as expected
  3. Confirm that the vFunction Monolithic Agent is capturing data as expected by starting Learning and validating learning results
  4. Confirm that the vFunction Distributed Agent is capturing data as expected

Updated on 26 Feb 2026