Skip to main content

Creating Exceptions

There are many different types of exceptions that both checks and resolutions can throw. Each one affects the execution of the GetSetUp CLI in different ways.

CheckFailureException​

Throw this exception from within a check to indicate that it was not successful and that the user should be prompted to run any available resolutions.

If there are no available resolutions, then the check will be marked as failed in the results summary at the end of the process and when the CLI exits it will use a non-zero exit code.

If there are resolutions available, the user runs one, and that resolution is successful, then the check will be marked as successful in the results summary and the CLI can still exit with a zero exit code.

If there are resolutions available, the user runs one, but that resolution is not successful, then the check will be marked as failed in the results summary and when the CLI exits it will use a non-zero exit code.

Example usages of this could be:

  • A check that verifies a specific file exists, but it does not.
  • A check that verifies the user has at least Node.JS version 18 installed, but they have version 16.
  • A check that verifies the user has Docker running on their machine, however it's installed but not running.

CheckAbortException​

Throw this exception from within a check to indicate that it was not successful and that no attempt should be made to resolve it from the GetSetUp CLI.

It can also be thrown from resolutions to indicate that they were not successful and that no further resolutions should be attempted.

In either case the check will be marked as failed in the results summary and the CLI will exit with a non-zero exit code. Other checks, including checks from the same plugin, will still be run.

Example usages of this could be:

  • A check that verifies a specific file exists, but access to the file is denied.
  • A check that verifies the user has access to a specific domain but it's returning 5xx error codes.
  • A check that requires the GetSetUp config file to contain a string in a specific format but it's malformed.

CheckProcessAbortException​

Throw this exception from resolutions to indicate that the entire GetSetUp CLI process needs to be terminated because it needs to be restarted. The related check will be marked as failed in the results summary and the CLI will exit immediately with a non-zero exit code.

Generally this exception should only be thrown because a resolution has installed a piece of software that requires some form of restart to take effect.

The CheckProcessAbortException requires an AbortReason enum value to be passed to it's constructor. This enum contains the following values:

  • RestartProcess
  • RestartShell
  • RestartComputer

The RestartProcess value indicates that the process should be restarted, i.e, it's adequate for the user to re-run the GetSetUp CLI right away.

The RestartShell value indicates that the shell should be restarted, i.e, the user should close and re-open their PowerShell/Bash/ZSH/CMD window before re-running the GetSetUp CLI.

The RestartComputer value indicates that the computer should be restarted, i.e, the user should restart their computer before re-running the GetSetUp CLI.

tip

Where possible, try to limit your uses of this exception to the RestartProcess value in order to minimise the disruption to the user.

PluginAbortException​

Throw this exception from within the checks and resolutions of a plugin to indicate that the plugin itself is in an unrecoverable state and that the GetSetUp CLI should move on to the next plugin.

The currently running check will be marked as failed in the results summary and when the CLI exits it will use a non-zero exit code.

Usages of this exception should be minimal because checks should generally be independent of each other, however it can be used in cases where:

  • A check expects some state kept in a singleton service to contain a specific value, but it contains a different value.

RestartCheckException​

Throw this exception from within a resolution to indicate that the check that the resolution is related to should be re-run. This is functionally equivalent to the resolution returning the ResolutionSuccessAction.RetryCheck enum value; you can pick between the two approaches for whichever makes the most sense syntactically within your resolution.

tip

A check can only be restarted twice, for a total of three attempts. After that, the resolution will be marked as failed in the results summary and when the CLI exits it will use a non-zero exit code.