Breaking changes to event raising in next release

[David Tchepak]

Just wanted to give people some warning about a breaking change that
has just made it into the master repo.

Short version: http://bit.ly/awkr3k [BreakingChanges.txt on Github]

Long version:

We have had some (quite understandable) confusion around raising
events declared as delegates that do not inherit from EventHandler or
EventHandler<T>. A good example of this type of event is in
INotifyPropertyChanged (mentioned on the list recently: http://bit.ly/aXAnjz).
To help fix this we've now got a breaking change to the syntax to
hopefully provide a more obvious way of raising all event types.

You have always been able to raise a delegate type of the event by
calling Raise.Event<THandler>(params object[] arguments) like this:

sub.PropertyChanged +=
Raise.Event<PropertyChangedEventHandler>(this, new
PropertyChangedEventArgs("test"));

Unfortunately this signature can be confusing to find and use because
it can conflict with the Raise.Event<TEventArgs>() methods used to
raise the standard EventHandler-style events.

To fix this, Raise.Event<TEventArgs>(...) methods have been renamed to
Raise.EventWith<TEventArgs>(...). If you get some compile errors about
incompatible types after building from source or when using the next
release of NSubstitute, you may need to go through your code and
replace some Raise.Event(...) calls with calls to
Raise.EventWith(...).

The intention is that you can use Raise.Event<THandler>() to raise any
event, but if you want a shortcut syntax to raise an EventHandler-
style event with particular arguments, you can use
Raise.EventWith<TEventArgs>().

Which brings us to the second breaking change. As we have the ability
to raise all kinds of events from Raise.Event<THandler>(), the
Raise.Action() methods are somewhat superfluous. Worse, they can
become a source of confusion if you are used to Raise.Action() and are
looking for a Raise.Func() or trying to raise an Action event with
more than 3 args. So we've removed Raise.Action() methods in favour of
Raise.Event<Action>(). Again, to fix this in your codebase you will
need to rename any Raise.Action() calls you have with the equivalent
Raise.Event<Action>() call.

I apologise for the inconvenience this will cause. We don't make
breaking changes lightly, but we felt it worth doing in this case to
get a solid API that handles all event types in a consistent way prior
to a v1.0 release.

If you have any feedback on this change (or need help making the
changes), please post to the list or email me directly.

Regards,
David

[Richard Banks]

Sounds good to me.

--
You received this message because you are subscribed to the Google Groups "NSubstitute" group.
To post to this group, send email to nsubs...@googlegroups.com.
To unsubscribe from this group, send email to nsubstitute...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/nsubstitute?hl=en.

--
- Richard Banks (@rbanks54)
blog: http://www.richard-banks.org
podcast: http://www.talkingshopdownunder.com