xg run

xg run

Execute a Dataverse plugin out-of-process via XrmGhost.FrameworkHost.

Synopsis

xg run -a <ASSEMBLY_PATH> -t <PLUGIN_TYPE> [options]

Description

xg run is the primary execution command in the XrmGhost CLI. It loads the plugin assembly you specify, starts XrmGhost.FrameworkHost.exe as a background process, and dispatches the plugin execution over a local gRPC channel. The host process is terminated automatically when the run completes.

The command has two required arguments — the assembly path and the fully-qualified plugin type name — and a rich set of optional flags that control scenario injection, verbosity, debugging, configuration strings, and data-source routing.

Scenario files are JSON documents generated by xg generate-scenario and let you define the execution context (message name, entity, stage, depth), input parameters, pre/post entity images, mock OrganizationService responses, and expected outcomes. Without a scenario file the host constructs a minimal default context.

Verbosity flags (-n, -v, -d) are mutually exclusive in practice: use the lowest level that gives you the information you need. The default (no verbosity flag) shows only plugin traces, which keeps the output clean in CI.

Data-source routing (--data-source) controls how RetrieveMultiple calls are handled inside the simulated IOrganizationService. auto (the default) lets the host decide based on the scenario content.

Options

Flag	Type	Default	Description
-a, --assembly-path	string	(required)	Path to the plugin assembly DLL. The file must exist at the time the command is invoked.
-t, --plugin-type	string	(required)	Fully-qualified name of the plugin type to execute (e.g., MyPlugins.MyPluginClass).
-s, --scenario	string	—	Path to a JSON scenario file. When provided, the file is deserialised into a ScenarioDefinition that supplies the execution context, input parameters, entity images, mock data, and expected outcomes.
-f, --framework-host-path	string	—	Explicit path to XrmGhost.FrameworkHost.exe. When omitted, the CLI resolves the host from its managed application-data install root, then falls back to legacy beside-the-CLI locations (bin/, then the CLI directory).
-w, --debug-plugin-wait	bool	false	Instructs FrameworkHost to pause before executing the plugin and wait for a debugger to attach. The CLI prints the host process ID and step-by-step attach instructions.
-c, --continue-on-unlicensed	bool	false	When a Pro-tier feature is encountered without a valid license, execution continues with a mocked result and a warning instead of terminating with a non-zero exit code.
-n, --normal	bool	false	Show plugin traces plus critical framework messages (errors and warnings). Expands the default output without the noise of full verbose mode.
-v, --verbose	bool	false	Show plugin traces and all framework traces, ordered chronologically.
-d, --debug	bool	false	Show all traces including timing analysis and performance metrics. Most detailed output level.
--debug-mode	bool	false	Enable detailed debug output for CLI-level operations (version info, scenario loading steps, license state, entitlement emission, entity extraction diagnostics). Distinct from -d/--debug, which controls plugin trace verbosity.
--unsecure-config	string	—	Unsecure configuration string passed to the plugin as IPluginExecutionContext.UnsecureConfig.
--secure-config	string	—	Secure configuration string passed to the plugin as IPluginExecutionContext.SecureConfig.
--data-source	string	auto	Controls how RetrieveMultiple calls are routed inside the simulated IOrganizationService. Accepted values: mock (use scenario mock data only), live (route to a real Dataverse environment), auto (host decides based on scenario content).

Exit Codes

Code	Meaning
0	Plugin executed successfully.
1	Plugin execution failed, scenario file not found, assembly not found, FrameworkHost failed to start or become healthy, or an unexpected error occurred.

Examples

Basic run

Execute a plugin against its assembly with no scenario file. The host creates a minimal default execution context.

xg run \
  -a ./bin/Debug/MyPlugins.dll \
  -t MyPlugins.AccountPreCreate

Run with a scenario file

Load a scenario that defines the execution context, input parameters, and mock data.

xg run \
  -a ./bin/Debug/MyPlugins.dll \
  -t MyPlugins.AccountPreCreate \
  -s ./scenarios/account-create.json

Advanced run — debug attach, secure config, and explicit data source

Generate a scenario first, then execute with debugger attach support, a secure configuration string, and mock-only data sourcing.

# Generate the scenario template (run once)
xg generate-scenario \
  -a ./bin/Debug/MyPlugins.dll \
  -t MyPlugins.AccountPreCreate \
  -o ./scenarios/account-create.json

# Run with advanced flags
xg run \
  -a ./bin/Debug/MyPlugins.dll \
  -t MyPlugins.AccountPreCreate \
  -s ./scenarios/account-create.json \
  -w \
  --secure-config "api-key=secret123" \
  --data-source mock \
  -d

After the command prints the FrameworkHost PID and attach instructions, attach your debugger to XrmGhost.FrameworkHost.exe, set breakpoints in your plugin code, and then resume execution.

Run with verbose output and unlicensed-Pro continuation

xg run \
  -a ./bin/Debug/MyPlugins.dll \
  -t MyPlugins.ComplexPlugin \
  -s ./scenarios/complex.json \
  -v \
  -c

With -c, any Pro-tier feature encountered (such as Final Entity States) returns a mocked result and prints a warning rather than terminating with exit code 1.

See Also

• xg generate-scenario — Generate a scenario JSON template for a plugin assembly and type
• xg doctor — Diagnose CLI configuration, FrameworkHost connectivity, and license validity
• CLI Overview — Introduction to the XrmGhost CLI and how this documentation is organised