sdks/dotnet/packages/NSubstitute.1.6.0.0/BreakingChanges.txt

# Licensed to the Apache Software Foundation (ASF) under one or more
# contributor license agreements.  See the NOTICE file distributed with
# this work for additional information regarding copyright ownership.
# The ASF licenses this file to You under the Apache License, Version 2.0
# (the "License"); you may not use this file except in compliance with
# the License.  You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

================================================================================================
1.5.0 Release
================================================================================================

The base object methods (Equals, GetHashCode and ToString) for substitute objects of classes that
extend those methods now return the result of calling the actual implementation of those methods
rather than the default value for the return type. This means that places where you relied on
.Equals returning false, .ToString returning null and .GetHashCode returning 0 because the actual
methods weren't called will now call the actual implementation.

Reason:
Substitute objects of classes that overrode those methods that were used as parameters for
setting up return values or checking received calls weren't able to be directly used within the
call, e.g. instead of:

someObject.SomeCall(aSubstitute).Returns(1);

You previously needed to have:

someObject.SomeCall(Arg.Is<TypeBeingSubstituted>(a => a == aSubstitute)).Returns(1);

However, now you can use the former, which is much more terse and consistent with the way other
Returns or Received calls work.

This means that substitute objects will now always work like .NET objects rather than being
inconsistent when the class being substituted overrode any of those base object methods.

Fix:
There is no workaround to change the behaviour of .Equals, .GetHashCode or .ToString. If you have
a use case to change the behaviour of these methods please lodge an issue at the NSubstitute
Github site.

------------------------------------------------------------------------------------------------

In rare cases the new `Returns()` and `ReturnsForAnyArgs()` overloads can cause compilation to fail due to the call being ambiguous (CS0121). 

Reason:
The new overloads allow a sequence of callbacks to be used for return values. A common example is return several values, then throwing an exception.

Fix:
Remove the ambiguity by explicitly casting the arguments types or by using lambda syntax.
e.g. sub.Call().Returns(x => null, x => null);

================================================================================================
1.4.0 Release
================================================================================================

Auto-substitute from substitutes of `Func` delegates (following the same rules as auto-subbing
for methods and properties). So the delegate returned from `Substitute.For<Func<IFoo>>()` will 
return a substitute of `IFoo`. This means some substitutes for delegates that used to return
null will now return a new substitute.

Reason:
Reduced setup when substituting for `Func` delegates, and consistency with behaviour for 
properties and methods. 

Fix:
Explicitly return null from substitute delegates when required for a test.
e.g. subFunc().Returns(x => null);


================================================================================================
1.2.0 Release
================================================================================================

Auto-substitute for pure virtual classes (in addition to interfaces and delegate types), which
means some methods and properties on substitutes that used to return null by default will now
return a new substitute of that type.

Reason:
Cut down the code required to configure substitute members that return interface-like types
(e.g. ASP.NET web abstractions like HttpContextBase) which are safe to create and proxy.

Safe classes are those with all their public methods and properties defined as virtual or 
abstract, and containing a default, parameterless constructor defined as public or protected.

Fix:
Explicitly return null from methods and property getters when required for a test.
e.g. sub.Method().Returns(x => null);


================================================================================================
0.9.5 Release
================================================================================================

Raise.Event<TEventArgs>(...) methods renamed to Raise.EventWith<TEventArgs()

Reason:
The Raise.Event<TEventArgs>() signature would often conflict with the
Raise.Event<THandler>() method which is used to raise all types of events.

Raise.Event<THandler>() will now always work for any event type, while
Raise.EventWith<TEventArgs>() can be used as a shortcut to raise
EventHandler-style events with a particular argument.

Fix:
Replace Raise.Event<TEventArgs>() calls with equivalent Raise.EventWith<TEventArgs>() call.

------------------------------------------------------------------------------------------------
Raise.Action() methods removed

Reason:
The Raise.Event<THandler>() method can be used to raise all delegate events, including Actions.
Raise.Action() was removed so there is a consistent way of raising all delegate events.

Fix:
- Replace Raise.Action() calls with Raise.Event<Action>().
- Replace Raise.Action<T>(T arg) calls with Raise.Event<Action<T>>(arg).
- Replace Raise.Action<T1,T2>(T1 x, T2 y) calls with Raise.Event<Action<T1,T2>>(x, y).


================================================================================================
0.9.0 Release
================================================================================================

No breaking changes.