I’m giving a NServiceBus tutorial at this years Norweigan Developers Conference (NDC). It’s going to be a lot of coding and hands on demos of what NServiceBus can do for you so please stop by!
Both me and Udi Dahan will be at NDC so we might have some surprises in store for you as well!
In this post I’ll go through the different options you have when it comes to migrating your 2.6 Timeouts to the new 3.0 format. For those of you that aren’t familiar with the NServiceBus timeouts the short explanation is that NServiceBus supports durable timeouts that survives process restarts. In order to do that we need to store the timeouts on disk. In 2.6 the default storage was a MSMQ queue but in 3.0 it’s RavenDB and this is why you might need to migrate. I say might because the actual timeout messages that gets sent over the wire is compatible between 2.6 and 3.0.1
Note: The reason that you need to be on NServiceBus 3.0.1 for this to work is that there was a bug in 3.0.0 that made the timeout incompatible. This is now fixed in 3.0.1
This means that you can run the 2.6 and 3.0.1 TimeoutManagers (TM) in parallel until there are no more 2.6 timeouts left and then decommission the 2.6 TM.
These are the steps you need to take if you plan to skip migration and run the TimeoutManagers side by side.
The fact that timeouts are durable means that they could and usually are set to a time far in the future. For example if you have insurances with long cycles you can have your renewal saga set to wake up in X years. In this situation you don’t want to run both timeout managers in parallel for that long time. This is when you would consider doing a migration instead. To do this we provide a tool, either in the zip download (/Tools/Migration/TimeoutMigrator.exe) or in the NServiceBus.Tools NuGet package.
This tool will extract your 2.6 Timeouts and send them over to the new 3.0 TM that will be responsible for managing them. Before I go through the steps we need to talk about those of you that require zero downtime deployments. The reason for this is that the 2.6.0.1504 doesn’t support hot migrations. This means that you need to upgrade to NServiceBus 2.6.0.1511 if you want to migrate your timeouts with your system still running. With that out of the way lets look at how you would use the tool to migrate.
1. Upgrade your endpoint to 3.0.1
2. Make sure to run the installers so that the dedicated input queue for the 3.0 TM gets created.
3. If you haven’t upgraded to 2.6.0.1511 you need to shutdown the 2.6 TM.
4. Run the TimeoutMigrator.exe. If you only want to migrate timeouts older than a specific time you can specify that using the -migrateOlderThan {minutes} switch. This will extract the timeouts and send them to the new 3.0 TM. The tool will ask you for the source and destination queues if not specified on the command line.
The command line switched are:
-storageQueue {name of the 2.6 storage queue}
-destination {name of the 3.0 TM input queue}
Typical settings would be:
-storageQueue Timeout.Storage
-destination {endpointName}.Timeouts
That’s all there is to it. Good luck!
In my talk about event design in service oriented architectures I dicussed how you should try to design your events so that they would only carry Id’s across service boundaries. Instead you would use use commands, which always are internal to a service, to store what ever data you need for each particular service and use the event to synchronize status changes across services. In essence this means that the only thing that is shared between services is the ID. This obviously also relates to how you design you entities. I’m not going into details here because Ayende has posted two excellent post on this subject. So please head over to his blog and read them:
http://ayende.com/blog/153703/there-ainrsquo-t-no-such-thing-the-definitive-entity-definition
http://ayende.com/blog/153704/composite-entities
As you see avoiding logical coupling between both events and entities is one of the most important things to think about when designing distributed systems that you don’t expect to rewrite from scratch every other year.
Finally this also shows why trying to design a “canonical data model” for your entire system is such a bad idea. Doing this will send you straight down the road of failure.
It’s been a long time waiting but today NServiceBus 3.0 was finally released. The team has been working pretty much full time with this release since the 2.6 release in June 2011 and I’m very pleased with the results even if it took a bit longer than we anticipated.
I’ve often got asked to rank my favorite new features and that’s always a though one. But if I have to pick one it would be the native support for RavenDB as our default storage. Using it for a while on both my own projects and customer projects I must say that the easy of use and the dramatic increase in productivity has been much better than I could hope for. Especially sagas are now so much easier to build and maintain without having the burden of the mappings and schema updates that came with the NHibernate persister in 2.X. Sagas has always been the nuclear weapon of NServiceBus and 3.0 takes all this to the next level.
For those of you that are upgrading from 2.X I’ve prepared a video that walks you through the upgrade process.
If you want to get your hands on 3.0.0 please head over to NServiceBus.com or pull it down using NuGet.
For those of you interested in training we’re already doing a 4-day course that will help you quickly get up to speed with NServiceBus 3.0.
I’m about to do some screen casts on NServiceBus and while getting familiar with Camtasia I recorded this short video explaining a better way to setup the NServiceBus.Host.exe within Visual Studio.
Hope you like it!
Last night I did a talk on event design in service oriented architectures with the abstract.
A common problem when designing service oriented architectures is that events going across services tend to be very large in terms of properties they carry. This has the negative effect of making development tougher, testing harder and deployment a risky operation.
In this talk, NServiceBus and Enterprise Software Expert Andreas Ohlund will analyse the checkout process of an online retailer to identify some of the misconceptions that lead to fat events. Finally we’ll look at techniques that will help you keep your events small and fit for the purpose thus mitigating the problems above.
The talk was recorded and can be found here:
http://skillsmatter.com/podcast/open-source-dot-net/events-diet
Profiles where introduced in NServiceBus 2.X so this is nothing that is new in 3.0. I’ve blogged about them a while ago but in short they are ways for you to alter the behavior of your endpoint without recompiling your code. This will help you tailor your endpoints for different environments but also controlling things like scaling out. Profiles are only available if you use the NServiceBus host so this is not applicable if you self host NServiceBus inside a website, wcf service, smart client, excel:) whatever.
Profiles can be divided into 2 main categories depending on what they control. Those categories are Environment and Feature. Environment profiles can often use Feature profiles to turn things on and off depending on the environment. Technically there is no difference between the two types.
NServiceBus comes with 3 builtin profiles who’s main goal is to adjust the behavioral of the host depending on the environment where the endpoint is running. You can of course create your own profiles, more on that later. The 3 environmental profiles are:
The feature related profiles that comes out of the box are:
To activate a specific profile just pass the full name of the profile on the commandline when starting the host. Type names are case insensitive. Profiles can be combine by separating them with a white space. So if you want your endpoint to run in the Integration and Master profiles you would use:
.\NServiceBus.Host.exe nservicebus.integration nservicebus.master
When you install the host as a windows service the profiles used when installing will be persisted and used every time the host starts. So if you want to install your host with the Production and the MultiSite profiles you would use:
.\NServiceBus.Host.exe /install nservicebus.production nservicebus.multisite
To define your own profiles you need to take the following steps:
The message pipeline in NServiceBus 2.X pretty much consisted of what we called message modules. They served their purpose but didn’t quite give you the full control over the message pipeline needed to do more advanced things. Another major shortcoming was that there was no way to hook into the pipeline at the sending/client side of the message conversation. When introducing the DataBus feature of NServiceBus 3.0 we came up with the notion of message mutators to solve a specific requirement to change the content of a message before and after sending it on the wire. The message mutators turned out to be a nice addition to our pipeline both in terms of their ability to change message content but also to serve as more fine grained hooks into the pipeline.
Lets take a look at how to use them!
We have 2 types of message mutators, one that operates on the applicative messages and another one that operates on the physical transport messages. Message mutators is used to change/react to individual messages being send or received. The IMessageMutator interface lets you implement hooks for both the sending side and the receiving side. If you only need one or the other you can implement one of the more fine grained IMutateOutgoingMessages or IMutateIncomingMessages. Reacting to individual messages can be used to perform things like validation of outgoing/incoming messages. A sample of this using data annotations to validate messages can be found in the MessageMutator sample included in the NServiceBus download. We use this type of mutator internally to do things like property encryption and serialization/de serialization of properties to and from the DataBus. The other type of mutator, Transport message mutators, are created by implementing the IMutateTransportMessages interface. As mentioned earlier this type of mutator works on the entire transport message and is useful for things like compression, header manipulation etc.
A full explanation of the syntax used can be found here. Remember that message mutators are NOT automatically registered in the container so in order for them to be invoked you need to register them in the container your self.
Just like the recommendation for headers, message mutators should only be used for infrastructure purposes. So as a rule of thumb only consider using message mutators so solve technical requirements.
If a server side (incoming) mutator throws a exception the message will be aborted, rolled back to the queue and retried. If a client side (outgoing) message mutator throws the exception will bubble up to the method calling bus.Send|Publish.
Hopefully this helped you understand what the message mutators are and how you can use the to bend the NServiceBus pipeline to your will.
Ok that was a confusing title:)
In NServiceBus we have 2 different types of messages and that usually confuses people. So lets take a look at the different types, what they should be used for and who should use them.
This is the type of message that most users think of when we talk about messages. This is the message that you as a users of the framework will define in order to send data from a client to a server. In NServiceBus this is either a C# class or interface inheriting from the IMessage marker interface and in 3.0 possibly defined by a convention instead. This is the message that you own version and control. Let’s call it a “message” going forwards. To send this message over the wire we need to serialize it to any of the supported formats, json, xml, protobuf etc. The serialized data is wrapped in an envelope that can be given the messaging system for store and forward transmission to its final destination. We call this a TransportMessage. You can send multiple of your applicative messages in the same go making them part of the same TransportMessage using the Bus.Send(object[] messages) signature.
This is the other of the message types and is owned, controlled and versioned by NServiceBus. If you have read the EAI patterns book this would roughly translate to a envelope wrapper. Other frameworks like Lokad.Cqrs just call them envelopes. The main purpose of this type of message is to carry the serialized payload across the wire but they also contains headers and infrastructure related information such as return address, time sent, id etc. TransportMessages is the physical unit that gets sent between a client and a server so If you look at messages in input queues, error or audit queues etc. it’s this kind of message you would see.
It’s very important to understand that the unit of work when it comes to message processing is the Transport Message (TM). When NServiceBus picks up a TM from the input queue a transaction is created and all message handlers for the contained messages (remember it could be more than one) will execute in this transaction. If no exception is thrown the transaction will commit and the message will be removed. If any handler throws an error NServiceBus will retry a configurable number of time and then send the entire TM to the configured error queue. Most of the time messages will relate 1-1 to TM’s but you can use this feature if you want messages to be processed a whole inside a single transaction.
You as a user can’t send transport messages without contained messages but NServiceBus sends empty transport messages internally to control things like subscriptions, worker registration for the distributor etc. We call this special type if message a “ControlMessage” and they only contain headers.
Hopefully this post has shed some light when it comes to the different types of messages used in the NServiceBus lingo.
In a previous post I talked about the different ways to make sure that you have a Raven server available in order for your NServiceBus endpoints to store their data. In this post we’ll look at the different options for connecting to that Raven server.
To tell NServiceBus to use Raven for persistence is a easy as calling Configure.RavenPersistence(). This is the default configuration and it uses the following conventions:
There are a few situations where the default behavior might not be good enough for you.
After connecting to a Raven server we need to decide which actual database to use. Unless we find a default database specified in the connection string NServiceBus will use the endpoint name as the database name. So if your endpoint is named “MyServer” the database name will be “MyServer”. Each endpoint will have a separate database unless you explicitly override using the connection string. RavenDB will automatically create the database if it doesn’t already exist.
A detailed explanation of the endpoint name concept can be found here.
No the Raven client is merged and internalized into the NServiceBus assemblies so if you want to use Raven for your own purposes you need to reference the Raven client and setup your own document store.
Just open a web browser and type the url if the Raven server, this will open up the Raven DB management studio.