Changes Assert.Equals from throwing an exception to being marked as obsolete, and adds a new obsolete Assert.ReferenceEquals method. This prevents silent failures that would occur if these methods were removed entirely.

Problem

The original plan was to remove Assert.Equals in v4, but this would create a dangerous scenario:

// If Assert.Equals is removed, this code would silently call object.Equals()
// and never actually assert anything - a silent test failure!
Assert.Equals(expected, actual); // Falls back to object.Equals() - no assertion!

Solution

Instead of removal, both methods are now marked with [Obsolete] attributes:

• Assert.Equals: Now obsolete instead of throwing Assert.Fail()
• Assert.ReferenceEquals: New obsolete method to prevent similar issues

Both methods consistently return false and guide users to proper alternatives:

• Assert.Equals → Use Assert.AreEqual and overloads
• Assert.ReferenceEquals → Use Assert.AreSame and overloads

Implementation Details

• ✅ Modified Assert.Equals with [Obsolete] attribute
• ✅ Added new Assert.ReferenceEquals with [Obsolete] attribute
• ✅ Added DoNotUseAssertReferenceEquals resource string with full localization (13 languages)
• ✅ Updated PublicAPI.Unshipped.txt for new method
• ✅ Added unit tests to verify obsolete behavior
• ✅ Updated XML documentation

Testing

#pragma warning disable CS0618 // Type or member is obsolete
bool result1 = Assert.Equals("test", "test");        // Returns false, shows obsolete warning
bool result2 = Assert.ReferenceEquals(obj, obj);     // Returns false, shows obsolete warning  
#pragma warning restore CS0618 // Type or member is obsolete

This approach provides compile-time warnings while preventing the dangerous silent failure scenario.

Fixes #5758.

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.