Merge pull request #6 from konak/dev-response-headers

Merge dev-response-headers branch into dev

README.md

@@ -1,3 +1,65 @@
 [![.NET](https://github.com/konak/am.kon.packages.services.web-client-service/actions/workflows/dotnet.yml/badge.svg)](https://github.com/konak/am.kon.packages.services.web-client-service/actions/workflows/dotnet.yml)
 
-# am.kon.packages.services.web-client-service
+# WebClientService for .NET Core
+
+The WebClientService package provides a robust and flexible web client component designed to be used as a service within .NET Core applications. It leverages the power of '**IHttpClientFactory**' to facilitate efficient and scalable interactions with web services. This package supports dependency injection, making it easy to integrate into your existing .NET Core applications.
+
+## Key Features:
+- **Dependency Injection**: Seamlessly integrates with the .NET Core dependency injection framework.
+- **HTTP Client Management**: Utilizes '**IHttpClientFactory**' for robust HTTP client instantiation and management.
+- **Result Handling**: Comprehensive handling of HTTP response results with detailed status and error information.
+- **Extensible Base Classes**: Abstract base classes for implementing services that interact with web endpoints, returning various data types including strings and streams.
+- **Configurable Requests**: Supports various HTTP methods, custom headers, bearer token authentication, and more.
+
+## Usage Scenarios:
+- Consuming RESTful APIs
+- Fetching data from web services
+- Handling HTTP responses with rich error information
+- Streaming data from endpoints
+
+## Getting Started:
+
+1. **Installation**: Install the package via NuGet Package Manager.
+
+```shell
+dotnet add package WebClientService
+```
+
+2. **Configuration**: Configure IHttpClientFactory in your Startup.cs.
+
+```C#
+public void ConfigureServices(IServiceCollection services)
+{
+    services.AddHttpClient();
+    services.AddScoped<WebClientStringDataService>();
+    services.AddScoped<WebClientStreamDataService>();
+}
+```
+
+3. **Usage**: Inject the service into your controllers or services and start making web requests.
+
+```C#
+public class MyService
+{
+    private readonly WebClientStringDataService _webClient;
+
+    public MyService(WebClientStringDataService webClient)
+    {
+        _webClient = webClient;
+    }
+
+    public async Task<string> GetDataAsync(Uri requestUri)
+    {
+        var result = await _webClient.InvokeRequest(requestUri);
+        if (result.Result == RequestInvocationResultTypes.Ok)
+        {
+            return result.Data;
+        }
+        else
+        {
+            // Handle error
+            throw new Exception(result.Message);
+        }
+    }
+}
+```

src/am.kon.packages.services.web-client-service/Constants/HttpAuthenticationScheme.cs

@@ -2,7 +2,7 @@
 namespace am.kon.packages.services.WebClientService.Constants
 {
 	/// <summary>
-	/// Class for the constatns describing http authentication schemes
+	/// Class for the constants describing HTTP authentication schemes.
 	/// </summary>
 	public static class HttpAuthenticationScheme
 	{

src/am.kon.packages.services.web-client-service/Constants/HttpClientNames.cs

@@ -2,12 +2,12 @@
 namespace am.kon.packages.services.WebClientService.Constants
 {
     /// <summary>
-    /// Class with constants for HttpClient names
+    /// Class with constants for HttpClient names.
     /// </summary>
     public static class HttpClientNames
     {
         /// <summary>
-        /// name of the default http client name
+        /// Name of the default HttpClient name.
         /// </summary>
         public const string Default = "default";
     }

src/am.kon.packages.services.web-client-service/Constants/HttpContentMediaTypes.cs

@@ -2,11 +2,26 @@
 namespace am.kon.packages.services.WebClientService.Constants
 {
     /// <summary>
-    /// Class of media type constants
+    /// Enums of media types.
     /// </summary>
-    public static class HttpContentMediaTypes
+    public enum HttpContentMediaTypes
     {
-        public const string ApplicationJson = "application/json";
+        None,
+        TextPlain,
+        TextHtml,
+        TextCss,
+        ApplicationJson,
+        ApplicationXml,
+        ApplicationFormUrlEncoded,
+        ApplicationOctetStream,
+        MultipartFormData,
+        ImagePng,
+        ImageJpeg,
+        ImageGif,
+        AudioMpeg,
+        AudioOgg,
+        VideoMp4,
+        VideoOgg
     }
 }
 

src/am.kon.packages.services.web-client-service/Constants/HttpContentMediaTypesConstants.cs

@@ -0,0 +1,24 @@
+namespace am.kon.packages.services.WebClientService.Constants
+{
+    /// <summary>
+    /// Class of media type constants.
+    /// </summary>
+    public static class HttpContentMediaTypesConstants
+    {
+        public const string TextPlain = "text/plain";
+        public const string TextHtml = "text/html";
+        public const string TextCss = "text/css";
+        public const string ApplicationJson = "application/json";
+        public const string ApplicationXml = "application/xml";
+        public const string ApplicationFormUrlEncoded = "application/x-www-form-urlencoded";
+        public const string ApplicationOctetStream = "application/octet-stream";
+        public const string MultipartFormData = "multipart/form-data";
+        public const string ImagePng = "image/png";
+        public const string ImageJpeg = "image/jpeg";
+        public const string ImageGif = "image/gif";
+        public const string AudioMpeg = "audio/mpeg";
+        public const string AudioOgg = "audio/ogg";
+        public const string VideoMp4 = "video/mp4";
+        public const string VideoOgg = "video/ogg";
+    }
+}

src/am.kon.packages.services.web-client-service/Extensions/HttpContentMediaTypesExtensions.cs

@@ -0,0 +1,40 @@
+using System;
+using am.kon.packages.services.WebClientService.Constants;
+
+namespace am.kon.packages.services.WebClientService.Extensions
+{
+    /// <summary>
+    /// Extension methods for <see cref="HttpContentMediaTypes"/>.
+    /// </summary>
+    public static class HttpContentMediaTypesExtensions
+    {
+        /// <summary>
+        /// Extension method to get string representation for instance of <see cref="HttpContentMediaTypes"/>.
+        /// </summary>
+        /// <param name="mediaType">Instance of <see cref="HttpContentMediaTypes"/> to get string representation for.</param>
+        /// <returns>String representation of the instance of <see cref="HttpContentMediaTypes"/>.</returns>
+        /// <exception cref="ArgumentOutOfRangeException">Trows when invalid value was provided for <see cref="HttpContentMediaTypes"/>.</exception>
+        public static string GetMimeType(this HttpContentMediaTypes mediaType)
+        {
+            return mediaType switch
+            {
+                HttpContentMediaTypes.TextPlain => HttpContentMediaTypesConstants.TextPlain,
+                HttpContentMediaTypes.TextHtml => HttpContentMediaTypesConstants.TextHtml,
+                HttpContentMediaTypes.TextCss => HttpContentMediaTypesConstants.TextCss,
+                HttpContentMediaTypes.ApplicationJson => HttpContentMediaTypesConstants.ApplicationJson,
+                HttpContentMediaTypes.ApplicationXml => HttpContentMediaTypesConstants.ApplicationXml,
+                HttpContentMediaTypes.ApplicationFormUrlEncoded => HttpContentMediaTypesConstants.ApplicationFormUrlEncoded,
+                HttpContentMediaTypes.ApplicationOctetStream => HttpContentMediaTypesConstants.ApplicationOctetStream,
+                HttpContentMediaTypes.MultipartFormData => HttpContentMediaTypesConstants.MultipartFormData,
+                HttpContentMediaTypes.ImagePng => HttpContentMediaTypesConstants.ImagePng,
+                HttpContentMediaTypes.ImageJpeg => HttpContentMediaTypesConstants.ImageJpeg,
+                HttpContentMediaTypes.ImageGif => HttpContentMediaTypesConstants.ImageGif,
+                HttpContentMediaTypes.AudioMpeg => HttpContentMediaTypesConstants.AudioMpeg,
+                HttpContentMediaTypes.AudioOgg => HttpContentMediaTypesConstants.AudioOgg,
+                HttpContentMediaTypes.VideoMp4 => HttpContentMediaTypesConstants.VideoMp4,
+                HttpContentMediaTypes.VideoOgg => HttpContentMediaTypesConstants.VideoOgg,
+                _ => throw new ArgumentOutOfRangeException(nameof(mediaType), mediaType, null)
+            };
+        }
+    }
+}

src/am.kon.packages.services.web-client-service/Extensions/HttpHeadersExtensions.cs

@@ -0,0 +1,39 @@
+using System.Collections.Generic;
+using System.Net.Http.Headers;
+
+namespace am.kon.packages.services.WebClientService.Extensions
+{
+    /// <summary>
+    /// Extension methods for <see cref="HttpHeaders"/>
+    /// </summary>
+    public static class HttpHeadersExtensions
+    {
+        /// <summary>
+        /// Copy all available headers from instance of <see cref="HttpHeaders"/> to new instance of <see cref="WebClientResponseHeaders"/>.
+        /// </summary>
+        /// <param name="headers">Instance of <see cref="HttpHeaders"/> to copy headers from.</param>
+        /// <returns>New instance of <see cref="WebClientResponseHeaders"/> with all available headers of instance of <see cref="HttpHeaders"/>.</returns>
+        public static WebClientResponseHeaders ToWebClientResponseHeaders(this HttpHeaders headers)
+        {
+            WebClientResponseHeaders newInstance = new WebClientResponseHeaders();
+
+            return ToWebClientResponseHeaders(headers, newInstance);
+        }
+
+        /// <summary>
+        /// Copy all available headers from instance of <see cref="HttpHeaders"/> to new instance of <see cref="WebClientResponseHeaders"/>.
+        /// </summary>
+        /// <param name="srcHeaders">Instance of <see cref="HttpHeaders"/> to copy headers from.</param>
+        /// <param name="dstHeaders">Instance of <see cref="WebClientResponseHeaders"/> to copy headers to.</param>
+        /// <returns>Instance of <see cref="WebClientResponseHeaders"/> with all available headers of instance of <see cref="HttpHeaders"/>.</returns>
+        public static WebClientResponseHeaders ToWebClientResponseHeaders(this HttpHeaders srcHeaders, WebClientResponseHeaders dstHeaders)
+        {
+            foreach (KeyValuePair<string,IEnumerable<string>> header in srcHeaders)
+            {
+                dstHeaders.TryAddWithoutValidation(header.Key, header.Value);
+            }
+
+            return dstHeaders;
+        }
+    }
+}

src/am.kon.packages.services.web-client-service/RequestInvocationResult.cs

@@ -2,36 +2,42 @@
 namespace am.kon.packages.services.WebClientService
 {
     /// <summary>
-    /// Object describing the result of http invocation
+    /// Object describing the result of an HTTP invocation.
     /// </summary>
 	public class RequestInvocationResult<TData>
 	{
         /// <summary>
-        /// Result of invocation
+        /// Result of the invocation.
         /// </summary>
         public RequestInvocationResultTypes Result { get; set; }
 
         /// <summary>
-        /// Data returned by invocation process.
-        /// In case of error during invocation this property will contain error message and additional data if there is some.
+        /// Data returned by the invocation process.
+        /// In case of an error during invocation, this property will contain the error message and additional data if available.
         /// </summary>
         public TData Data { get; set; }
 
         /// <summary>
-        /// Message describing request invocation result.
+        /// Message describing the request invocation result.
         /// </summary>
         /// <remarks>
-        /// If request has completed successfuly Message will be ampty string.
-        /// In case if some error will happen during communication with the server,
-        /// or server will return an error code, Message will contain data about that error.
+        /// If the request has completed successfully, Message will be an empty string.
+        /// In case of an error during communication with the server,
+        /// or if the server returns an error code, Message will contain data about that error.
         /// </remarks>
         public string Message { get; set; }
+
+        /// <summary>
+        /// Collection of headers returned from the server.
+        /// </summary>
+        public WebClientResponseHeaders Headers { get; set; }
 
         public RequestInvocationResult()
         {
             Result = RequestInvocationResultTypes.Unknown;
             Data = default(TData);
             Message = string.Empty;
+            Headers = new WebClientResponseHeaders();
         }
     }
 }

src/am.kon.packages.services.web-client-service/RequestInvocationResultTypes.cs

@@ -2,27 +2,27 @@
 namespace am.kon.packages.services.WebClientService
 {
     /// <summary>
-    /// Enum describing result type of http request invocation
+    /// Enum describing result type of HTTP request invocation.
     /// </summary>
 	public enum RequestInvocationResultTypes
 	{
         /// <summary>
-        /// Unknown result type
+        /// Unknown result type.
         /// </summary>
         Unknown = 0,
 
         /// <summary>
-        /// Invocation completed successful
+        /// Invocation completed successful.
         /// </summary>
         Ok = 1,
 
         /// <summary>
-        /// There was an error during invocation process
+        /// There was an error during the invocation process.
         /// </summary>
         ResponseError = 2,
 
         /// <summary>
-        /// There was some communication issue during invocation process
+        /// There was a communication issue during the invocation process.
         /// </summary>
         ConnectionError = 3
     }

src/am.kon.packages.services.web-client-service/WebClientResponseHeaders.cs

@@ -0,0 +1,13 @@
+using System.Collections.Generic;
+using System.Net.Http.Headers;
+
+namespace am.kon.packages.services.WebClientService
+{
+    /// <summary>
+    /// Collection of headers and their values returned from the server after a web client request.
+    /// </summary>
+    public class WebClientResponseHeaders : HttpHeaders
+    {
+
+    }
+}