Add For/Exclude to allow exclusion of members inside a collection

[whymatter]

Closes #1771

IMPORTANT

• The code complies with the Coding Guidelines for C#.
• The changes are covered by a new or existing set of unit tests which follow the Arrange-Act-Assert syntax such as is used in this example.
• If the contribution adds a feature or fixes a bug, please update the release notes, which are published on the website.
• If the contribution changes the public API the changes needs to be included by running AcceptApiChanges.ps1/AcceptApiChanges.sh.
• If the contribution affects the documentation, please include your changes in this pull request so the documentation will appear on the website.

[whymatter]

@dennisdoomen I still have to do the release notes, however, you can already have a look at the ThenExcluding implementation. Unit tests are all green.

[dennisdoomen]

I recommend waiting with the rebase until #1789 is merged because it requires moving the tests to a new file.

[dennisdoomen]

🤔 To align with the new WithMapping options, I think we should use [] for that.

[whymatter]

Please see this comment #1782 (comment)

[whymatter]

Done 🙂

[whymatter]

Hi, sorry I was offline for a few days, looking forward to fix the issues next week :)

[whymatter]

Updated the documentation and release notes, ran AcceptApiChanges.ps1 :)

[jnyrup]

I tried to play a bit with this, but encountered something that seems a bit non-intuitive to me.

This passes as Collection is excluded from the equivalence

var subject = new { Member = "1", Collection = new[] { new { First = "A", Second = "B" } } };
var expected = new { Member = "1", Collection = new[] { new { First = "C", Second = "D" } } };

subject.Should().BeEquivalentTo(expected, opt => opt
    .Excluding(e => e.Collection));

Adding .ThenExcluding(e => e.Second) makes it fail as now only Collection.Second is excluded.

var subject = new { Member = "1", Collection = new[] { new { First = "A", Second = "B" } } };
var expected = new { Member = "1", Collection = new[] { new { First = "C", Second = "D" } } };

subject.Should().BeEquivalentTo(expected, opt => opt
    .Excluding(e => e.Collection).ThenExcluding(e => e.Second));

So the equivalency engine in fact includes Collection except its property Second.

I don't think the analogy of Include and ThenInclude from EF is completely translatable and invertible to Exclude and ThenExclude.
With ThenInclude you include something extra in addition to what's being included by Include.
If you have excluded something with Exclude, there's nothing left for ThenExclude to exclude.

I think e.g. combining Including with ThenExcluding comes closer to what's happening.

subject.Should().BeEquivalentTo(expected, opt => opt
    .Including(e => e.Collection).ThenExcluding(e => e.Second));

[whymatter]

I see that Including followed by ThenExcluding is also an interesting case and I think we need it as well.
However, my intention was to help people using Excluding (like this guy #500).
If one has existing assertions that use Excluding and want to add attributes in nested collections and exclude them, it would be a pain to rewrite all test to use Including.