How to troubleshoot vFunction Agent not loading on .NET Applications running in a Windows environment
Overview of the Issue
This article is meant to help when the vFunction Agent is not loading in a .NET Application running in a Windows environment. The most common points of failure are:
- A permissions issue where the .NET Application is run by a user that cannot access the location where the vFunction Agent files are stored
- An issue with the Environment Variables added into the .NET Application, such as a typo or a mismatch between the Framework / Core Environment Variables used and the type of .NET Application
- An issue with the Folder Path to the vFunction Agent where Windows treats the single-backslash as an escape character
- A .NET Agent issue where another Agent is hooked into the .NET Application instead of vFunction and this third-party Agent needs to be disabled in order for the vFunction Agent to be added
Check %TEMP% Location for Logging
The vFunction Agent attempts to create a new file named vfagent.net.log to capture Standard Output and Standard Error in the instance-specific vFunction logging directory. For example, this may be in C:\home\vfunction\log\instances\default-dotnet\vfagent.net.log.
If an issue arises that prevents the Application from writing to this directory, the vFunction Agent will write the log file to the %TEMP% directory. Open Windows Explorer and input the string %TEMP% into the Search Bar to navigate to this location and search for this file. Note that this workflow is accessible the Environment Variable %TEMP% for the user that runs the Application. This may be a separate user from the one initiating the RDP Session.
The %TEMP%\vfagent.net.log may contain errors about accessing the vFunction Agent DLL that need to be corrected. Or, the log may show that the installation.yaml’s agent.application_name field needs to be adjusted to hook into the relevant .NET Process.
Add both the Framework and Core Environment Variables
In the same location where the original vFunction Environment Variables were added, e.g. the applicationHost.config or Registry, modify the Environment Variables list to add both the Framework and Core Environment Variables. Also confirm the values (such as the Profiler UUID and the BASE_DIR path) are accurate:
VF_AGENT_CONF_LOCATION='$BASE_DIR\vfunction\config\agent\instances\default-dotnet\conf.json'
COR_PROFILER_PATH_64 = '$BASE_DIR\vfunction\agent\vfagent.net.dll'
CORECLR_PROFILER_PATH_64 = '$BASE_DIR\vfunction\agent\vfagent.net.dll'
COR_PROFILER_PATH_32 = '$BASE_DIR\vfunction\agent\vfagent.net.x86.dll'
CORECLR_PROFILER_PATH_32 = '$BASE_DIR\vfunction\agent\vfagent.net.x86.dll'
COR_ENABLE_PROFILING = '1'
CORECLR_ENABLE_PROFILING = '1'
COR_PROFILER = '{cd7d4b53-96c8-4552-9c11-6e41df8eab8a}'
CORECLR_PROFILER = '{cd7d4b53-96c8-4552-9c11-6e41df8eab8a}'
COMPlus_TailCallOpt = 0
DOTNET_TailCallOpt = 0
Use Double-Backslashes for the Agent’s Folder Path in the Environment Variables
In some cases, Windows may treat the single backslash as an escape character in the File Path of the .NET Application’s Environment Variables. Try using double-backslashes for the Folder Path. For example, for a Framework .NET App:
VF_AGENT_CONF_LOCATION='$BASE_DIR\\vfunction\\config\\agent\\instances\\default-dotnet\conf.json'
COR_PROFILER_PATH_64 = '$BASE_DIR\\vfunction\\agent\\vfagent.net.dll'
COR_PROFILER_PATH_32 = '$BASE_DIR\\vfunction\\agent\\vfagent.net.x86.dll'
COR_ENABLE_PROFILING = '1'
COR_PROFILER = '{cd7d4b53-96c8-4552-9c11-6e41df8eab8a}'
COMPlus_TailCallOpt = 0
Gather Errors About Loading the vFunction Agent
Take the following steps to run DebugView to get better insight into what is happening with the Application:
- On the Windows machine where the Application is running, download DebugView and unpack this Microsoft tool
- Right-click on dbgview64.exe and select Run as Administrator
- Select Capture from the Menu Bar
- Check the dropdown options to Capture Win32, Capture Global Win32, Pass-Through, and Capture Events
- Restart the Application. For example if an IIS Application, recycle the Application Pool, use an API and ensure there’s a new w3wp.exe Process ID.
- The Windows Error code may provide next steps about the source of the issue in order to resolve the problem, such as the wrong path to the vFunction Agent DLL or permissions issues or that another Agent is hooked into the Application which will need to be disabled.