Usage
Reference Replacer

The Reference Replacer is a multi-purpose executable. The mode in which it starts is determined by the command line arguments passed to it. Running the executable without any arguments will launch the Config Editor UI where you can build and test your configuration files.

Installation

The Reference Replacer doesn't include an installer. Download and extract the .zip file on the overview page to where you want to run it from, for e.g. C:\RefReplacer. You must set the application configuration before attempting to process configuration directories.

Application Config

Before attempting to process directories, you must provide some base e-mail configuration to allow administrator alerts. Open the 'ReplaceRefs.exe.config' file in a text editor and provide values for:

  • EmailHost
  • EmailSender
  • AdminAlertRecipients

You can test the e-mail server from the Config Editor.

You can also change the default number of threads used to avoid having to pass this on the command line as well as the default config directory used.

Directory Structure

If you'll only be processing one configuration directory on one schedule, you can use the 'Config' directory provided to store your configuration files. You only need to use the '--process' argument to process this directory. Make sure the working directory is the same directory as ReplaceRefs.exe.

If you're wanting to process on multiple schedules, I recommend the directory structure below, creating folders relevant to your schedules, for example:

...\ReferenceReplacer
...\ReferenceReplacer\bin
...\ReferenceReplacer\Daily
...\ReferenceReplacer\Hourly
...\ReferenceReplacer\Weekly

The 'bin' directory will contain the contents of the zip file, the ReplaceRefs executable etc. You can then place your config files into the relevant schedule's config directory and create tasks on those schedules pointing to those directories. See scheduling below for more information on the command required.

Command Line Arguments

The available command line arguments are below. These should be appended to the executable command:

C:\Path\To\ReplaceRefs.exe --args
Parameter Description
Short Long
-h --help Shows the available command line parameters.
-p --process Launch in processing mode to process a directory containing configuration files.
-d PATH --directory PATH Used with '--process' to specify the directory containing configuration files. This allows multiple processes to run on different schedules in parallel. If not specified the application will look in the current directory for a 'Config' directory and use that.
--dry-run Used with '--process' to perform a dry run. This will run through the actions without making any changes or sending any e-mails. Actions are logged to the console and log file. Log file outputs can be disabled, see '--no-log'.
-f FILE --file FILE Used with '--dry-run' to perform a dry run against a single configuration file instead of the entire directory.
--hide-cmd Only works with the Config Editor. Because this is a console application, the UI is run from a cmd.exe process. If the cmd.exe process is terminated, so is the UI, without warning. You can use this argument in a shortcut to hide the cmd.exe window and prevent accidental closures. You shouldn't use this when launching from a dedicated cmd.exe window as it will be hidden and the process will remain running, consuming resources.
--no-log Used with '--dry-run' to prevent logging to the log file. Information, warning and error messages are still displayed in the console. This is used by the Config Editor's test run.
-t X --threads X Specifies the number of threads to spawn, default 1. When greater than 1, a thread is spawned for each .conf file in the config directory to allow parallel processing. If you only have 1 .conf file, you'll see no benefit from increasing this.

Scheduling

You can run as many instances of ReplaceRefs.exe as needed. A configuration directory can only be processed by one instance at a time. Lock files are created in the directory to prevent two instances attempting to process the same files at the same time which could result in errors.

To schedule a configuration directory to be processed, use the Windows Task Scheduler, pointing at ReplaceRefs.exe with the '--process' argument and if necessary the '--directory' argument:

C:\Path\To\ReplaceRefs.exe --process --directory "C:\Path\To\Config"

Lock Files

If the application terminates abnormally, a lock file may be left in the configuration directory preventing processing. If this happens, administrators will be e-mailed on the next run.

To remove the lock file, navigate to the configuration directory (the directory specified with --directory) and remove the file named .refreplacer.lock.

Log Files

If you don't specify a directory to process, the logs are stored in the application directory. When a directory is provided, log files are created in that directory to prevent multiple processes conflicting with each other. The user running the application must have permission to write to this location.

You can adjust the verbosity of the log file in the NLog.config file found in the application directory. Values are:

  • Error
  • Warn
  • Info
  • Debug
  • Trace

As you descend the levels, the log file detail will grow as will the file size. It is recommended to only use 'Info' and above for production systems. By default logs will not be rotated, this can also be turned on in the NLog configuration. See the NLog documentation for more information.