From 81265498418dbf3416919ef97b928c2f8fd88ad9 Mon Sep 17 00:00:00 2001 From: Mark van Renswoude Date: Sat, 11 Feb 2017 21:32:30 +0100 Subject: [PATCH] Wrote some more documentation --- docs/conf.py | 2 +- docs/flow.rst | 11 +++++++ docs/gettingstarted.rst | 53 ++++++++++++++++++++++++++++++++-- docs/indepth.rst | 63 +++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 4 ++- 5 files changed, 128 insertions(+), 5 deletions(-) create mode 100644 docs/flow.rst create mode 100644 docs/indepth.rst diff --git a/docs/conf.py b/docs/conf.py index 3c38711..17d1913 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -155,4 +155,4 @@ texinfo_documents = [ ] - +highlight_language = 'csharp' \ No newline at end of file diff --git a/docs/flow.rst b/docs/flow.rst new file mode 100644 index 0000000..4b7c86b --- /dev/null +++ b/docs/flow.rst @@ -0,0 +1,11 @@ +Flow +==== + +.. error:: You've stumbled upon a piece of unfinished documentation. + Behind you is all prior knowledge. In front of you is nothing but emptyness. What do you do? + + 1. Attempt to explore further + 2. Complain to the author and demand your money back + 3. Abandon all hope + + > | diff --git a/docs/gettingstarted.rst b/docs/gettingstarted.rst index 34f736d..3677631 100644 --- a/docs/gettingstarted.rst +++ b/docs/gettingstarted.rst @@ -13,6 +13,55 @@ You will need an integration package as well for your IoC (Inversion of Control) Configuring Tapeti ------------------ +First create an instance of TapetiConfig, tell it which controllers to register and have it gather all the information by calling Build. Then pass the result to a TapetiConnection. + +:: + + using SimpleInjector; + using Tapeti; + + internal class Program + { + private static void Main() + { + var container = new Container(); + var config = new TapetiConfig(new SimpleInjectorDependencyResolver(container)) + .RegisterAllControllers() + .Build(); + + using (var connection = new TapetiConnection(config) + { + Params = new TapetiConnectionParams + { + Host = "localhost" + } + }) + { + connection.SubscribeSync(); + + // Start service + } + } + } + +.. note:: RegisterAllControllers without parameters searches the entry assembly. Pass an Assembly parameter to register other or additional controllers. + +.. caution:: Tapeti attempts to register it's default implementations in the IoC container during configuration, as well as when starting the connection (to register IPublisher). If your container is immutable after the initial configuration, like SimpleInjector is, make sure that you run the Tapeti configuration before requesting any instances from the container. + +Defining a message +------------------ +A message is a plain object which can be serialized using `Json.NET `_. + +:: + + public class SomethingHappenedMessage + { + public string Description { get; set; } + } + +Creating a message controller +----------------------------- + .. error:: You've stumbled upon a piece of unfinished documentation. Behind you is all prior knowledge. In front of you is nothing but emptyness. What do you do? @@ -20,6 +69,4 @@ Configuring Tapeti 2. Complain to the author and demand your money back 3. Abandon all hope - > | - -.. caution:: Tapeti attempts to register it's default implementations in the IoC container during configuration, as well as when starting the connection (to register IPublisher). If your container is immutable after the initial configuration, like SimpleInjector is, make sure that you run the Tapeti configuration before requesting any instances from the container. \ No newline at end of file + > | \ No newline at end of file diff --git a/docs/indepth.rst b/docs/indepth.rst new file mode 100644 index 0000000..cbca2d6 --- /dev/null +++ b/docs/indepth.rst @@ -0,0 +1,63 @@ +In-depth +======== + + +Messages +-------- +As described in the Getting started guide, a message is a plain object which can be serialized using `Json.NET `_. + +When communicating between services it is considered best practice to define messages in separate class library assemblies which can be referenced in other services. This establishes a public interface between services and components without binding to the implementation. + + +Routing keys +------------ +The routing key is determined by converting CamelCase to dot-separated lowercase, leaving out "Message" at the end if it is present. In the example below, the routing key will be "something.happened": + +:: + + public class SomethingHappenedMessage + { + public string Description { get; set; } + } + +This behaviour is implemented using the IRoutingKeyStrategy interface. For more information about changing this, see `Overriding default behaviour`_ + + + +Exchanges +--------- +The exchange on which the message is published and consumers are expected to bind to is determined by the first part of the namespace, skipping "Messaging" if it is present. In the example below, the exchange will be "Example": + +:: + + namespace Messaging.Example.Events + { + public class SomethingHappenedMessage + { + public string Description { get; set; } + } + } + +This behaviour is implemented using the IExchangeStrategy interface. For more information about changing this, see `Overriding default behaviour`_ + + + +Overriding default behaviour +---------------------------- +Various behaviours of Tapeti are implemented using interfaces which are resolved using the IoC container. Tapeti will attempt to register the default implementations, but these can easily be replaced with your own version. For example: + +:: + + // Nod to jsforcats.com + public class YellItRoutingKeyStrategy : IRoutingKeyStrategy + { + public string GetRoutingKey(Type messageType) + { + return messageType.Name.ToUpper() + "!!!!"; + } + } + + + container.Register(); + +The best place to register your implementation is before calling TapetiConfig. \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 47d4e9f..219c524 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,4 +6,6 @@ Tapeti documentation :caption: Contents: introduction - gettingstarted \ No newline at end of file + gettingstarted + indepth + flow \ No newline at end of file