Defines a base class to defive various application exceptions. More...

Inheritance diagram for PipServices3.Commons.Errors.ApplicationException:

Public Member Functions
	ApplicationException ()
	Creates a new instance of application exception. More...

	ApplicationException (string category=null, string correlationId=null, string code=null, string message=null)
	Creates a new instance of application exception and assigns its values. More...

override void	GetObjectData (SerializationInfo info, StreamingContext context)

ApplicationException	WithCode (string code)
	Sets a unique error code. More...

ApplicationException	WithCorrelationId (string correlationId)
	Sets a correlation id which can be used to trace this error through a call chain. More...

ApplicationException	WithCause (Exception cause)
	Sets a original error wrapped by this exception. More...

ApplicationException	WithStatus (int status)
	Sets a HTTP status code which shall be returned by REST calls. More...

ApplicationException	WithDetails (string key, object value)
	Sets a parameter for additional error details. This details can be used to restore error description in other languages. More...

ApplicationException	WithStackTrace (string stackTrace)
	Sets a stack trace for this error. This method returns reference to this exception to implement Builder pattern to chain additional calls. More...

ApplicationException	Wrap (Exception cause)
	Wraps another exception into specified application exception object. If original exception is of ApplicationException type it is returned without changes.Otherwise the original error is set as a cause to specified ApplicationException object. More...

Static Public Member Functions
static ApplicationException	WrapException (ApplicationException error, Exception cause)
	Wraps another exception into specified application exception object. If original exception is of ApplicationException type it is returned without changes.Otherwise the original error is set as a cause to specified ApplicationException object. More...

Public Attributes
string	BaseMessage => Message

Protected Member Functions
	ApplicationException (string message)
	Creates a new instance of application exception with string message. More...

	ApplicationException (SerializationInfo info, StreamingContext context)

Properties
string	Category `[get, set]`

string	CorrelationId `[get, set]`

string	Cause `[get, set]`

string	Code `[get, set]`

int	Status `[get, set]`

StringValueMap	Details `[get, set]`

new string	StackTrace `[get, set]`

Private Attributes
string	_stackTrace

Detailed Description

Defines a base class to defive various application exceptions.

Most languages have own definition of base exception(error) types. However, this class is implemented symmetrically in all languages supported by PipServices toolkit.It allows to create portable implementations and support proper error propagation in microservices calls.

Error propagation means that when microservice implemented in one language calls microservice(s) implemented in a different language(s), errors are returned throught the entire call chain and restored in their original (or close) type.

Since number of potential exception types is endless, PipServices toolkit supports only 12 standard categories of exceptions defined in ErrorCategory. This ApplicationException class acts as a basis for all other 12 standard exception types.

Most exceptions have just free-form message that describes occured error. That may not be sufficient to create meaninful error descriptions. The ApplicationException class proposes an extended error definition that has more standard fields:

message: is a humand readable error description
category: one of 12 standard error categories of errors
status: numeric HTTP status code for REST invocations
code: a unique error code, usually defined as "MY_ERROR_CODE"
correlation_id: a unique transaction id to trace execution through a call chain
details: map with error parameters that can help to recreate meaningful error description in other languages
stack_trace: a stack trace
cause: original error that is wrapped by this exception

ApplicationException class is not serializable.To pass errors through the wire it is converted into ErrorDescription object and restored on receiving end into identical exception type.

See ErrorCategory, ErrorDescription

Constructor & Destructor Documentation

◆ ApplicationException() [1/3]

PipServices3.Commons.Errors.ApplicationException.ApplicationException ( )

Creates a new instance of application exception.

◆ ApplicationException() [2/3]

PipServices3.Commons.Errors.ApplicationException.ApplicationException ( string message )

protected

Creates a new instance of application exception with string message.

Parameters

message a human-readable description of the error.

◆ ApplicationException() [3/3]

PipServices3.Commons.Errors.ApplicationException.ApplicationException	(	string	category = `null`,
		string	correlationId = `null`,
		string	code = `null`,
		string	message = `null`
	)

Creates a new instance of application exception and assigns its values.

Parameters

category	(optional) a standard error category. Default: Unknown
correlationId	(optional) a unique transaction id to trace execution through call chain.
code	(optional) a unique error code. Default: "UNKNOWN"
message	(optional) a human-readable description of the error.

Member Function Documentation

◆ WithCause()

ApplicationException PipServices3.Commons.Errors.ApplicationException.WithCause ( Exception cause )

Sets a original error wrapped by this exception.

This method returns reference to this exception to implement Builder pattern to chain additional calls.

Parameters

cause original error object

Returns: this exception object

◆ WithCode()

ApplicationException PipServices3.Commons.Errors.ApplicationException.WithCode ( string code )

Sets a unique error code.

This method returns reference to this exception to implement Builder pattern to chain additional calls.

Parameters

code	a unique error code

Returns: this exception object

◆ WithCorrelationId()

ApplicationException PipServices3.Commons.Errors.ApplicationException.WithCorrelationId ( string correlationId )

Sets a correlation id which can be used to trace this error through a call chain.

This method returns reference to this exception to implement Builder pattern to chain additional calls.

Parameters

correlationId a unique transaction id to trace error through call chain

Returns: this exception object

◆ WithDetails()

ApplicationException PipServices3.Commons.Errors.ApplicationException.WithDetails	(	string	key,
		object	value
	)

Sets a parameter for additional error details. This details can be used to restore error description in other languages.

This method returns reference to this exception to implement Builder pattern to chain additional calls.

Parameters

key	a details parameter key
value	a details parameter name

Returns: this exception object

◆ WithStackTrace()

ApplicationException PipServices3.Commons.Errors.ApplicationException.WithStackTrace ( string stackTrace )

Sets a stack trace for this error. This method returns reference to this exception to implement Builder pattern to chain additional calls.

Parameters

stackTrace a stack trace where this error occured

Returns: this exception object

◆ WithStatus()

ApplicationException PipServices3.Commons.Errors.ApplicationException.WithStatus ( int status )

Sets a HTTP status code which shall be returned by REST calls.

This method returns reference to this exception to implement Builder pattern to chain additional calls.

Parameters

status an HTTP error code.

Returns: this exception object

◆ Wrap()

ApplicationException PipServices3.Commons.Errors.ApplicationException.Wrap ( Exception cause )

Wraps another exception into specified application exception object. If original exception is of ApplicationException type it is returned without changes.Otherwise the original error is set as a cause to specified ApplicationException object.

Parameters

cause an original error object

Returns: an original or newly created ApplicationException

◆ WrapException()

static ApplicationException PipServices3.Commons.Errors.ApplicationException.WrapException	(	ApplicationException	error,
		Exception	cause
	)

static

Wraps another exception into specified application exception object. If original exception is of ApplicationException type it is returned without changes.Otherwise the original error is set as a cause to specified ApplicationException object.

Parameters

error	an ApplicationException object to wrap the cause
cause	an original error object

Returns: an original or newly created ApplicationException

Member Data Documentation

◆ BaseMessage

string PipServices3.Commons.Errors.ApplicationException.BaseMessage => Message

A human-readable error description (usually written in English)

Property Documentation

◆ Category

string PipServices3.Commons.Errors.ApplicationException.Category

getset

Standard error category

◆ Cause

string PipServices3.Commons.Errors.ApplicationException.Cause

getset

Original error wrapped by this exception

◆ Code

string PipServices3.Commons.Errors.ApplicationException.Code

getset

A unique error code

◆ CorrelationId

string PipServices3.Commons.Errors.ApplicationException.CorrelationId

getset

A unique transaction id to trace execution throug call chain

◆ Details

StringValueMap PipServices3.Commons.Errors.ApplicationException.Details

getset

A map with additional details that can be used to restore error description in other languages

◆ StackTrace

new string PipServices3.Commons.Errors.ApplicationException.StackTrace

getset

Stack trace of the exception

◆ Status

int PipServices3.Commons.Errors.ApplicationException.Status

getset

HTTP status code associated with this error type

The documentation for this class was generated from the following file:

src/Errors/ApplicationException.cs

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Properties

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ApplicationException() [1/3]

◆ ApplicationException() [2/3]

◆ ApplicationException() [3/3]

Member Function Documentation

◆ WithCause()

◆ WithCode()

◆ WithCorrelationId()

◆ WithDetails()

◆ WithStackTrace()

◆ WithStatus()

◆ Wrap()

◆ WrapException()

Member Data Documentation

◆ BaseMessage

Property Documentation

◆ Category

◆ Cause

◆ Code

◆ CorrelationId

◆ Details

◆ StackTrace

◆ Status