Add support to show custom error message

Author: vladimir-litvinchik

doc/images/custom-error-message.png

@@ -24,6 +24,7 @@ public class ViewerController : ControllerBase
         private readonly IFileStorage _fileStorage;
         private readonly IFileNameResolver _fileNameResolver;
         private readonly ISearchTermResolver _searchTermResolver;
+        private readonly IErrorMessageProvider _errorMessageProvider;
         private readonly IApiUrlBuilder _apiUrlBuilder;
         private readonly ILogger<ViewerController> _logger;
         private readonly Config _config;
@@ -33,13 +34,15 @@ public ViewerController(
             IFileStorage fileStorage,
             IFileNameResolver fileNameResolver,
             ISearchTermResolver searchTermResolver,
+            IErrorMessageProvider errorMessageProvider,
             IOptions<Config> config,
             IApiUrlBuilder apiUrlBuilder,
             ILogger<ViewerController> logger)
         {
             _fileStorage = fileStorage;
             _fileNameResolver = fileNameResolver;
             _searchTermResolver = searchTermResolver;
+            _errorMessageProvider = errorMessageProvider;
             _apiUrlBuilder = apiUrlBuilder;
             _viewer = viewer;
             _logger = logger;
@@ -67,7 +70,10 @@ public async Task<IActionResult> ListDir([FromBody] ListDirRequest request)
             {
                 _logger.LogError(ex, "Failed to load file tree.");
 
-                return ErrorJsonResult(ex.Message);
+                var ctx = new ErrorContext(ApiNames.API_METHOD_LIST_DIR, HttpContext);
+                var msg = _errorMessageProvider.GetErrorMessage(ex, ctx);
+
+                return ErrorJsonResult(msg);
             }
         }
 
@@ -92,7 +98,10 @@ public async Task<IActionResult> UploadFile()
             {
                 _logger.LogError(ex, "Failed to upload document.");
 
-                return ErrorJsonResult(ex.Message);
+                var ctx = new ErrorContext(ApiNames.API_METHOD_UPLOAD_FILE, HttpContext);
+                var msg = _errorMessageProvider.GetErrorMessage(ex, ctx);
+
+                return ErrorJsonResult(msg);
             }
         }
 
@@ -137,7 +146,10 @@ public async Task<IActionResult> ViewData([FromBody] ViewDataRequest request)
 
                 _logger.LogError(ex, "Failed to read document description.");
 
-                return ErrorJsonResult(ex.Message);
+                var ctx = new ErrorContext(ApiNames.API_METHOD_VIEW_DATA, HttpContext);
+                var msg = _errorMessageProvider.GetErrorMessage(ex, ctx);
+
+                return ErrorJsonResult(msg);
             }
         }
 
@@ -166,7 +178,10 @@ public async Task<IActionResult> CreatePages([FromBody] CreatePagesRequest reque
 
                 _logger.LogError(ex, "Failed to retrieve document pages.");
 
-                return ErrorJsonResult(ex.Message);
+                var ctx = new ErrorContext(ApiNames.API_METHOD_CREATE_PAGES, HttpContext);
+                var msg = _errorMessageProvider.GetErrorMessage(ex, ctx);
+
+                return ErrorJsonResult(msg);
             }
         }
 
@@ -202,7 +217,10 @@ public async Task<IActionResult> CreatePdf([FromBody] CreatePdfRequest request)
 
                 _logger.LogError(ex, "Failed to create PDF file.");
 
-                return ErrorJsonResult(ex.Message);
+                var ctx = new ErrorContext(ApiNames.API_METHOD_CREATE_PDF, HttpContext);
+                var msg = _errorMessageProvider.GetErrorMessage(ex, ctx);
+
+                return ErrorJsonResult(msg);
             }
         }
 
@@ -220,7 +238,10 @@ public async Task<IActionResult> GetPage([FromQuery] GetPageRequest request)
             {
                 _logger.LogError(ex, "Failed to retrieve document page.");
 
-                return ErrorJsonResult(ex.Message);
+                var ctx = new ErrorContext(ApiNames.API_METHOD_GET_PAGE, HttpContext);
+                var msg = _errorMessageProvider.GetErrorMessage(ex, ctx);
+
+                return ErrorJsonResult(msg);
             }
         }
 
@@ -238,7 +259,10 @@ public async Task<IActionResult> GetThumb([FromQuery] GetThumbRequest request)
             {
                 _logger.LogError(ex, "Failed to retrieve document thumb.");
 
-                return ErrorJsonResult(ex.Message);
+                var ctx = new ErrorContext(ApiNames.API_METHOD_GET_THUMB, HttpContext);
+                var msg = _errorMessageProvider.GetErrorMessage(ex, ctx);
+
+                return ErrorJsonResult(msg);
             }
         }
 
@@ -262,7 +286,10 @@ public async Task<IActionResult> GetPdf([FromQuery] GetPdfRequest request)
             {
                 _logger.LogError(ex, "Failed to retrieve PDF file.");
 
-                return ErrorJsonResult(ex.Message);
+                var ctx = new ErrorContext(ApiNames.API_METHOD_GET_PDF, HttpContext);
+                var msg = _errorMessageProvider.GetErrorMessage(ex, ctx);
+
+                return ErrorJsonResult(msg);
             }
         }
 
@@ -289,7 +316,10 @@ public async Task<IActionResult> GetResource([FromQuery] GetResourceRequest requ
             {
                 _logger.LogError(ex, "Failed to load document page resource.");
 
-                return ErrorJsonResult(ex.Message);
+                var ctx = new ErrorContext(ApiNames.API_METHOD_GET_RESOURCE, HttpContext);
+                var msg = _errorMessageProvider.GetErrorMessage(ex, ctx);
+
+                return ErrorJsonResult(msg);
             }
         }
 

src/GroupDocs.Viewer.UI.API/Controllers/ViewerController.cs

@@ -0,0 +1,34 @@
+using System;
+using Microsoft.AspNetCore.Http;
+
+namespace GroupDocs.Viewer.UI.Api
+{
+    /// <summary>
+    /// Represents contextual information for an error message,  
+    /// including the API method where the exception occurred and the associated HTTP context.
+    /// </summary>
+    public record ErrorContext
+    {
+        /// <summary>
+        /// The name of the API method where the exception occurred.
+        /// </summary>
+        public string ApiMethod { get; init; }
+
+        /// <summary>
+        /// The HTTP context associated with the request.
+        /// </summary>
+        public HttpContext HttpContext { get; init; }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ErrorMessageContext"/> record.
+        /// </summary>
+        /// <param name="apiMethod">The API method name.</param>
+        /// <param name="httpContext">The associated HTTP context.</param>
+        /// <exception cref="ArgumentNullException">Thrown if any parameter is null.</exception>
+        public ErrorContext(string apiMethod, HttpContext httpContext)
+        {
+            ApiMethod = apiMethod ?? throw new ArgumentNullException(nameof(apiMethod));
+            HttpContext = httpContext ?? throw new ArgumentNullException(nameof(httpContext));
+        }
+    }
+}

src/GroupDocs.Viewer.UI.API/ErrorHandling/ErrorContext.cs

@@ -0,0 +1,19 @@
+using System;
+namespace GroupDocs.Viewer.UI.Api
+{
+    /// <summary>
+    /// Defines a contract for providing user-friendly error messages based on exceptions.
+    /// Implementations can customize how error messages are generated for different exception types.
+    /// </summary>
+    public interface IErrorMessageProvider
+    {
+        /// <summary>
+        /// Retrieves an error message based on the given exception.  
+        /// The returned message is intended to be displayed on the UI.  
+        /// </summary>
+        /// <param name="exception">The exception to process.</param>
+        /// <param name="context">The exception message context.</param>
+        /// <returns>A user-friendly error message.</returns>
+        string GetErrorMessage(Exception exception, ErrorContext context);
+    }
+}

src/GroupDocs.Viewer.UI.API/ErrorHandling/IErrorMessageProvider.cs

@@ -0,0 +1,13 @@
+using System;
+
+namespace GroupDocs.Viewer.UI.Api
+{
+    /// Provides a default implementation for retrieving error messages from exceptions.
+    /// The returned message is displayed on the UI.
+    /// </summary>
+    public class ExceptionMessageProvider : IErrorMessageProvider
+    {
+        /// <inheritdoc />
+        public string GetErrorMessage(Exception exception, ErrorContext context) => exception.Message;
+    }
+}

src/GroupDocs.Viewer.UI.API/ErrorHandling/Implementation/ExceptionMessageProvider.cs

@@ -0,0 +1,57 @@
+# UI for GroupDocs.Viewer for .NET (API)
+
+`GroupDocs.Viewer.UI.Api` contains base types for implementing an API for `GroupDocs.Viewer.UI`.
+
+There are two API implementations provided within this package:
+
+* `GroupDocs.Viewer.UI.SelfHost.Api` - A self-hosted service that uses the 
+  [GroupDocs.Viewer](https://www.nuget.org/packages/groupdocs.viewer) package.
+* `GroupDocs.Viewer.UI.Cloud.Api` - Uses the cloud API provided by GroupDocs.
+
+This readme includes information and usage examples for the features provided by this module.
+
+## Features
+
+This section lists the features provided by the module.
+
+### Error Handling
+
+Types that enable you to display custom error messages can be found in the [ErrorHandling](./ErrorHandling) folder.
+The key type here is the [ErrorMessageProvider.cs](./ErrorMessageProvider.cs) interface, which defines a contract for providing user-friendly error messages based on exceptions.
+
+The following code demonstrates how to implement a custom error message provider:
+
+```cs
+using GroupDocs.Viewer.UI.Api;
+
+//...
+
+public class MyErrorMessageProvider : IErrorMessageProvider
+{
+    public string GetErrorMessage(Exception exception, ErrorContext context)
+    {
+        return "This is my custom error message...";
+    }
+}
+```
+
+Once the custom error message provider is implemented, it can be registered during the application composition stage.
+
+The following code snippet shows how to register a custom service as a singleton:
+
+```cs
+using GroupDocs.Viewer.UI.Api;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddSingleton<IErrorMessageProvider, MyErrorMessageProvider>();
+```
+
+**NOTE:** The service should be registered before you register the self-hosted or cloud API for it to take effect.
+
+By default, [ExceptionMessageProvider.cs](./ErrorHandling/ExceptionMessageProvider.cs) is registered.
+This class provides a default implementation that returns the exception error message.
+
+Once a custom error message provider is registered, a popup with the custom error message will be displayed in case of an error.
+
+![GroupDocs.Viewer.UI - Custom error message](https://raw.githubusercontent.com/groupdocs-viewer/groupdocs-viewer.github.io/master/resources/image/ui/custom-error-message.png)

src/GroupDocs.Viewer.UI.API/README.md

@@ -71,6 +71,7 @@ public static GroupDocsViewerUIApiBuilder AddGroupDocsViewerCloudApi(this IMvcBu
             builder.Services.AddTransient<IFileCache, NoopFileCache>();
             builder.Services.TryAddSingleton<IFileNameResolver, FilePathFileNameResolver>();
             builder.Services.TryAddSingleton<ISearchTermResolver, SearchTermResolver>();
+            builder.Services.TryAddSingleton<IErrorMessageProvider, ExceptionMessageProvider>();
             builder.Services.TryAddSingleton<IPageFormatter, NoopPageFormatter>();
             builder.Services.TryAddSingleton<IUIConfigProvider, UIConfigProvider>();
 

src/GroupDocs.Viewer.UI.Cloud.Api/Extensions/MvcBuilderExtensions.cs

@@ -49,6 +49,7 @@ public static GroupDocsViewerUIApiBuilder AddGroupDocsViewerSelfHostApi(this IMv
             builder.Services.TryAddSingleton<IFileTypeResolver, FileExtensionFileTypeResolver>();
             builder.Services.TryAddSingleton<IPageFormatter, NoopPageFormatter>();
             builder.Services.TryAddSingleton<ISearchTermResolver, SearchTermResolver>();
+            builder.Services.TryAddSingleton<IErrorMessageProvider, ExceptionMessageProvider>();
             builder.Services.TryAddSingleton<IUIConfigProvider, UIConfigProvider>();
 
             if (config.InternalCacheOptions.IsCacheEnabled)