feat: add docs, samples and enhancements

Author: BenjaminAbt

README.md

@@ -4,10 +4,10 @@ Parsing HTTP User Agents with .NET
 
 ## NuGet
 
-| NuGet |
-|-|
-| [![MyCSharp.HttpUserAgentParser](https://img.shields.io/nuget/v/MyCSharp.HttpUserAgentParser.svg?logo=nuget&label=MyCSharp.HttpUserAgentParser)](https://www.nuget.org/packages/MyCSharp.HttpUserAgentParser) |
-| [![MyCSharp.HttpUserAgentParser](https://img.shields.io/nuget/v/MyCSharp.HttpUserAgentParser.MemoryCache.svg?logo=nuget&label=MyCSharp.HttpUserAgentParser.MemoryCache)](https://www.nuget.org/packages/MyCSharp.HttpUserAgentParser.MemoryCache)| `dotnet add package MyCSharp.HttpUserAgentParser.MemoryCach.MemoryCache` |
+| NuGet | Install |
+|-|-|
+| [![MyCSharp.HttpUserAgentParser](https://img.shields.io/nuget/v/MyCSharp.HttpUserAgentParser.svg?logo=nuget&label=MyCSharp.HttpUserAgentParser)](https://www.nuget.org/packages/MyCSharp.HttpUserAgentParser) | `dotnet add package MyCSharp.HttpUserAgentParser` |
+| [![MyCSharp.HttpUserAgentParser.MemoryCache](https://img.shields.io/nuget/v/MyCSharp.HttpUserAgentParser.MemoryCache.svg?logo=nuget&label=MyCSharp.HttpUserAgentParser.MemoryCache)](https://www.nuget.org/packages/MyCSharp.HttpUserAgentParser.MemoryCache) | `dotnet add package MyCSharp.HttpUserAgentParser.MemoryCache` |
 | [![MyCSharp.HttpUserAgentParser.AspNetCore](https://img.shields.io/nuget/v/MyCSharp.HttpUserAgentParser.AspNetCore.svg?logo=nuget&label=MyCSharp.HttpUserAgentParser.AspNetCore)](https://www.nuget.org/packages/MyCSharp.HttpUserAgentParser.AspNetCore) | `dotnet add package MyCSharp.HttpUserAgentParser.AspNetCore` |
 
 
@@ -104,9 +104,9 @@ public void ConfigureServices(IServiceCollection services)
 Now you can use
 
 ```csharp
-public void MyMethod(IHttpUserAgentParserAccessor parserAccessor)
+public void MyMethod(IHttpUserAgentParserAccessor parserAccessor, HttpContext httpContext)
 {
-    HttpUserAgentInformation info = parserAccessor.Get();
+    HttpUserAgentInformation? info = parserAccessor.Get(httpContext);
 }
 ```
 
@@ -152,7 +152,7 @@ by [@BenjaminAbt](https://github.com/BenjaminAbt) and [@gfoidl](https://github.c
 
 MIT License
 
-Copyright (c) 2021-2025 MyCSharp 
+Copyright (c) 2021-2026 MyCSharp 
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

src/HttpUserAgentParser.AspNetCore/DependencyInjection/HttpUserAgentParserDependencyInjectionOptionsExtensions.cs

@@ -7,18 +7,24 @@
 namespace MyCSharp.HttpUserAgentParser.AspNetCore.DependencyInjection;
 
 /// <summary>
-/// Dependency injection extensions for ASP.NET Core environments
+/// Extension methods for <see cref="HttpUserAgentParserDependencyInjectionOptions"/> to add ASP.NET Core integration.
 /// </summary>
 public static class HttpUserAgentParserDependencyInjectionOptionsExtensions
 {
     /// <summary>
-    /// Registers <see cref="HttpUserAgentParserAccessor"/> as <see cref="IHttpUserAgentParserAccessor"/>.
-    ///  Requires a registered <see cref="IHttpUserAgentParserProvider"/>
+    /// Registers <see cref="HttpUserAgentParserAccessor"/> as a singleton implementation of <see cref="IHttpUserAgentParserAccessor"/>.
     /// </summary>
+    /// <param name="options">The options instance from the parser registration.</param>
+    /// <returns>The same options instance for method chaining.</returns>
+    /// <remarks>
+    /// Requires a registered <see cref="IHttpUserAgentParserProvider"/>.
+    /// Call this after <c>AddHttpUserAgentParser()</c> or <c>AddHttpUserAgentCachedParser()</c>.
+    /// </remarks>
     /// <example>
     /// <code>
     /// IServiceCollection services = new ServiceCollection();
-    /// services.AddHttpUserAgentParser().AddHttpUserAgentParserAccessor();
+    /// services.AddHttpUserAgentParser()
+    ///     .AddHttpUserAgentParserAccessor();
     /// </code>
     /// </example>
     public static HttpUserAgentParserDependencyInjectionOptions AddHttpUserAgentParserAccessor(

src/HttpUserAgentParser.AspNetCore/HttpContextExtensions.cs

@@ -6,16 +6,22 @@
 namespace MyCSharp.HttpUserAgentParser.AspNetCore;
 
 /// <summary>
-/// Static extensions for <see cref="HttpContext"/>
+/// Extension methods for <see cref="HttpContext"/> to access User-Agent information.
 /// </summary>
 public static class HttpContextExtensions
 {
     /// <summary>
-    /// Returns the User-Agent header value
+    /// Gets the User-Agent header value from the HTTP request.
     /// </summary>
+    /// <param name="httpContext">The HTTP context.</param>
+    /// <returns>The User-Agent string, or <see langword="null"/> if not present.</returns>
     /// <example>
     /// <code>
     /// string? userAgent = httpContext.GetUserAgentString();
+    /// if (userAgent != null)
+    /// {
+    ///     HttpUserAgentInformation info = HttpUserAgentParser.Parse(userAgent);
+    /// }
     /// </code>
     /// </example>
     public static string? GetUserAgentString(this HttpContext httpContext)

src/HttpUserAgentParser.AspNetCore/HttpUserAgentParserAccessor.cs

@@ -6,19 +6,19 @@
 namespace MyCSharp.HttpUserAgentParser.AspNetCore;
 
 /// <summary>
-/// User Agent parser accessor. Implements <see cref="IHttpContextAccessor.HttpContext"/>
+/// Default implementation of <see cref="IHttpUserAgentParserAccessor"/> for ASP.NET Core applications.
 /// </summary>
 /// <remarks>
-/// Creates a new instance of <see cref="HttpUserAgentParserAccessor"/>
+/// Extracts and parses the User-Agent header from HTTP requests.
+/// Register via <c>services.AddHttpUserAgentParser().AddHttpUserAgentParserAccessor()</c>.
 /// </remarks>
+/// <param name="httpUserAgentParser">The parser provider to use for parsing.</param>
 public class HttpUserAgentParserAccessor(IHttpUserAgentParserProvider httpUserAgentParser)
     : IHttpUserAgentParserAccessor
 {
     private readonly IHttpUserAgentParserProvider _httpUserAgentParser = httpUserAgentParser;
 
-    /// <summary>
-    /// User agent of current <see cref="IHttpContextAccessor"/>
-    /// </summary>
+    /// <inheritdoc/>
     /// <example>
     /// <code>
     /// string? userAgent = accessor.GetHttpContextUserAgent(httpContext);
@@ -27,12 +27,14 @@ public class HttpUserAgentParserAccessor(IHttpUserAgentParserProvider httpUserAg
     public string? GetHttpContextUserAgent(HttpContext httpContext)
         => httpContext.GetUserAgentString();
 
-    /// <summary>
-    /// Returns current <see cref="HttpUserAgentInformation"/> of current <see cref="IHttpContextAccessor"/>
-    /// </summary>
+    /// <inheritdoc/>
     /// <example>
     /// <code>
     /// HttpUserAgentInformation? info = accessor.Get(httpContext);
+    /// if (info != null)
+    /// {
+    ///     Console.WriteLine(info.Value.Name);
+    /// }
     /// </code>
     /// </example>
     public HttpUserAgentInformation? Get(HttpContext httpContext)

src/HttpUserAgentParser.AspNetCore/IHttpUserAgentParserAccessor.cs

@@ -5,17 +5,24 @@
 namespace MyCSharp.HttpUserAgentParser.AspNetCore;
 
 /// <summary>
-/// User Agent parser accessor
+/// Provides access to User-Agent parsing functionality within an ASP.NET Core context.
 /// </summary>
 public interface IHttpUserAgentParserAccessor
 {
     /// <summary>
-    /// User agent value
+    /// Gets the User-Agent header value from the specified HTTP context.
     /// </summary>
+    /// <param name="httpContext">The HTTP context to extract the User-Agent from.</param>
+    /// <returns>The User-Agent string, or <see langword="null"/> if not present.</returns>
     string? GetHttpContextUserAgent(HttpContext httpContext);
 
     /// <summary>
-    /// Returns current <see cref="HttpUserAgentInformation"/>
+    /// Parses the User-Agent from the specified HTTP context.
     /// </summary>
+    /// <param name="httpContext">The HTTP context to extract and parse the User-Agent from.</param>
+    /// <returns>
+    /// An <see cref="HttpUserAgentInformation"/> instance if the User-Agent header is present;
+    /// otherwise, <see langword="null"/>.
+    /// </returns>
     HttpUserAgentInformation? Get(HttpContext httpContext);
 }

src/HttpUserAgentParser.MemoryCache/DependencyInjection/HttpUserAgentParserMemoryCacheServiceCollectionExtensions.cs

@@ -7,20 +7,27 @@
 namespace MyCSharp.HttpUserAgentParser.MemoryCache.DependencyInjection;
 
 /// <summary>
-/// Dependency injection extensions for IMemoryCache
+/// Extension methods for registering <see cref="HttpUserAgentParserMemoryCachedProvider"/> with dependency injection.
 /// </summary>
 public static class HttpUserAgentParserMemoryCacheServiceCollectionExtensions
 {
     /// <summary>
-    /// Registers <see cref="HttpUserAgentParserCachedProvider"/> as singleton to <see cref="IHttpUserAgentParserProvider"/>
+    /// Registers <see cref="HttpUserAgentParserMemoryCachedProvider"/> as a singleton implementation of <see cref="IHttpUserAgentParserProvider"/>.
     /// </summary>
+    /// <param name="services">The service collection to add the services to.</param>
+    /// <param name="options">Optional action to configure the cache options.</param>
+    /// <returns>Options for further configuration.</returns>
+    /// <remarks>
+    /// <para>Default configuration: 256 entries maximum, 1 day sliding expiration.</para>
+    /// <para>Use the <paramref name="options"/> parameter to customize cache behavior.</para>
+    /// </remarks>
     /// <example>
     /// <code>
     /// IServiceCollection services = new ServiceCollection();
-    /// services.AddHttpUserAgentMemoryCachedParser(options =>
+    /// services.AddHttpUserAgentMemoryCachedParser(opts =>
     /// {
-    ///     options.CacheOptions.SizeLimit = 512;
-    ///     options.CacheEntryOptions.SlidingExpiration = TimeSpan.FromHours(6);
+    ///     opts.CacheOptions.SizeLimit = 512;
+    ///     opts.CacheEntryOptions.SlidingExpiration = TimeSpan.FromHours(6);
     /// });
     /// </code>
     /// </example>

src/HttpUserAgentParser.MemoryCache/HttpUserAgentParserMemoryCachedProvider.cs

@@ -5,18 +5,28 @@
 
 namespace MyCSharp.HttpUserAgentParser.MemoryCache;
 
-/// <inheritdoc/>
 /// <summary>
-/// Creates a new instance of <see cref="HttpUserAgentParserMemoryCachedProvider"/>.
+/// Implementation of <see cref="IHttpUserAgentParserProvider"/> with caching using <see cref="Microsoft.Extensions.Caching.Memory.MemoryCache"/>.
 /// </summary>
-/// <param name="options">The options used to set expiration and size limit</param>
+/// <remarks>
+/// <para>Provides sliding expiration and size limits for cached entries.</para>
+/// <para>Default configuration: 256 entries maximum, 1 day sliding expiration.</para>
+/// </remarks>
+/// <param name="options">The options controlling cache size and expiration.</param>
 public class HttpUserAgentParserMemoryCachedProvider(
     HttpUserAgentParserMemoryCachedProviderOptions options) : IHttpUserAgentParserProvider
 {
     private readonly Microsoft.Extensions.Caching.Memory.MemoryCache _memoryCache = new(options.CacheOptions);
     private readonly HttpUserAgentParserMemoryCachedProviderOptions _options = options;
 
     /// <inheritdoc/>
+    /// <example>
+    /// <code>
+    /// HttpUserAgentParserMemoryCachedProviderOptions options = new();
+    /// HttpUserAgentParserMemoryCachedProvider provider = new(options);
+    /// HttpUserAgentInformation info = provider.Parse("Mozilla/5.0 Chrome/90.0.4430.212");
+    /// </code>
+    /// </example>
     public HttpUserAgentInformation Parse(string userAgent)
     {
         CacheKey key = GetKey(userAgent);

src/HttpUserAgentParser.MemoryCache/HttpUserAgentParserMemoryCachedProviderOptions.cs

@@ -5,22 +5,24 @@
 namespace MyCSharp.HttpUserAgentParser.MemoryCache;
 
 /// <summary>
-/// Provider options for <see cref="HttpUserAgentParserMemoryCachedProvider"/>
+/// Configuration options for <see cref="HttpUserAgentParserMemoryCachedProvider"/>.
+/// </summary>
 /// <remarks>
-/// Default of <seealso cref="MemoryCacheOptions.SizeLimit"/> is 256.
-/// Default of <seealso cref="MemoryCacheEntryOptions.SlidingExpiration"/> is 1 day
+/// <para>Default <see cref="MemoryCacheOptions.SizeLimit"/>: 256 entries.</para>
+/// <para>Default <see cref="MemoryCacheEntryOptions.SlidingExpiration"/>: 1 day.</para>
 /// </remarks>
-/// </summary>
 public class HttpUserAgentParserMemoryCachedProviderOptions
 {
     /// <summary>
-    /// Cache options
+    /// Gets the memory cache configuration options.
     /// </summary>
+    /// <remarks>Controls size limits and compaction behavior.</remarks>
     public MemoryCacheOptions CacheOptions { get; }
 
     /// <summary>
-    /// Cache entry options
+    /// Gets the options applied to each cache entry.
     /// </summary>
+    /// <remarks>Controls sliding expiration for cached user agent information.</remarks>
     public MemoryCacheEntryOptions CacheEntryOptions { get; }
 
     /// <summary>

src/HttpUserAgentParser/DependencyInjection/HttpUserAgentParserDependencyInjectionOptions.cs

@@ -5,16 +5,18 @@
 namespace MyCSharp.HttpUserAgentParser.DependencyInjection;
 
 /// <summary>
-/// Options for dependency injection
+/// Configuration options returned by the dependency injection registration methods.
+/// Used for fluent configuration of additional features.
 /// </summary>
 /// <remarks>
-/// Creates a new instance of <see cref="HttpUserAgentParserDependencyInjectionOptions"/>
+/// This class provides access to the service collection for registering additional services
+/// such as telemetry or ASP.NET Core integrations.
 /// </remarks>
-/// <param name="services"></param>
+/// <param name="services">The service collection to configure.</param>
 public class HttpUserAgentParserDependencyInjectionOptions(IServiceCollection services)
 {
     /// <summary>
-    /// Services container
+    /// Gets the service collection being configured.
     /// </summary>
     public IServiceCollection Services { get; } = services;
 }

src/HttpUserAgentParser/DependencyInjection/HttpUserAgentParserServiceCollectionExtensions.cs

@@ -11,12 +11,14 @@ namespace MyCSharp.HttpUserAgentParser.DependencyInjection;
 public static class HttpUserAgentParserServiceCollectionExtensions
 {
     /// <summary>
-    /// Registers <see cref="HttpUserAgentParserDefaultProvider"/> as singleton to <see cref="IHttpUserAgentParserProvider"/>
+    /// Registers <see cref="HttpUserAgentParserDefaultProvider"/> as a singleton implementation of <see cref="IHttpUserAgentParserProvider"/>.
     /// </summary>
+    /// <param name="services">The service collection to add the services to.</param>
+    /// <returns>Options for further configuration.</returns>
     /// <example>
     /// <code>
     /// IServiceCollection services = new ServiceCollection();
-    /// services.AddHttpUserAgentParser();
+    /// HttpUserAgentParserDependencyInjectionOptions options = services.AddHttpUserAgentParser();
     /// </code>
     /// </example>
     public static HttpUserAgentParserDependencyInjectionOptions AddHttpUserAgentParser(
@@ -26,12 +28,18 @@ public static HttpUserAgentParserDependencyInjectionOptions AddHttpUserAgentPars
     }
 
     /// <summary>
-    /// Registers <see cref="HttpUserAgentParserCachedProvider"/> as singleton to <see cref="IHttpUserAgentParserProvider"/>
+    /// Registers <see cref="HttpUserAgentParserCachedProvider"/> as a singleton implementation of <see cref="IHttpUserAgentParserProvider"/>.
     /// </summary>
+    /// <param name="services">The service collection to add the services to.</param>
+    /// <returns>Options for further configuration.</returns>
+    /// <remarks>
+    /// This provider caches parsed results indefinitely using a <see cref="System.Collections.Concurrent.ConcurrentDictionary{TKey, TValue}"/>.
+    /// For expiration-based caching, use the MemoryCache package instead.
+    /// </remarks>
     /// <example>
     /// <code>
     /// IServiceCollection services = new ServiceCollection();
-    /// services.AddHttpUserAgentCachedParser();
+    /// HttpUserAgentParserDependencyInjectionOptions options = services.AddHttpUserAgentCachedParser();
     /// </code>
     /// </example>
     public static HttpUserAgentParserDependencyInjectionOptions AddHttpUserAgentCachedParser(
@@ -41,12 +49,16 @@ public static HttpUserAgentParserDependencyInjectionOptions AddHttpUserAgentCach
     }
 
     /// <summary>
-    /// Registers <typeparam name="TProvider"/> as singleton to <see cref="IHttpUserAgentParserProvider"/>
+    /// Registers a custom <see cref="IHttpUserAgentParserProvider"/> implementation as a singleton.
     /// </summary>
+    /// <typeparam name="TProvider">The provider type implementing <see cref="IHttpUserAgentParserProvider"/>.</typeparam>
+    /// <param name="services">The service collection to add the services to.</param>
+    /// <returns>Options for further configuration.</returns>
     /// <example>
     /// <code>
     /// IServiceCollection services = new ServiceCollection();
-    /// services.AddHttpUserAgentParser&lt;HttpUserAgentParserDefaultProvider&gt;();
+    /// HttpUserAgentParserDependencyInjectionOptions options = services
+    ///     .AddHttpUserAgentParser&lt;HttpUserAgentParserDefaultProvider&gt;();
     /// </code>
     /// </example>
     public static HttpUserAgentParserDependencyInjectionOptions AddHttpUserAgentParser<TProvider>(