Add GetUserName method to ClaimsPrincipalExtensions

Introduce a new extension method `GetUserName` in the
`ClaimsPrincipalExtensions` class within the `EasyExtensions`
namespace. This method retrieves the user's name or unique
identifier by checking claims in the following order of
precedence: `ClaimTypes.Name`, "sub", and `ClaimTypes.NameIdentifier`.

Throw a `KeyNotFoundException` if none of these claims are found
and a `NullReferenceException` if the `user` parameter is null.

Include detailed XML documentation for the method, describing
its purpose, behavior, parameters, return value, and exceptions.

Author: bvdcode

Sources/EasyExtensions/Extensions/ClaimsPrincipalExtensions.cs

@@ -9,6 +9,44 @@ namespace EasyExtensions
     /// </summary>
     public static class ClaimsPrincipalExtensions
     {
+        /// <summary>
+        /// Retrieves the user name or unique identifier from the specified claims principal.
+        /// </summary>
+        /// <remarks>This method attempts to retrieve the user's name by first checking for a name claim
+        /// (<see cref="System.Security.Claims.ClaimTypes.Name"/>), then a subject claim ('sub'), and finally a name
+        /// identifier claim (<see cref="System.Security.Claims.ClaimTypes.NameIdentifier"/>). If none of these claims
+        /// are found, an exception is thrown.</remarks>
+        /// <param name="user">The claims principal from which to extract the user name. Cannot be null.</param>
+        /// <returns>A string containing the user's name, subject identifier ('sub'), or name identifier claim value, in that
+        /// order of precedence.</returns>
+        /// <exception cref="NullReferenceException">Thrown if the <paramref name="user"/> parameter is null.</exception>
+        /// <exception cref="KeyNotFoundException">Thrown if neither a name, subject ('sub'), nor name identifier claim is present in the claims principal.</exception>
+        public static string GetUserName(this ClaimsPrincipal? user)
+        {
+            if (user == null)
+            {
+                throw new NullReferenceException(nameof(user));
+            }
+            Claim? name = user.FindFirst(ClaimTypes.Name);
+            if (name != null)
+            {
+                return name.Value;
+            }
+            Claim? sub = user.FindFirst("sub");
+            if (sub != null)
+            {
+                return sub.Value;
+            }
+
+            Claim? nameIdentifier = user.FindFirst(ClaimTypes.NameIdentifier);
+            if (nameIdentifier != null)
+            {
+                return nameIdentifier.Value;
+            }
+
+            throw new KeyNotFoundException("'sub' or " + ClaimTypes.NameIdentifier);
+        }
+
         /// <summary>
         /// Attempts to extract the user's unique identifier from the specified claims principal.
         /// </summary>