Masstransit: Documentation for EndpointConvention

[lakario]

I stumbled across the EndpointConvention class while digging through sources. It's incredibly useful, and yet I see it is not documented anywhere; is there specific a reason for this, other than time?

[phatboyg]

It's not ready for prime time, and thus hasn't been documented. It's dark functionality at this point.

Now if you wanted to write some documentation about it...

[alexeyzimarev]

So after the last commit can we document it? I can write something.

[lakario]

@phatboyg I was messing around with this method of registering send endpoints and I ran into a bit of a challenge. It doesn't seem to understand type hierarchies, so registrations are matched only on exact type matches. Thus, I can't register a base type (i.e. ICommand) and then expect it to properly route a more specific derived message type. Furthermore, if I register ISomeCommand and then call _bus.Send(new SomeCommand()), it will try to route on the type SomeCommand and fail to select the convention for ISomeCommand. You must be explicit: _bus.Send<ISomeCommand>(new SomeCommand()).

For this to be _ready for prime time_, I think the functionality of the type matching needs to be expanded to respect derived types.

[phatboyg]

Which is why I said it wasn't ready! :)

Seriously good suggestions and ones that are easily implemented. An exact type match should have priority, but lacking an exact match would defer to the next closest type.

[lakario]

No problem, totally understand.

[phatboyg]

Implemented messages types will now be supported as well, in the next release :)

[lakario]

Thanks @phatboyg!

I built something rather handy which you may be able to benefit from. My implementation understands the "hierarchy" of interfaces such that the "most specific" message convention can be selected when registering multiple conventions. Thus, given conventions for both IBase and IDoUpdate, sending a DoUpdate : IDoUpdate message would select the IDoUpdate convention, over IBase. Also, with this implementation, if it encounters multiple conventions at the same ancestor level _with unique URIs_, it will throw an exception, rather than produce a non-deterministic route.

Here's you go: https://gist.github.com/lakario/b9d73099e453c1832fc3638ff397f29a.

[phatboyg]

Complicated!

I think the message type check does the same thing without the ambiguity check, which is what I'm doing now. It checks at each level using the same approach to finding messages types on the most derived type.

[lakario]

I may have over-engineered my implementation.... just a little. =)

[alexeyzimarev]

Is there anything more to document than EndpointConvention.Map<TMessage>(Uri uri)? I use it, can write a page.

[phatboyg]

Not really, I'm replacing almost everything related to this with the topology/routing/policy features I'm working on in the topology branch.

[alexeyzimarev]

So I am really to early to use it or you keep the convention mapping as well?

[phatboyg]

I'm sure it will remain for a while, even after the new stuff is introduced, but it will be replaced by a well documentation system for defining the topology (how the broker is configured, and how features like routing keys and partition keys are applied from messages), routing (for commands and non-published types), and policy (for dealing with availability issues, rerouting traffic, etc. based upon application conditions.

[alexeyzimarev]

Wow, that's a lot!

[phatboyg]

It's a big effort for sure, and topology will launch first, quickly followed by routing and policy.

[ericgreenmix]

Is there any update on these new features? I am at a place where I need to use the EndpointConvention.Map but I am not sure if this is still the only (or best) way to register the Conventions?

[alexeyzimarev]

New functionality is not released yet.

[dimachado]

The ScheduleSend api will also take advantage of this endpoint convention? It will also be usefull to allow to configure destination address for scheduled commands.

[alexeyzimarev]

@phatboyg Do you still plan to change the send address conventions API with the new routing? I can document what we have at the moment.

[phatboyg]

If you could document what we have that would be great. It will be backwards compatible.