Install - vFunction .NET Framework Distributed Agent running on a Windows Host as an IIS Site

Installation Steps if installing on all IIS Sites

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 the UI or via PowerShell. Both workflows are outlined below:
Setting User Environment Variables Manually in 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 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
COR_PROFILER_PATH C:\otel\win-xVERSION\OpenTelemetry.AutoInstrumentation.Native.dll as an example
OTEL_DOTNET_AUTO_INSTALL_DIR C:\otel as an example
DOTNET_ADDITIONAL_DEPS C:\otel\AdditionalDeps as an example
DOTNET_SHARED_STORE C:\otel\store as an example
DOTNET_STARTUP_HOOKS C:\otel\net\OpenTelemetry.AutoInstrumentation.StartupHook.dll as an example
OTEL_DOTNET_AUTO_HOME C:\otel as an example
OTEL_EXPORTER_OTLP_ENDPOINT https://vfunction.mycompany.com/api/unauth/otlp as an example
OTEL_EXPORTER_OTLP_HEADERS 93af7f38-0000-0000-0000-bd9516798497 as an example
COR_ENABLE_PROFILING 1
COR_PROFILER {918728DD-259F-4A6A-AC2B-B85E1B658318}
OTEL_EXPORTER_OTLP_PROTOCOL http/protobuf
OTEL_TRACES_EXPORTER otlp
OTEL_METRICS_EXPORTER none
OTEL_LOGS_EXPORTER none

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
# Find-and-Replace C:\otel with the location where the vFunction Installation ZIP was extracted

# Replace VERSION with 64 or 86 depending on the Windows version
[System.Environment]::SetEnvironmentVariable('COR_PROFILER_PATH', 'C:\otel\win-xVERSION\OpenTelemetry.AutoInstrumentation.Native.dll', [System.EnvironmentVariableTarget]::User)

[System.Environment]::SetEnvironmentVariable('COR_ENABLE_PROFILING', '1', [System.EnvironmentVariableTarget]::User)

[System.Environment]::SetEnvironmentVariable('COR_PROFILER', '{918728DD-259F-4A6A-AC2B-B85E1B658318}', [System.EnvironmentVariableTarget]::User)

[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)

# Replace https://vfunction.mycompany.com with the VF Server's URL
[System.Environment]::SetEnvironmentVariable('OTEL_EXPORTER_OTLP_ENDPOINT', 'https://vfunction.mycompany.com/api/unauth/otlp', [System.EnvironmentVariableTarget]::User)

# Replace the UUID with the value retrieved from the VF Server UI
[System.Environment]::SetEnvironmentVariable('OTEL_EXPORTER_OTLP_HEADERS', '93af7f38-0000-0000-0000-bd9516798497', [System.EnvironmentVariableTarget]::User)

[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)

# Optional if the Service talks to a Microsoft SQL DB
[System.Environment]::SetEnvironmentVariable('OTEL_DOTNET_AUTO_SQLCLIENT_SET_DBSTATEMENT_FOR_TEXT', 'true', [System.EnvironmentVariableTarget]::User)

# Optional if the Service talks to an Oracle DB
[System.Environment]::SetEnvironmentVariable('OTEL_DOTNET_AUTO_ORACLEMDA_SET_DBSTATEMENT_FOR_TEXT', 'true', [System.EnvironmentVariableTarget]::User)
  1. In PowerShell, restart the Application Pool for the IIS Site to be profiled
# Replace $instance with the name of the IIS Site's Application Pool
Restart-WebAppPool -Name "$instance"
  1. Confirm that the .NET Application runs as expected
  2. Start Learning in the vFunction Server UI and confirm tracing information is captured as expected

Installation Steps if installing on specific IIS Sites

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 Environment Variables for the Application Pool that runs the Application. Note that this can be done manually via the applicationHost.config or via PowerShell. Both workflows are outlined below:
Setting Environment Variables for the Application Pool via the applicationHost.config

Take the following steps to add the vFunction Hooks to the Application Pool via the applicationHost.config:

  1. On the machine running the Application, find the Application Pool running the relevant IIS Site
  2. In a text editor, open C:\Windows\System32\inetsrv\config\applicationHost.config
  3. Search for the term “applicationPools”. Below this, find the relevant Application Pool and add the environmentVariables:
# Find-and-Replace C:\otel with the location where the vFunction Installation ZIP was extracted

    <add name="$instance" autoStart="true">
        <environmentVariables>
            # Replace VERSION with either 64 or 86
            <add name="COR_PROFILER_PATH" value="C:\otel\win-xVERSION\OpenTelemetry.AutoInstrumentation.Native.dll" />
            <add name="OTEL_DOTNET_AUTO_INSTALL_DIR" value="C:\otel" />
            <add name="DOTNET_ADDITIONAL_DEPS" value="C:\otel\AdditionalDeps" />
            <add name="DOTNET_SHARED_STORE" value="C:\otel\store" />
            <add name="DOTNET_STARTUP_HOOKS" value="C:\otel\net\OpenTelemetry.AutoInstrumentation.StartupHook.dll" />
            <add name="OTEL_DOTNET_AUTO_HOME " value="C:\otel" />
            # Replace https://vfunction.mycompany.com with the VF Server's URL
            <add name="OTEL_EXPORTER_OTLP_ENDPOINT" value="https://vfunction.mycompany.com/api/unauth/otlp" />
            # Replace the UUID with the value retrieved from the VF Server UI
            <add name="OTEL_EXPORTER_OTLP_HEADERS" value="93af7f38-0000-0000-0000-bd9516798497" />
            <add name="COR_ENABLE_PROFILING" value="1" />
            <add name="COR_PROFILER" value="{918728DD-259F-4A6A-AC2B-B85E1B658318}" />
            <add name="OTEL_EXPORTER_OTLP_PROTOCOL" value="http/protobuf" />
            <add name="OTEL_TRACES_EXPORTER" value="otlp" />
            <add name="OTEL_METRICS_EXPORTER" value="none" />
            <add name="OTEL_LOGS_EXPORTER" value="none" />
            # Optional if using Microsoft SQL as a DB
            <add name="OTEL_DOTNET_AUTO_SQLCLIENT_SET_DBSTATEMENT_FOR_TEXT" value="true" />
            # Optional if using Oracle as a DB
            <add name="OTEL_DOTNET_AUTO_ORACLEMDA_SET_DBSTATEMENT_FOR_TEXT" value="true" />
    	</environmentVariables>
    </add>
  1. Save and close the file
Setting Environment Variables for the Application Pool via PowerShell

Take the following steps to add the vFunction Hooks to the Application Pool via the applicationHost.config:

  1. On the machine running the Application, find the Application Pool running the relevant IIS Site
  2. Open PowerShell , modify and run the commands below
# Find-and-replace all instances of C:\otel with the actual location where the Zip was unzipped
# Find-and-replace all instances of $instance with the Application Pool name

# Replace VERSION with either 64 or 86
Add-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST'  -filter "system.applicationHost/applicationPools/add[@name='$instance']/environmentVariables" -name "." -value @{name='COR_PROFILER_PATH';value='C:\otel\win-xVERSION\OpenTelemetry.AutoInstrumentation.Native.dll'}

Add-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST'  -filter "system.applicationHost/applicationPools/add[@name='$instance']/environmentVariables" -name "." -value @{name='OTEL_DOTNET_AUTO_INSTALL_DIR';value='C:\otel'}

Add-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST'  -filter "system.applicationHost/applicationPools/add[@name='$instance']/environmentVariables" -name "." -value @{name='DOTNET_ADDITIONAL_DEPS';value='C:\otel\AdditionalDeps'}

Add-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST'  -filter "system.applicationHost/applicationPools/add[@name='$instance']/environmentVariables" -name "." -value @{name='DOTNET_SHARED_STORE';value='C:\otel\store'}

Add-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST'  -filter "system.applicationHost/applicationPools/add[@name='$instance']/environmentVariables" -name "." -value @{name='DOTNET_STARTUP_HOOKS';value='C:\otel\net\OpenTelemetry.AutoInstrumentation.StartupHook.dll'}

Add-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST'  -filter "system.applicationHost/applicationPools/add[@name='$instance']/environmentVariables" -name "." -value @{name='OTEL_DOTNET_AUTO_HOME';value='C:\otel'}

# Replace https://vfunction.mycompany.com with the VF Server's URL
Add-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST'  -filter "system.applicationHost/applicationPools/add[@name='$instance']/environmentVariables" -name "." -value @{name='OTEL_EXPORTER_OTLP_ENDPOINT';value='https://vfunction.mycompany.com/api/unauth/otlp'}

# Replace the UUID with the value retrieved from the VF Server UI
Add-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST'  -filter "system.applicationHost/applicationPools/add[@name='$instance']/environmentVariables" -name "." -value @{name='OTEL_EXPORTER_OTLP_HEADERS';value='93af7f38-0000-0000-0000-bd9516798497'}

Add-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST'  -filter "system.applicationHost/applicationPools/add[@name='$instance']/environmentVariables" -name "." -value @{name='COR_ENABLE_PROFILING';value='1'}

Add-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST'  -filter "system.applicationHost/applicationPools/add[@name='$instance']/environmentVariables" -name "." -value @{name='COR_PROFILER';value='{918728DD-259F-4A6A-AC2B-B85E1B658318}'}

Add-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST'  -filter "system.applicationHost/applicationPools/add[@name='$instance']/environmentVariables" -name "." -value @{name='OTEL_EXPORTER_OTLP_PROTOCOL';value='http/protobuf'}

Add-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST'  -filter "system.applicationHost/applicationPools/add[@name='$instance']/environmentVariables" -name "." -value @{name='OTEL_TRACES_EXPORTER';value='otlp'}

Add-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST'  -filter "system.applicationHost/applicationPools/add[@name='$instance']/environmentVariables" -name "." -value @{name='OTEL_METRICS_EXPORTER';value='none'}

Add-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST'  -filter "system.applicationHost/applicationPools/add[@name='$instance']/environmentVariables" -name "." -value @{name='OTEL_LOGS_EXPORTER';value='none'}

# Optional if using Microsoft SQL as a DB
Add-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST'  -filter "system.applicationHost/applicationPools/add[@name='$instance']/environmentVariables" -name "." -value @{name='OTEL_DOTNET_AUTO_SQLCLIENT_SET_DBSTATEMENT_FOR_TEXT';value='true'}

# Optional if using Oracle as a DB
Add-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST'  -filter "system.applicationHost/applicationPools/add[@name='$instance']/environmentVariables" -name "." -value @{name='Optional for Oracle: OTEL_DOTNET_AUTO_ORACLEMDA_SET_DBSTATEMENT_FOR_TEXT';value='true'}
  1. In PowerShell, restart the Application Pool for the IIS Site to be profiled
# Replace $instance with the name of the IIS Site's Application Pool
Restart-WebAppPool -Name "$instance"
  1. Confirm that the .NET Application runs as expected
  2. Start Learning in the vFunction Server UI and confirm tracing information is captured as expected

Updated on 13 Jan 2026