Error Message Remapping¶

Overview¶

New in Vinyl 2.6, Vinyl allows developers to provide user-friendly common replacement messages for database exception errors. Providing friendly messages can help users unfamiliar with database technology understand what has happened when an error occurs. Replacing error messages such as Violation of PRIMARY KEY constraint 'PK_ProductInt' with something more understandable such as Record already exists can go a long way toward improving the user experience.

To remap an error message, several steps must first be performed to identify the exception:

• The database type is determined by matching the exception's properties:

• Type Name: This is the full exception class name

• Source: This is the assembly package for the DLL

• A database error message match is attempted using regular expressions for the exception message and data parameters.

  • First, the list of database specific exception messages is scanned in Index order
  • If no match is found, the list of general exception message entries is scanned in Index order

In the case where no match is found, the exception message will be left untouched.

Database Type Mapping¶

Database type mapping allows the developer to map exception classes to specific database types. This way, a smaller set of exception messages can be examined when attempting to remap an exception message.

By default, Vinyl ships with many of the typical database types already pre-filled. In the unlikely event that a new entry is required, a developer can perform the following steps to add a new database mapping:

• Navigate to the Vinyl IDE > Configuration > Error Messages:

  

• Click the Configure toolbar button in the Database Type panel:

  

• Click Create

• Pick your Database Type and fill in the following details:

• Type Name: The fully qualified name of the exception class (e.g. System.Data.SqlClient.SqlException)

• Source: Optional field to provide the DLL assembly name. This field is useful if a system exception type is being remapped for a specific assembly. For instance the Rest database type remaps the system type System.InvalidOperationException for the Vinyl.DataSource.Rest assembly only.

• Description: Optional field to provide a description for the entry

• Click the checkmark icon to Save the entry

Now exceptions error messages can be mapped to the configured database type.

Error Messages¶

To successfully remap an error message, an intelligent, user-friendly entry must be made in the Error Message table. Entries can be added to one of two lists:

1. An error message for a specific database type (e.g. Microsoft SQL Server)
2. An error message for any database type

When a database exception is encountered, the list of error messages for the mapped database type is examined first. If no match is found, the list of non-specific database type messages (error messages with a NULL database type) is examined. Each list is ordered by Index.

To enter a new Error Message:

• Navigate to Vinyl IDE > Configuration > Error Messages

• Click Create in the Errors panel and enter the details:

  

Error Message Parameters¶

The list of parameters for an Error Message is as follows:

Message¶

The replacement message to be displayed to the user. This message can include substitution parameters in the form of named regex capture groups (of the exception message Pattern) or exception data parameter names using the Vinyl {{name}} syntax.

Pattern¶

This is the regular expression pattern used to match the exception message. This pattern can specify named capture groups e.g. Capture group 'Key' inside quotation marks "(?<Key>.*)".

Example Pattern:

Outputs Row already exists for key 'PK_OrderDetails'.

Match starts at the beginning of string. Includes a capture group called Key which matches PK_OrderDetails inside the single quotes.

Example¶

This is an example exception message that will match the given Pattern. If an example is entered, the pattern regular expression will be validated.

Index¶

Index allows sorting of error messages. Note that Index is not a unique key. Multiple error messages can share the same Index as most matches cannot truly be ordered. By default the Index is set to 100 and in most cases, it makes sense to leave it as-is. However some matches can be obviously moved to the front or end of the processing list. For instance if the developer wants to create a catch-all pattern that matches any string (so that the exception message is always remapped even if all previous matches fail), they could use a very high Index value (e.g. 9999).

Exception Data¶

The Data dictionary of parameters for an exception can also be matched. This is useful when an exception contains a generic message but has specific exception details in the Data dictionary. There are three Data entries that can be added to an error message. You'll need to double click on the error message to see the full list of exception data parameters.

• Name: The name of the exception data parameter
• Regex: The regular expression to match against the exception data parameter value

Substitutions¶

As discussed previously, the user-friendly Message can include substitutions which resolve to either:

• A named capture group in the Pattern or
• An exception data parameter name

The syntax of substitutions is {{name}} and can be used anywhere within the Message.

Shipping User Messages¶

User database type mappings and error messages are packaged with LPs created on the Vinyl instance. When an LP is installed on another Vinyl instance, those user entries will be installed as well. This follows the same pattern as user-defined mvSQL functions. The new entries become active immediately upon install. Currently, there is no way to disable this functionality.