Improve error handling for duplicate display names (#3091)

Wrap SingleOrDefault by display name in try-catch to handle cases where
multiple target users share the same display name. Log detailed error
and warning messages, including a suggestion to enable MatchUsersByEmail
and a list of matching users, before rethrowing the exception for better
diagnostics.

Fix for #3090

Author: MrHinsh

src/MigrationTools.Clients.TfsObjectModel/Tools/TfsUserMappingTool.cs

@@ -190,7 +190,21 @@ public IdentityMapResult GetUsersInSourceMappedToTarget(TfsProcessor processor)
                             targetUser = candidates[0];
                         }
                     }
-                    targetUser ??= targetUsers.SingleOrDefault(x => x.DisplayName == sourceUser.DisplayName);
+                    try
+                    {
+                        targetUser ??= targetUsers.SingleOrDefault(x => x.DisplayName == sourceUser.DisplayName);
+                    }
+                    catch (InvalidOperationException)
+                    {
+                        Log.LogError("TfsUserMappingTool::GetUsersInSourceMappedToTarget:: Multiple target users found with the same display name '{displayName}'. "
+                            + "Consider enabling MatchUsersByEmail option to avoid this issue. ", 
+                            sourceUser.DisplayName, sourceUser.AccountName);
+                        var matchingUsers = targetUsers.Where(x => x.DisplayName == sourceUser.DisplayName).ToList();
+                        Log.LogWarning("TfsUserMappingTool::GetUsersInSourceMappedToTarget:: The list of matching users is {matchingUsers}",
+                            string.Join(", ", matchingUsers.Select(x => $"{x.DisplayName} [{x.MailAddress}]")));
+                        throw;
+                    }
+                    
                     identityMap.Add(new IdentityMapData { Source = sourceUser, Target = targetUser });
                 }
                 return new()