General Troubleshooting: Static .NET Agent on Windows

Run Viper as a Process instead of a Service

By default, the vFunction install.ps1 script will install and run vFunction Viper as a Windows Service. In some circumstances, Windows security settings prevent the Viper Service from being created and running as expected. In this scenario, run Viper as a standalone process. When run as a Service, Viper will automatically start when the Windows Server restarts. When run as a Process, Viper will need to be manually started when the Windows Server restarts.

To run Viper as a process:

  1. Run PowerShell as an Administrator
  2. Run the installation script including the runAsServices flag. For example:
powershell -NoProfile -ExecutionPolicy unrestricted -Command "C:\vfunction\controller-installation\install.ps1 -instance viperinst -runAsServices false"

Note that, when the installation script is run with -runAsServices false, a file named $BASE_DIR\vfunction\config\var\run\instances\$INSTANCE_NAME\run-as-process is created. This file is used in subsequent restart-controller.ps1 and upgrade.ps1 scripts to ensure that Viper continues to run as a process in the future.

Review Logs

The vFunction logs are, by default, written to the folder $BASE_DIR\vfunction\log\instances\$INSTANCE_NAME\. This folder includes:

  • archive directory for any older logging that has been rotated out. By default, logs are rotated after they reach 1gb in size. And, 30 log files are retained in this log directory
  • vfviper.err.log includes the redirected Standard Error output from the Viper process
  • vfviper.log includes Info-level logging for Viper
  • vfviper.out.log includes the redirected Standard Output output from the Viper process
  • vfviper.wrapper.log
  • vfviper-all.$DATE.log includes Debug-level logging for all of Viper’s log messages with basic details
  • vfviper-own.$DATE.log includes Trace-level logging from Viper’s own log messages with extra web details using some ASP.NET core renderers

Confirm there are no issues in the Viper Configuration Files

During the installation process, the Viper Configuration Files are created. Confirm there are no unexpected characters or unexpected formatting in the Configuration Files that are used to start the vFunction Viper process / service.

Replace $BASE_DIR with the vFunction Installation Location. Replace $INSTANCE_NAME with the name of the vFunction Instance.
  • Process Configuration File:
  • Service Configuration File: $BASE_DIR\vfunction\viper\instances\$INSTANCE_NAME\bin\vfviper.xml

Attempt to manually start Viper in the Command Line

Attempting to manually start Viper from the Command Line may generate Console output that is helpful in understanding the point of failure with starting or running Viper.

Run As Process

Take the following steps to try to manually start Viper as a Process:

  1. Open PowerShell as an Administrator
  2. Navigate to the directory where the Service launches from:
### Replace $BASE_DIR with the vFunction Installation Location
### Replace $INSTANCE_NAME with the name of the vFunction Instance
cd $BASE_DIR\\vfunction\\viper\\instances\\$INSTANCE_NAME\\bin
  1. Start the Viper process
### Replace $BASE_DIR with the vFunction Installation Location
### Replace $INSTANCE_NAME with the name of the vFunction Instance
Start-Process -PassThru -FilePath "$BASE_DIR\\vfunction\\viper\\instances\\$INSTANCE_NAME\\bin\\vfviper-$INSTANCE_NAME.exe" -RedirectStandardOutput "$BASE_DIR\\vfunction\\log\instances\$INSTANCE_NAME\vfviper.out.log" -RedirectStandardError "$BASE_DIR\\vfunction\\log\instances\$INSTANCE_NAME\vfviper.err.log"```

</div>

</div>

##### Run As Service

Take the following steps to try to manually start Viper as a Service:

<div style="padding-left: 20px">

1. Open PowerShell as an Administrator
2. Navigate to the directory where the Service launches from:

<div style="padding-left: 50px">

```powershell
### Replace $BASE_DIR with the vFunction Installation Location
### Replace $INSTANCE_NAME with the name of the vFunction Instance
cd $BASE_DIR\\vfunction\\viper\\instances\\$INSTANCE_NAME\\bin
  1. Install the Service
Invoke-Expression ".\vfviper.exe install --no-elevate"
  1. Start the Service
Invoke-Expression ".\vfviper.exe start --no-elevate"

Turn on Debug / Trace Logging

Debug Logging can be turned on by creating the subkey debug_mode: true under the key Viper in the installation.yaml. After creating the subkey, run the upgrade.ps1 script. Similarly, the subkey trace_mode: true can be used instead.

viper:
  debug_mode: true
  assemblies:
    - C:\app\bin
  stored_procedure:
    # optional db_provider: sqlserver, oracle
#    db_provider:
    # optional db_connection_string: Server=<IP>;Database=<DB name>;User ID=<ID>;Password=<Password>;Encrypt=False
#    db_connection_string:

Updated on 19 Feb 2025