Enterprise Reporter 3.2.2 - ToolBox User Guide

Overview

The ToolBox (formerly “ValidationTool”) is an internal tool designed to assist developers and QC in automating repetitive or error-prone tasks. The motivation for writing the ToolBox was a simple tool similar to ANT or MAVEN which has a simple, easy to learn syntax, that provided a standard model for writing tools during development and which had a minimal learning curve. I wanted a tool that could be used in a variety of situations without having to learn a grammar and syntax like PowerShell. It was imperative that the tool be useful both from a developer’s main development machine as well as the automated build process on TFS.

Installation is as simple as copying the files into a folder – there is currently no installer, though as the number of support assemblies grow, this is something we may consider.

Introduction

The ToolBox (formerly “ValidationTool”) is an internal tool designed to assist developers and QC in automating repetitive or error-prone tasks. The motivation for writing the ToolBox was a simple tool similar to ANT or MAVEN which has a simple, easy to learn syntax, that provided a standard model for writing tools during development and which had a minimal learning curve. I wanted a tool that could be used in a variety of situations without having to learn a grammar and syntax like PowerShell. It was imperative that the tool be useful both from a developer’s main development machine as well as the automated build process on TFS.

Installation is as simple as copying the files into a folder – there is currently no installer, though as the number of support assemblies grow, this is something we may consider.

Displaying Basic Information

The ToolBox consists of a command-line client EXE (ToolBox.exe), the core ToolBox functionality (ToolBox.Core.dll), several task assemblies (ToolBox.Tasks.*.dll) and supporting assemblies for the task assemblies. As the tool’s repertoire of tasks has expanded, there are now several supporting assemblies that are part of the package; this will increase as the tool is further expanded.

 

TOOLBOX v3.1.0.1736

 

TOOLBOX v1.1.1.115

 

TOOLBOX -DEPENDENCIES

Checks all task assemblies to ensure dependencies are available

 

TOOLBOX -DIR

Lists chain-files in the TOOLBOX_SCRIPTS folder

 

TOOLBOX -EXECUTE <CHAINFILE> [-VARS !(VAR1)=VALUE1 !(VAR2)=VALUE2 ...] [-DEBUG] [-REMOTE HOST:PORT] [-PUSH] [-ALTPATH PATH] [-MAXLOGS COUNT] [-LOG PATH]

Executes the specified chain-file

 

TOOLBOX -HELP [TASKNAME]

Displays usage information for ToolBox.exe or the specified task

 

TOOLBOX -LIST [ASSEMBLY1.DLL;...;ASSEMBLYN.DLL]

Displays the list of all tasks or those in the given assemblies

 

TOOLBOX -MAN [OPERATION]

Provides UNIX-style help for the specified operation

 

TOOLBOX -NEWCHAIN <CHAINFILE>

Creates a new chain file stub with the given name

 

TOOLBOX -REGISTER

Registers the tasks contained in any assemblies named, 'ToolBox.Tasks.*.dll'

 

TOOLBOX -REMOTE_MODE [PORT]

Starts up the ToolBox in remote mode, on the specified port

 

TOOLBOX -REMOTE_RECONNECT <HOST:PORT> [-MAXLOGS COUNT]

Connects to the specified remote ToolBox and listens for log messages

 

TOOLBOX -SEARCH <KEY>

Displays all tasks with a name or description containing <key>To retrieve a list of available tasks

TOOLBOX v1.1.1.115

 

 

[ACTIVEDIRECTORY]

ADContact - The task manages Active Directory Contact

BackupActiveDirectory - Backs up Active Directory data to a SQLite file

EnableActiveDirectoryAccount - Enable/Disable an Active Directory account

JoinDomain - Joins a computer to a domain

LeaveDomain - Removes a computer from a domain

PopulateAdCountryState - Populates ActiveDirectory with Country/State OUs

PopulateAdUsersGroupsComputers - Populates ActiveDirectory with Users groups and ciomputers

PopulateAdUsers - Populates ActiveDirectory with the specified number of users

RenameActiveDirectoryOUs - Renames Active Directory OUs to include numbers

RestoreActiveDirectory - Restores Active Directory Data from a SQLite file

 

[BUILD]

JavaScript - Runs JavaScript

MsBuild - Performs solution build using MSBuild

NuGet - Performs NuGet operations

PseudoLocalize - Performs resource pseudo localization

SetPkgVersion - Performs search through folders and changes the package versions

 

[COMPUTER]

RestartComputer - Restarts the specified computer

SetComputerServiceLogonRights - Sets computer service logon rights

SetServiceAccount - Sets the NT Service account and password

StartService - Starts NT Service

TakeScreenshot - Takes a screenshot of the entire screen or a specific window

 

[DATABASE]

AddUpgradeScriptsToInstaller - Adds upgrade scripts to installer

BackupDatabase - Backs up the specified database

CheckLogErrors - Check Log for Errors

CompareIndexNames - Compares the indices in database X with those in database Y

CompareRolePermissions - Compares the permissions for each table and function in database X with those in database Y

CompareRoutines - Compares the routines in database X with those in database Y

CompareTableContent - Compares the data in the specified tables in database X with the same tables in database Y

CompareTablesColumns - Compares the columns in the specified tables of database X with those in database Y

CompareTables - Compares the tables in database X with those in database Y

CompareViewsColumns - Compares the views columns in the specified views of database X with those in database Y

CompareViews - Compares the views in database X with those in database Y

CreateDatabase - Creates a new database using dbconfig.exe

CreateLocalDbInstance - Creates a new LocalDb Instance if it doesn't exist

DeleteLocalDbInstance - Deletes a LocalDb Instance

DropDatabase - Drops a database

DumpReporterLogsToDatabase - Dumps the contents of an ER log into the database

EnumerateIndices - Enumerates the indices in the given database

EnumerateRoutines - Enumerates the routines in the given database

EnumerateTables - Enumerates the tables in the given database

EnumerateViews - Enumerates the views in the given database

ExecuteFileQuery - Executes a SQL query from a sql file

ExecuteQuery - Executes a SQL query

ExportDataToCsv - Exports data from a database to a CSV file

ExportDataToSqlite - Exports data to a SQLite database

ExportDataToSqlServer - Exports data from a SQL Server database into another SQL Server database

ExportHttpToSqlServer - Save Graph properties to the database table

ExportJsonToSqlServer - Exports json data into SQL Server database

ExtractLastJobExecutionTime - Extracts Last Job Execution Time from SQLite database

FixDatabaseScript - Generates database creation script

GenerateReportsScript - Generates reports scripts

GenerateResetSecurityScript - Generates reset security script file

GenerateUpgradeScriptStub - Generates an upgrade script stub from version X to version Y

GetMissingTables - Discover missing tables

RestoreDatabase - Restores a backed-up database and gives it a new name

SQLDataCompareProjectResult - Compares two databases using RedGate DataCompare tool

SQLDataCompareProject - Compares two databases using RedGate DataCompare tool

SQLSchemaCompareProject - Compares two database schema using RedGate SQL Schema Compare tool

StartLocalDbInstance - Starts a LocalDb Instance

StopLocalDbInstance - Stops a LocalDb Instance

UpgradeDatabase - Upgrades an existing database

ValidateIndexNames - Examines the specified database to ensure index names match a specified template

ValidateReportIds - Checks report definitions for unique identifiers

ValidateRoles - Ensures the specified database has had appropriate roles applied to each table

 

[DATAVIZ]

DumpRunInfo - Dumps run data from the main database to a file

VisualiseJobRun - Generates sequence diagrams for tasks of a JobRun

 

[FILES]

AppendFiles - Concatenates all files together

CompareTextFiles - Compares two text files and outputs lines with different content

ConvertRTFtoText - Converts an RTF document to a plain text document

CopyFilesFromShare - Copies files from remote share source directory to the target

CopyFiles - Copies files from source directory to the target

CopyMatchingFiles - Copies files from source to target directory based on matching directory structure

CreateFolder - Creates a folder if doesn't exist

CreateZip - Creates compressed zip file

DeleteFiles - Copies files from source directory to the target

DeleteFolder - Deletes a folder

FileExists - Check if file exists

FileSize - Enumerates files under a root folder and calculates total size

JsonFileCompare - Compares two Json files for equality

ReplaceTextInFile - Replaces text in a file. It can be text search or regular expression

ReplaceVersionInFileName - Replaces version in a file name

ReplaceVersionInFile - Replaces version in a file

ReSignStrongName - Uses Enhanced Strong Names signing

ResourceUpdate - Updates resource in a binary

SevenZip - Runs 7zip tool

SignTool - Timestamps and digitally signs binaries

SignVerify - Vetrifies digitally signs binaries

UnZip - Unzips zip file

ValidateAssemblyVersions - Examines a set of assemblies and checks for matching file versions

ValidatecsvFormat - Validates that all given csv files are in the correct format and data types are correct

ValidateInstalledFilesDetails - Validates installed files are properly signed

ValidateInstalledFilesSigned - Validates installed files are properly signed

 

[IMAGES]

IconGenerator - Generates images of various sizes and colours from a folder of SVG files

 

[POWERSHELL]

ConfigurePowerShell - Configures PowerShell on a computer

CopyFilesFromRemote - Copies files from remote computer using Remote Powershell

CopyFilesToRemote - Copies files to a remote computer using Remote Powershell

ExecutePowerShellCommand - Executes an arbitrary PowerShell command

ExecutePowerShell - Executes an arbitrary PowerShell script

SetPowerShellUnrestricted - Set the Unrestricted PowerShell property

 

[PROCESSES]

Echo - Echos the input string

ExecuteProcess - Executes an arbitrary process

Sleep - Waits for a specified number of seconds

 

[SECURITY]

AslrCheck - Performs check for ASLR flag in binaries using Microsoft BinScope tool

HashCode - Generates the hashcode for a string value

 

[TFS]

TFSAdd - Adds a file to TFS

TFSChangesetAssemblies - Show modified assemblies within a range of TFS changesets

TFSCheckOut - Checks out a file from TFS

TFSQueueBuild - Enqueues a new build task in TFS

TFSSync - Syncs Local Directory Files with TFS Directory

 

[SERVER]

UpgradeServer32 - Upgrades server form <3.2 to 3.2

 

[VISUALSTUDIO]

FindDeadProjects - Locates unreferenced (dead) projects

LineCount - Performs a basic lines of code count

StaticAnalysis - Examines a set of projects to ensure static analysis tools are properly configured

VSExternalTools - Creates a folder if doesn't exist

VSInstallVsix - Installs a Visual Studio extension

 

[VMWARE]

VMDeleteSnapshot - Delete VMWare snapshots

VMPowerOff - Powers Off VMWare Computer

VMPowerOn - Powers On a VMWare computer

VMRevertSnapshot - Revert VMWare snapshots

VMRunInGuest - Runs program in guest

VMTakeSnapshot - Take VMWare snapshots

 

Found 120 tasks

Working With Tasks

This section provides some examples of how you can retrieve information about specific tasks.

 

TOOLBOX v1.1.1.115

 

[DATABASE]

CreateDatabase - Creates a new database using dbconfig.exe

CreateLocalDbInstance - Creates a new LocalDb Instance if it doesn't exist

 

[FILES]

CreateFolder - Creates a folder if doesn't exist

CreateZip - Creates compressed zip file

 

Found 4 tasks

 

TOOLBOX v1.1.1.115

 

TASK: CreateDatabase

--------------------

<?xml version="1.0" encoding="utf-8" ?>

<TaskChain [failonerror]>

<task name="CreateDatabase" [id] [enabled] [fatal] [runalways] [showalloutput]>

<args>

<arg name="Filepath">[REQ] The path to the database creation executable</arg>

<arg name="SqlHost">[REQ] The SQL Server host machine</arg>

<arg name="DatabaseName">[REQ] The name of the database to be created</arg>

<arg name="DatabaseWizardConfigFile">[REQ] The path to the database wizard configuration file</arg>

<arg name="SaveServerConfiguration">[OPT] Defines whether we want to save changes to the server configuration</arg>

</args>

</task>

</TaskChain>

 

TASKCHAIN OPTIONAL ATTRIBUTES:

failonerror="true|(false)" - If true, terminates the chain on any error

 

TASK OPTIONAL ATTRIBUTES:

id="friendly name" - A unique identifier for a task

 

TASK OPTIONAL ATTRIBUTES WITH VARIABLE SUPPORT:

enabled="(true)|false" - If true, this task will be skipped

fatal="(true)|false" - If true, any error in this task will terminate the run

runalways="true|(false)" - If true, this task will ALWAYS run even if earlier tasks failed

showalloutput="true|(false)" - If true, shows all output, otherwise just errors

 

TOOLBOX v1.1.1.115

 

[C:\Program Files\Quest\Enterprise Reporter\Server\ToolBox\Toolbox.Tasks.Build.dll]

[BUILD]

JavaScript - Runs JavaScript

MsBuild - Performs solution build using MSBuild

NuGet - Performs NuGet operations

PseudoLocalize - Performs resource pseudo localization

SetPkgVersion - Performs search through folders and changes the package versions

 

Found 5 tasks

 

It is possible to query more than one assembly at a time by separating the names of the assemblies. If the assemblies do not lie in the current path, the names must be fully qualified:

 

TOOLBOX v1.1.1.115

 

[C:\Program Files\Quest\Enterprise Reporter\Server\ToolBox\Toolbox.Tasks.Build.dll]

[BUILD]

JavaScript - Runs JavaScript

MsBuild - Performs solution build using MSBuild

NuGet - Performs NuGet operations

PseudoLocalize - Performs resource pseudo localization

SetPkgVersion - Performs search through folders and changes the package versions

 

[C:\Program Files\Quest\Enterprise Reporter\Server\ToolBox\Toolbox.Tasks.Computer.dll]

[COMPUTER]

RestartComputer - Restarts the specified computer

SetComputerServiceLogonRights - Sets computer service logon rights

SetServiceAccount - Sets the NT Service account and password

StartService - Starts NT Service

TakeScreenshot - Takes a screenshot of the entire screen or a specific window

 

Found 10 tasks

In order to make use of the tasks within an assembly, ToolBox must first know about the tasks within that assembly. If, for example, you have created a new assembly, or added tasks to an existing assembly, then you need to place that assembly into the same folder as TOOLBOX.EXE and then execute a “toolbox –register” operation. This will force ToolBox to enumerate all assemblies matching the file pattern, “ToolBox.Tasks.*.dll” and interrogate those assemblies for tasks. The result will be an output file containing a mapping named, “taskcatalogue.json” which acts as an index and lookup for the ToolBox when executing tasks.

 

TOOLBOX v1.1.1.115

 

ToolBox.Tasks.ActiveDirectory.dll (found 10 tasks)

ADContactTask

BackupActiveDirectoryTask

EnableActiveDirectoryAccountTask

JoinDomainTask

LeaveDomainTask

PopulateAdCountryStateTask

PopulateAdUsersGroupsComputersTask

PopulateAdUsersTask

RenameActiveDirectoryOUsTask

RestoreActiveDirectoryTask

 

ToolBox.Tasks.Build.dll (found 5 tasks)

JavaScriptTask

MsBuildTask

NuGetTask

PseudoLocalizeTask

SetPkgVersionTask

 

ToolBox.Tasks.Computer.dll (found 5 tasks)

RestartComputerTask

SetComputerServiceLogonRightsTask

SetServiceAccountTask

StartServiceTask

TakeScreenshotTask

 

ToolBox.Tasks.Database.dll (found 43 tasks)

AddUpgradeScriptsToInstallerTask

BackupDatabaseTask

CheckLogErrorsTask

CompareIndexNamesTask

CompareRolePermissionsTask

CompareRoutinesTask

CompareTableContentTask

CompareTablesColumnsTask

CompareTablesTask

CompareViewsColumnsTask

CompareViewsTask

CreateDatabaseTask

CreateLocalDbInstanceTask

DeleteLocalDbInstanceTask

DropDatabaseTask

DumpReporterLogsToDatabaseTask

EnumerateIndicesTask

EnumerateRoutinesTask

EnumerateTablesTask

EnumerateViewsTask

ExecuteFileQueryTask

ExecuteQueryTask

ExportDataToCsvTask

ExportDataToSqliteTask

ExportDataToSqlServerTask

ExportHttpToSqlServerTask

ExportJsonToSqlServerTask

ExtractLastJobExecutionTimeTask

FixDatabaseScriptTask

GenerateReportsScriptTask

GenerateResetSecurityScriptTask

GenerateUpgradeScriptStubTask

GetMissingTablesTask

RestoreDatabaseTask

SQLDataCompareProjectResultTask

SQLDataCompareProjectTask

SQLSchemaCompareProjectTask

StartLocalDbInstanceTask

StopLocalDbInstanceTask

UpgradeDatabaseTask

ValidateIndexNamesTask

ValidateReportIdsTask

ValidateRolesTask

 

ToolBox.Tasks.DataViz.dll (found 2 tasks)

DumpRunInfoTask

VisualiseJobRunTask

 

ToolBox.Tasks.EnterpriseReporter.dll (found 2 tasks)

SetSystemCredentialsTask

ValidateLicenceFilesTask

 

ToolBox.Tasks.Files.dll (found 26 tasks)

AppendFilesTask

CompareTextFilesTask

ConvertRTFtoTextTask

CopyFilesFromShareTask

CopyFilesTask

CopyMatchingFilesTask

CreateFolderTask

CreateZipTask

DeleteFilesTask

DeleteFolderTask

FileExistsTask

FileSizeTask

JsonFileCompareTask

ReplaceTextInFileTask

ReplaceVersionInFileNameTask

ReplaceVersionInFileTask

ReSignStrongNameTask

ResourceUpdateTask

SevenZipTask

SignToolTask

SignVerifyTask

UnZipTask

ValidateAssemblyVersionsTask

ValidatecsvFormatTask

ValidateInstalledFilesDetailsTask

ValidateInstalledFilesSignedTask

 

ToolBox.Tasks.Images.dll (found 1 task)

IconGeneratorTask

 

ToolBox.Tasks.PowerShell.dll (found 6 tasks)

ConfigurePowerShellTask

CopyFilesFromRemoteTask

CopyFilesToRemoteTask

ExecutePowerShellCommandTask

ExecutePowerShellTask

SetPowerShellUnrestrictedTask

 

ToolBox.Tasks.Processes.dll (found 3 tasks)

EchoTask

ExecuteProcessTask

SleepTask

 

ToolBox.Tasks.Security.dll (found 2 tasks)

AslrCheckTask

HashCodeTask

 

ToolBox.Tasks.TFS.dll (found 5 tasks)

TFSAddTask

TFSChangesetAssembliesTask

TFSCheckOutTask

TFSQueueBuildTask

TFSSyncTask

 

ToolBox.Tasks.Upgrade.Server.dll (found 1 task)

UpgradeServer32Task

 

ToolBox.Tasks.VisualStudio.dll (found 5 tasks)

FindDeadProjectsTask

LineCountTask

StaticAnalysisTask

VSExternalToolsTask

VSInstallVsixTask

 

ToolBox.Tasks.VMWare.dll (found 6 tasks)

VMDeleteSnapshotTask

VMPowerOffTask

VMPowerOnTask

VMRevertSnapshotTask

VMRunInGuestTask

VMTakeSnapshotTask

 

Added 15 assemblies containing 122 tasks.