Movatterモバイル変換

No results found!

• Microservice Solution

• Exception Handling

• Localization

• Logging

• Object Extensions

• Options

• logged and a formattedJSON message is returned to the client.

  Error Message Format

  Error Message is an instance of theRemoteServiceErrorResponse class. The simplest error JSON has amessage property as shown below:

  {  "error": {    "message": "This topic is locked and can not add a new message"  }}

  There areoptional fields those can be filled based upon the exception that has occurred.

  Error Code

  Errorcode is an optional and unique string value for the exception. ThrownException should implement theIHasErrorCode interface to fill this field. Example JSON value:

  {  "error": {    "code": "App:010042",    "message": "This topic is locked and can not add a new message"  }}

  Error code can also be used to localize the exception and customize the HTTP status code (see the related sections below).

  Error Details

  Errordetails in an optional field of the JSON error message. ThrownException should implement theIHasErrorDetails interface to fill this field. Example JSON value:

  {  "error": {    "code": "App:010042",    "message": "This topic is locked and can not add a new message",    "details": "A more detailed info about the error..."  }}

  Validation Errors

  validationErrors is a standard field that is filled if the thrown exception implements theIHasValidationErrors interface.

  {  "error": {    "code": "App:010046",    "message": "Your request is not valid, please correct and try again!",    "validationErrors": [{      "message": "Username should be minimum length of 3.",      "members": ["userName"]    },    {      "message": "Password is required",      "members": ["password"]    }]  }}

  AbpValidationException implements theIHasValidationErrors interface and it is automatically thrown by the framework when a request input is not valid. So, usually you don't need to deal with validation errors unless you have higly customised validation logic.

  Logging

  Caught exceptions are automatically logged.

  Log Level

  Exceptions are logged with theError level by default. The Log level can be determined by the exception if it implements theIHasLogLevel interface. Example:

  public class MyException : Exception, IHasLogLevel{    public LogLevel LogLevel { get; set; } = LogLevel.Warning;    //...}

  Self Logging Exceptions

  Some exception types may need to write additional logs. They can implement theIExceptionWithSelfLogging if needed. Example:

  public class MyException : Exception, IExceptionWithSelfLogging{    public void Log(ILogger logger)    {        //...log additional info    }}

  ILogger.LogException extension methods is used to write exception logs. You can use the same extension method when needed.

  Business Exceptions

  Most of your own exceptions will be business exceptions. TheIBusinessException interface is used to mark an exception as a business exception.

  BusinessException implements theIBusinessException interface in addition to theIHasErrorCode,IHasErrorDetails andIHasLogLevel interfaces. The default log level isWarning.

  Usually you have an error code related to a particular business exception. For example:

  throw new BusinessException(QaErrorCodes.CanNotVoteYourOwnAnswer);

  QaErrorCodes.CanNotVoteYourOwnAnswer is just aconst string. The following error code format is recommended:

  <code-namespace>:<error-code>

  code-namespace is aunique value specific to your module/application. Example:

  Volo.Qa:010002

  Volo.Qa is the code-namespace here. code-namespace is then will be used whilelocalizing exception messages.

  • You candirectly throw aBusinessException orderive your own exception types from it when needed.
  • All properties are optional for theBusinessException class. But you generally set eitherErrorCode orMessage property.

  Exception Localization

  One problem with throwing exceptions is how to localize error messages while sending it to the client. ABP offers two models and their variants.

  User Friendly Exception

  If an exception implements theIUserFriendlyException interface, then ABP does not change it'sMessage andDetails properties and directly send it to the client.

  UserFriendlyException class is the built-in implementation of theIUserFriendlyException interface. Example usage:

  throw new UserFriendlyException(    "Username should be unique!");

  In this way, there isno need for localization at all. If you want to localize the message, you can inject and use the standardstring localizer (see thelocalization document). Example:

  throw new UserFriendlyException(_stringLocalizer["UserNameShouldBeUniqueMessage"]);

  Then define it in thelocalization resource for each language. Example:

  {  "culture": "en",  "texts": {    "UserNameShouldBeUniqueMessage": "Username should be unique!"  }}

  String localizer already supportsparameterized messages. For example:

  throw new UserFriendlyException(_stringLocalizer["UserNameShouldBeUniqueMessage", "john"]);

  Then the localization text can be:

  "UserNameShouldBeUniqueMessage": "Username should be unique! '{0}' is already taken!"

  • TheIUserFriendlyException interface is derived from theIBusinessException and theUserFriendlyException class is derived from theBusinessException class.

  Using Error Codes

  UserFriendlyException is fine, but it has a few problems in advanced usages:

  • It requires you toinject the string localizer everywhere and always use it while throwing exceptions.
  • However, in some of the cases, it maynot be possible to inject the string localizer (in a static context or in an entity method).

  Instead of localizing the message while throwing the exception, you can separate the process usingerror codes.

  First, define thecode-namespace tolocalization resource mapping in the module configuration:

  services.Configure<AbpExceptionLocalizationOptions>(options =>{    options.MapCodeNamespace("Volo.Qa", typeof(QaResource));});

  Then any of the exceptions withVolo.Qa namespace will be localized using their given localization resource. The localization resource should always have an entry with the error code key. Example:

  {  "culture": "en",  "texts": {    "Volo.Qa:010002": "You can not vote your own answer!"  }}

  Then a business exception can be thrown with the error code:

  throw new BusinessException(QaDomainErrorCodes.CanNotVoteYourOwnAnswer);

  • Throwing any exception implementing theIHasErrorCode interface behaves the same. So, the error code localization approach is not unique to theBusinessException class.
  • Defining localized string is not required for an error message. If it's not defined, ABP sends the default error message to the client. It does not use theMessage property of the exception! if you want that, use theUserFriendlyException (or use an exception type that implements theIUserFriendlyException interface).

  Using Message Parameters

  If you have a parameterized error message, then you can set it with the exception'sData property. For example:

  throw new BusinessException("App:010046"){    Data =    {        {"UserName", "john"}    }};

  Fortunately there is a shortcut way to code this:

  throw new BusinessException("App:010046")    .WithData("UserName", "john");

  Then the localized text can contain theUserName parameter:

  {  "culture": "en",  "texts": {    "App:010046": "Username should be unique. '{UserName}' is already taken!"  }}

  • WithData can be chained with more than one parameter (like.WithData(...).WithData(...)).

  HTTP Status Code Mapping

  ABP tries to automatically determine the most suitable HTTP status code for common exception types by following these rules:

  • For theAbpAuthorizationException:
    • Returns401 (unauthorized) if user has not logged in.
    • Returns403 (forbidden) if user has logged in.
  • Returns400 (bad request) for theAbpValidationException.
  • Returns404 (not found) for theEntityNotFoundException.
  • Returns403 (forbidden) for theIBusinessException (andIUserFriendlyException since it extends theIBusinessException).
  • Returns501 (not implemented) for theNotImplementedException.
  • Returns500 (internal server error) for other exceptions (those are assumed as infrastructure exceptions).

  TheIHttpExceptionStatusCodeFinder is used to automatically determine the HTTP status code. The default implementation is theDefaultHttpExceptionStatusCodeFinder class. It can be replaced or extended as needed.

  Custom Mappings

  Automatic HTTP status code determination can be overrided by custom mappings. For example:

  services.Configure<AbpExceptionHttpStatusCodeOptions>(options =>{    options.Map("Volo.Qa:010002", HttpStatusCode.Conflict);});

  Subscribing to the Exceptions

  It is possible to be informed when the ABPhandles an exception. It automaticallylogs all the exceptions to the standardlogger, but you may want to do more.

  In this case, create a class derived from theExceptionSubscriber class in your application:

  public class MyExceptionSubscriber : ExceptionSubscriber{    public async override Task HandleAsync(ExceptionNotificationContext context)    {        //TODO...    }}

  Thecontext object contains necessary information about the exception occurred.

  You can have multiple subscribers, each gets a copy of the exception. Exceptions thrown by your subscriber is ignored (but still logged).

  Built-In Exceptions

  Some exception types are automatically thrown by the framework:

  • AbpAuthorizationException is thrown if the current user has no permission to perform the requested operation. Seeauthorization for more.
  • AbpValidationException is thrown if the input of the current request is not valid. Seevalidation for more.
  • EntityNotFoundException is thrown if the requested entity is not available. This is mostly thrown byrepositories.

  You can also throw these type of exceptions in your code (although it's rarely needed).

  AbpExceptionHandlingOptions

  AbpExceptionHandlingOptions is the mainoptions object to configure the exception handling system. You can configure it in theConfigureServices method of yourmodule:

  Configure<AbpExceptionHandlingOptions>(options =>{    options.SendExceptionsDetailsToClients = true;    options.SendStackTraceToClients = false;});

  Here, a list of the options you can configure:

  • SendExceptionsDetailsToClients (default:false): You can enable or disable sending exception details to the client.
  • SendStackTraceToClients (default:true): You can enable or disable sending the stack trace of exception to the client. If you want to send the stack trace to the client, you must set bothSendStackTraceToClients andSendExceptionsDetailsToClients options totrue otherwise, the stack trace will not be sent to the client.

  See Also

  • Video tutorial

Thank you for your valuable feedback!

Please note that although we cannot respond to feedback, our team will use your comments to improve the experience.