Sequence Diagram - How to model C#-events?

[jjweis]

Hello.

Could anybody give me a hint how to model C#-events in a sequence diagram?

I have a Class ClassA that publishes an event MyEvent. Furthermore there is a class ClassB that subscribes to ClassA.MyEvent and handles it in the method HandleMyEvent.

I want to model in a sequence diagram the fact that an instance of ClassA raises MyEvent and an instance of ClassB handles this event in HandleMyEvent.

Up to now I achieve to express the "calling" of ClassB.HandleMyEvent, but this doesn't give me any information about the subscription of HandleMyEvent to ClassA.MyEvent.

Thank you.

Juergen Weis

[sargasso]

I want to model in a sequence diagram the fact that an instance of ClassA raises MyEvent and an instance of ClassB handles this event in HandleMyEvent.

In terms of a "sequence" in a sequence diagram this is not meaningful.  The raising and sinking of the events are disjoint.  I use message endpoint elements to indicate event fires, one for the raise and one for the sink, which I tend to model on separate diagrams. They render nicely as a black blob - syntactically "some skullduggery somewhere in the runtime is taking care of this".

... the subscription of HandleMyEvent to ClassA.MyEvent.

Not sure what you are trying to achive here.  Event subsrciption in C# is pretty trivial and again handled efficiently by the runtime.  Subscribing and unsubscribing doesn't seem to me to be something that would require sequence modelling??  Or is there some specific trickery you are trying to pull?
Putting that another way, hitching the handler routine to the delegate doesn't seem to me to imply a message passing at a critical point in the interaction between the objects.

hth
bruce

[«Midnight»]

To take this farther along...

You need to consider a few things in addition to the "subscription" you mention above:

• The event itself. This is often expressed in a state diagram. After all, the event should cause some kind of (state) transition to take place someplace. If not why expose the event at all? UML provdes specific elements to cover this, and these are available in EA.
  
• The trigger for the event. You might want to look at this in an activity diagram. The trigger is actually a kind of action, which (in an activity diagram) can be expressed as: do/^eventName... You could elaborate this further as an Action element if need be.
  
• You can express an event as a class (such as a C# delegate or eventhandler), as an operation (the handler routine within its an implementing class such as a Windows Form), or as a specialized variant of either of the above. Do what's best for your environment and the system you are modelling.

All that out of the way, let's get back to your sequence diagram...

Consider how you expect things to happen. Do you anticipate that the action of subscription will somehow lead (more or less directly) to the event being triggered? If so you will want to have a sequence diagram to cover this cause and event relationship between the participating entities. If not then a sequence diagram could be almost misleading. The sequence diagram does have a time axis, and this does state that some things happen before others (jsut as you would need to subscribe to an event before you could be notified). However, the sequence diagram is best used to show how a set of directly related actions will occur, and how the various entities are related during the time period when the actions are occurring.

Unless there is a fairly tight coupling between the subscription and events occurring you should reconsider the sequence diagram. For expample, if you declare your event handlers about the time that you create the various objects within your system, and then leave them to interact through the lifetime of the system, this indicates a relationship (as above) between the various entities, but not a specific sequence of action-reaction. Use state, activity, and class diagrams to illustrate the various relationships.

However, if you periodically subscribe and unsubscribe to events in the hope of catching them only when the time is right, then you might want to illustrate (both) these processes with sequence diagrams in addition to the State, Activity and structural viewpoints. Be aware that there is very little (if any) code that can be inferred from these diagrams that is not best shown in the others; if there is anything new here (in the sequences), you might want to revisit the others to see what details you missed there.

HTH, David

[jjweis]

Hello Bruce, hello David,

thank you very much for your long and detailed answers.

I think I should have been more specific in my question.

ClassA implements a hardware-component which receives messages/signals from the "outer world".  ClassA translates these messages/signals to the event MyEvent. ClassB is a kind of "listener" and invokes HandleMyEvent when the event MyEvent is raised.

I want to describe for some specific scenarios how a message/signal from the "outer world" enters into the software-system and it "spreads" out.  I want to show which objects are activated at what time and how they pass the information invoking the methods of other objects.

I think the Sequence Diagram is just  the appropriate instrument to accomplish that. In order to show the the connection  between the event ClassA.MyEvent and ClassB.HandleMyEvent I draw an arrow from an instance of ClassA to an instance of ClassB like ClassA would do a "normal" invocation of ClassB.HandleMyEvent. (When this arrow crosses a thread-boundary I mark it as asynchronous.) But this arrow gives me only part of what it's happening: The arrow tells me that ClassB.HandleMyEvent is invoked, but it doesn't tell me that the cause of the invocation was the firing of ClassA.MyEvent.

Do you think that there are more appropriate means in UML than the Sequence Diagram to represent what I want?

Juergen

[«Midnight»]

Consider a collaboration diagram as well. Still, the following might be useful.

UML provides a Signal entity (which is an asynchronous message sent between objects). Signals can be modelled just like classes, and can have an inheritance hierarchy, which could help you elsewhere.

Offhand I cannot remember if EA models signals in any level of detail. I do know that the (older at least) Unisys dialect of XMI contained considerable detail about signals and events (rather then just mentioning them in the DTD), but I have not tested EA in this area.

I gather (or at least I suspect) you are in a position where the actual event itself could have originated from anyplace. The consumer is not (necessarily) interested in where the event originated, but the audience for your model certainly is. Thus the need to show something.

This fits in fairly well with what I've said earlier. Perhaps you could consider a state diagram to provide a context for the event - showing what changes in the system when this event takes place. You might have several such diagrams if the events could originate from several different (types of) objects.

Remember that in a sequence diagram you can also have a thread showing states, and link transitiions to these. Each state should (of course) be modelled elsewhere and simply referenced in the sequence diagram.

You might however be in the position where the originator of the event could be any of several instances of a single class. This is a bit different. [An example of this is how .Net provides a "sender" parameter for each event, indicating the specific instance that raised the event). Although you probably should still model the event in some other diagram, what I've said above will not expose the information you need on a sequence diagram.

UML allows you to specify a message (in a sequence daigram) at several levels of granularity. Most of the time you simply have an arrow, perhaps with a name. Sometimes you will designate it, such as marking it as asynchronous (thus making it an event). You can also provide considerable detail. This is somewhat less common, so people are often unaware it can be done. In the case of a message (and thus an event) you can specify quite a bit. Here's how it might look:

predecessor guard-condition sequence-expression return-value := message-name argument-list

Perhaps you can find what you need in there someplace.

David