diff --git a/.github/workflows/nuget.yml b/.github/workflows/nuget.yml index ff3f2cf..6dd31cd 100644 --- a/.github/workflows/nuget.yml +++ b/.github/workflows/nuget.yml @@ -6,7 +6,7 @@ on: - main jobs: - deploy: + publish: name: 'build, pack & publish' runs-on: ubuntu-latest steps: @@ -16,13 +16,25 @@ jobs: - name: 'Install dotnet' uses: actions/setup-dotnet@v1 with: - dotnet-version: '6.0.x' + dotnet-version: 6.0.x - - name: 'Restore packages' - run: dotnet restore ${{ env.PROJECT_PATH }} - - - name: 'Build project' - run: dotnet build ${{ env.PROJECT_PATH }} --no-restore --configuration Release + - name: 'Publish Abstractions' + id : publish_abstractions_nuget + uses: rohith/publish-nuget@v2 + with: + PROJECT_FILE_PATH: src/ExceptionAll.Abstractions/ExceptionAll.Abstractions.csproj + NUGET_KEY: ${{ secrets.NUGET_AUTH_TOKEN }} + + - name: 'Publish ExceptionAll' + id: publish_exceptionall_nuget + uses: rohith/publish-nuget@v2 + with: + PROJECT_FILE_PATH: src/ExceptionAll/ExceptionAll.csproj + NUGET_KEY: ${{ secrets.NUGET_AUTH_TOKEN }} - - name: 'Push package' - run: dotnet nuget push ${{ env.PACKAGE_OUTPUT_DIRECTORY }}\*.nupkg -k ${{ secrets.NUGET_AUTH_TOKEN }} -s ${{ env.NUGET_SOURCE_URL }} \ No newline at end of file + - name: 'Publish Client' + id: publish_client_nuget + uses: rohith/publish-nuget@v2 + with: + PROJECT_FILE_PATH: src/ExceptionAll.Client/ExceptionAll.Client.csproj + NUGET_KEY: ${{ secrets.NUGET_AUTH_TOKEN }} \ No newline at end of file diff --git a/README.md b/README.md index f69436c..3cb7456 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ # ExceptionAll -Package | Version | Downloads ------|------|------- -ExceptionAll | [![Nuget version](https://img.shields.io/nuget/v/ExceptionAll)](https://www.nuget.org/packages/ExceptionAll/) | [![Nuget downloads](https://img.shields.io/nuget/dt/ExceptionAll)](https://www.nuget.org/packages/ExceptionAll/) -ExceptionAll.Abstractions | [![Nuget version](https://img.shields.io/nuget/v/ExceptionAll.Abstractions)](https://www.nuget.org/packages/ExceptionAll.Abstractions/) | [![Nuget downloads](https://img.shields.io/nuget/dt/ExceptionAll.Abstractions)](https://www.nuget.org/packages/ExceptionAll.Abstractions/) -ExceptionAll.Client | [![Nuget version](https://img.shields.io/nuget/v/ExceptionAll.Client)](https://www.nuget.org/packages/ExceptionAll.Client/) | [![Nuget downloads](https://img.shields.io/nuget/dt/ExceptionAll.Client)](https://www.nuget.org/packages/ExceptionAll.Client/) +| Package | Version | Downloads | +|----------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------| +| ExceptionAll | [![Nuget version](https://img.shields.io/nuget/v/ExceptionAll)](https://www.nuget.org/packages/ExceptionAll/) | [![Nuget downloads](https://img.shields.io/nuget/dt/ExceptionAll)](https://www.nuget.org/packages/ExceptionAll/) | +| ExceptionAll.Abstractions | [![Nuget version](https://img.shields.io/nuget/v/ExceptionAll.Abstractions)](https://www.nuget.org/packages/ExceptionAll.Abstractions/) | [![Nuget downloads](https://img.shields.io/nuget/dt/ExceptionAll.Abstractions)](https://www.nuget.org/packages/ExceptionAll.Abstractions/) | +| ExceptionAll.Client | [![Nuget version](https://img.shields.io/nuget/v/ExceptionAll.Client)](https://www.nuget.org/packages/ExceptionAll.Client/) | [![Nuget downloads](https://img.shields.io/nuget/dt/ExceptionAll.Client)](https://www.nuget.org/packages/ExceptionAll.Client/) | ## Table of Contents @@ -13,12 +13,15 @@ Package | Version | Downloads - [Server Side](#server-side) - [Client Side](#client-side) - [Example Code](#example-code) + - [Server](#server) + - [Client](#client) - [Swagger Examples](#swagger-examples) - [Extending ExceptionAll](#extending-exceptionall) + ________ ## Summary -ExceptionAll is a library for adding global error handling to Web API solutions using .NET Core. Its goals are to: +ExceptionAll is a library for adding global error handling to Web API solutions as well as streamline http client interactions. Its goals are to: 1. Reduce code noise by reducing the need for 'try-catch' blocks in code 2. Provide a single source of responsibility for configuring and maintaining API error handling logic 3. Allow for the customization of error response data and logging actions @@ -28,7 +31,7 @@ ExceptionAll is a library for adding global error handling to Web API solutions _______ ## Setup -Note: ExceptionAll offers both front and backend solutions but they do not need to be mutally exclusive. Please read over what each solution does and how it is applicable to your problem/application +Note: ExceptionAll offers both front and backend solutions but they do not need to be mutually exclusive. Please read over what each solution does and how it is applicable to your problem/application ### Server Side 1. Install ExceptionAll & ExceptionAll.Abstractions nuget packages @@ -38,6 +41,7 @@ _______ 2. ContextConfiguration - Allows the developer to extend the standard response object by adding details from the HttpContext. Options become limitless since custom headers are accessible. - As the context properties are updated, the Swagger documentation should also be updated as well. + - The 'Errors' key is reserved by ExceptionAll ```csharp public class ExceptionAllConfiguration : IExceptionAllConfiguration @@ -78,14 +82,17 @@ _______ 1. Install both ExceptionAll.Client & ExceptionAll.Abstractions nuget packages 2. Add the following code within your Program.cs file in order to inject the applicable services - - ```csharp + ```csharp + using ExceptionAll.Client.Helpers; + builder.Services.AddExceptionAllClientServices(); builder.Services.AddHttpClient(); ``` a. In client use, you will use 'IExceptionAllClientFactory' which is a wrapper around the standard .NET IHttpClientFactory interface. If clients are needed to be configured differently for different endpoints, simply add additional HttpClients with the applicable configurations. _______ ## Example Code + +### Server 1. The default API response provided by ExceptionAll. This simulates an uncaught exception in your API code. This response will also be returned for specific exception types not initially considered during configuration. 1. API Controller code @@ -107,7 +114,7 @@ _______ ``` 2. API Response - ![alt text](ReadMeImages\v4\ApiControllerStandardResponse.PNG) + ![alt text](ReadMeImages/v4/ApiControllerStandardResponse.PNG) 2. This example shows catching an exception configured in the configuration class. (See above configuration code) 1. API Controller code @@ -124,7 +131,7 @@ _______ ``` 1. API Response. The properties match what we see in our configuration, seen further up on the page. - ![alt text](ReadMeImages\v4\ArgumentNullRefResponse.PNG) + ![alt text](ReadMeImages/v4/ArgumentNullRefResponse.PNG) 3. There may be times where an ExceptionAll response is undesired. To get a non-ExceptionAll response, just wrap the controller/endpoint code with a standard 'try-catch' block and return the new, desired object. 1. API Controller code @@ -147,7 +154,7 @@ _______ ``` 1. API Response - ![alt text](ReadMeImages\v4\NonExceptionAllResponse.PNG) + ![alt text](ReadMeImages/v4/NonExceptionAllResponse.PNG) 4. This example covers manual response generation, for times developers want to return caught exceptions with a special message and/or a surface list of errors to the user 1. API Controller code @@ -181,8 +188,22 @@ _______ ``` 1. API Response - ![alt text](ReadMeImages\v4\ManuallyReturnedResponse.PNG) + ![alt text](ReadMeImages/v4/ManuallyReturnedResponse.PNG) +### Client +1. Make sure to inject the ExceptionAllClient factory wherever you are trying to make HttpClient calls + ```csharp + @inject IExceptionAllClientFactory _exceptionAllClientFactory + ``` +2. Create a HttpClient like you normally would. Two examples below + ```csharp + // Standard client creation + IExceptionAllClient ExceptionAllClient = _exceptionAllClientFactory.CreateClient(); + + // Creating named HttpClient configured in IOC + IExceptionAllClient ClientWithHeader = _exceptionAllClientFactory.CreateClient("Test"); + ``` +3. Execute one of the interface methods in order to call a http CRUD operation _______ ## Swagger Examples @@ -228,7 +249,7 @@ In order to provide the Swagger examples, add attributes with the return object The above code should give you the following Swagger response examples: -![alt text](ReadMeImages\v4\SwaggerExamples.PNG) +![alt text](ReadMeImages/v4/SwaggerExamples.PNG) _______ @@ -238,13 +259,9 @@ and create additional detail types, follow the below example as a template and i ```csharp -public class BadGatewayDetails : IExceptionAllDetails +public class BadGatewayDetails : BaseDetails { - public string Title => GetDetails().Title; - public int StatusCode => GetDetails().StatusCode; - public string Message { get; init; } = string.Empty; - public IReadOnlyDictionary? ContextDetails { get; init; } - public (int StatusCode, string Title) GetDetails() + public override (int StatusCode, string Title) GetDetails() { return (502, "Bad Gateway"); } diff --git a/src/ExceptionAll.Abstractions/ExceptionAll.Abstractions.csproj b/src/ExceptionAll.Abstractions/ExceptionAll.Abstractions.csproj index 0344afd..f2f96ef 100644 --- a/src/ExceptionAll.Abstractions/ExceptionAll.Abstractions.csproj +++ b/src/ExceptionAll.Abstractions/ExceptionAll.Abstractions.csproj @@ -7,13 +7,14 @@ True https://github.com/1eyewonder/ExceptionAll Git - Global Exception Handling + global-exception-handling api clean-code netcore csharp swagger Object abstractions for ExceptionAll to be shared in both server and client applications 2022 MIT Bronson Bata 1.0.0 False + 6.0.0 \ No newline at end of file diff --git a/src/ExceptionAll.Client/Clients/ExceptionAllClient.cs b/src/ExceptionAll.Client/Clients/ExceptionAllClient.cs index 7c27607..63fc29a 100644 --- a/src/ExceptionAll.Client/Clients/ExceptionAllClient.cs +++ b/src/ExceptionAll.Client/Clients/ExceptionAllClient.cs @@ -48,7 +48,7 @@ public ExceptionAllClient( /// /// public async ValueTask PostContentAsync( - string relativeUrl, T content, CancellationToken token = new()) + string relativeUrl, T content, CancellationToken token = default) { var response = await _httpClient.PostAsJsonAsync(relativeUrl, content, _options, token); await _validation.ValidateAsync(response); @@ -60,7 +60,7 @@ public ExceptionAllClient( /// /// public async ValueTask PutContentAsync( - string relativeUrl, T content, CancellationToken token = new()) + string relativeUrl, T content, CancellationToken token = default) { var response = await _httpClient.PutAsJsonAsync(relativeUrl, content, _options, token); await _validation.ValidateAsync(response); diff --git a/src/ExceptionAll.Client/ExceptionAll.Client.csproj b/src/ExceptionAll.Client/ExceptionAll.Client.csproj index dfc0e2c..3df6ad6 100644 --- a/src/ExceptionAll.Client/ExceptionAll.Client.csproj +++ b/src/ExceptionAll.Client/ExceptionAll.Client.csproj @@ -7,13 +7,14 @@ True https://github.com/1eyewonder/ExceptionAll Git - Global Exception Handling - ExceptionAll client package for better API error handling and serialization + global-exception-handling api clean-code netcore csharp + ExceptionAll client package for cleaner API error handling and serialization 2022 MIT Bronson Bata 1.0.0 False + 6.0.0 diff --git a/src/ExceptionAll.Client/Interfaces/IExceptionAllClient.cs b/src/ExceptionAll.Client/Interfaces/IExceptionAllClient.cs index bccba25..2902013 100644 --- a/src/ExceptionAll.Client/Interfaces/IExceptionAllClient.cs +++ b/src/ExceptionAll.Client/Interfaces/IExceptionAllClient.cs @@ -31,7 +31,7 @@ public interface IExceptionAllClient /// /// /// - ValueTask PostContentAsync(string relativeUrl, T content, CancellationToken token = new()); + ValueTask PostContentAsync(string relativeUrl, T content, CancellationToken token = default); /// /// Executes Http Put and returns the requested object type @@ -41,5 +41,5 @@ public interface IExceptionAllClient /// /// /// - ValueTask PutContentAsync(string relativeUrl, T content, CancellationToken token = new()); + ValueTask PutContentAsync(string relativeUrl, T content, CancellationToken token = default); } \ No newline at end of file diff --git a/src/ExceptionAll/ExceptionAll.csproj b/src/ExceptionAll/ExceptionAll.csproj index 02f08a4..d49995e 100644 --- a/src/ExceptionAll/ExceptionAll.csproj +++ b/src/ExceptionAll/ExceptionAll.csproj @@ -6,8 +6,8 @@ true https://github.com/1eyewonder/ExceptionAll Git - Global Exception Handling - Library for adding global error handling to .NET Core Web API solutions. + global-exception-handling api clean-code netcore csharp swagger + Adds configurable global error handling to .NET Core Web API solutions 2022 MIT Bronson Bata @@ -17,6 +17,7 @@ enable False /ExceptionAll-swagger.xml + 6.0.0