doc

Author: bspeth-afk

Ev.ServiceBus.sln

@@ -24,6 +24,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{15791C07-7
 		docs\Ev.ServiceBus.HealthChecks.md = docs\Ev.ServiceBus.HealthChecks.md
 		docs\Ev.ServiceBus.Mvc.md = docs\Ev.ServiceBus.Mvc.md
 		docs\Instrumentation.md = docs\Instrumentation.md
+		docs\Isolation.md = docs\Isolation.md
 	EndProjectSection
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{8EC286EB-A71F-4431-ACA4-E92C79975817}"

README.md

@@ -40,6 +40,7 @@ across the whole system (name of the property : `PayloadTypeId`).
 * [Initial Set up](./docs/SetUp.md)
 * [How to send messages](./docs/SendMessages.md)
 * [How to receive messages](./docs/ReceiveMessages.md)
+* [Isolation Feature](./docs/Isolation.md)
 * [Advanced scenarios](./docs/AdvancedScenarios.md)
 * [Ev.ServiceBus.HealthChecks](./docs/Ev.ServiceBus.HealthChecks.md)
 * [Instrumentation](./docs/Instrumentation.md)

docs/AdvancedScenarios.md

@@ -201,21 +201,3 @@ public class MyMessageSender
             }
         }
 ```
-
-## Running service instance in isolation
-
-By "running in isolation" we mean ability to run an instance of microservice (MS) on local environment, when MS is using real queues and topics to communicate with other MSs
-Simple case : App1 sending message to App2, which responds back with another message.
-Desired isolation is in the following: If message comes from App1.Local, then the response to it should be processed also only by App1.Local. Same holds true from App1.Cloud - it should process responses that are only coming from cloud instances.
-
-This is achived by simply proper condifuration (see sample project)
-```csharp
-services.AddServiceBus(
-    settings =>
-    {
-        // Provide a connection string here !
-        settings.WithConnection("Endpoint=sb://yourconnection.servicebus.windows.net/;SharedAccessKeyName=yourkeyh;SharedAccessKey=ae6pTuOBAFDH2y7xJJf9BFubZGxXMToN6B9NiVgLnbQ=", new ServiceBusClientOptions());
-        settings.UseIsolation = true;
-        settings.IsolationKey = "your-isolation-key";
-    })
-```

docs/Isolation.md

@@ -0,0 +1,88 @@
+# Isolation feature
+
+## Concept
+
+In a microservice ecosystem where those services communicate through messages via Service bus queues or topics, some scenarios become difficult to debug.
+For example, sometimes you want to manually send a message to a queue and debug in local how your microservice behaves. That would require you to recreate a service bus namespace with the proper queue configured and link app running in local to it. 
+Another example is, sometimes you want to send a message to one microservice to see and debug how another microservice behaves down the line.
+
+The isolation feature allows your local application to connect to the service bus namespace of an up and running environment without disturbing it's stability.
+It then allows you to manually send messages with some metadata to that queue and you local application will receive it instead of the app running in the environment.
+
+## Configuration
+
+### Default configuration
+By default, the isolation feature is disabled. your application will treat every incoming messages.
+```csharp
+services.AddServiceBus(
+    settings =>
+    {
+        // Provide a connection string here !
+        settings.WithConnection("Endpoint=sb://yourconnection.servicebus.windows.net/;SharedAccessKeyName=yourkeyh;SharedAccessKey=ae6pTuOBAFDH2y7xJJf9BFubZGxXMToN6B9NiVgLnbQ=", new ServiceBusClientOptions());
+        settings.WithIsolation(IsolationBehavior.HandleAllMessages, null, null);    
+    })
+```
+
+### Environment configuration
+To use the feature, you need to activate isolation both on your local app and on your environment.
+
+Applications running in your environment must use the "HandleNonIsolatedMessages" behavior.
+You also need to provide a name for your microservice.
+
+```csharp
+services.AddServiceBus(
+    settings =>
+    {
+        // Provide a connection string here !
+        settings.WithConnection("Endpoint=sb://yourconnection.servicebus.windows.net/;SharedAccessKeyName=yourkeyh;SharedAccessKey=ae6pTuOBAFDH2y7xJJf9BFubZGxXMToN6B9NiVgLnbQ=", new ServiceBusClientOptions());
+        settings.WithIsolation(IsolationBehavior.HandleNonIsolatedMessages, null, "My.Application");    
+    })
+```
+
+### Local configuration
+To use the feature, you need to activate isolation both on your local app and on your environment.
+
+The Application running in local must use the "HandleIsolatedMessage" behavior.
+You also need to provide a name for your microservice and an isolation key.
+Your local application will only process messages that have the same isolation key as the one you provide.
+
+```csharp
+services.AddServiceBus(
+    settings =>
+    {
+        // Provide a connection string here !
+        settings.WithConnection("Endpoint=sb://yourconnection.servicebus.windows.net/;SharedAccessKeyName=yourkeyh;SharedAccessKey=ae6pTuOBAFDH2y7xJJf9BFubZGxXMToN6B9NiVgLnbQ=", new ServiceBusClientOptions());
+        settings.WithIsolation(IsolationBehavior.HandleIsolatedMessage, "My.IsolationKey", "My.Application");    
+    })
+```
+
+## Usage
+
+### Simple case
+Now to use the feature, you will need to send a message with the proper metadata to the queue/topic of your environment.
+
+Let's say you have a microservice `App1` and you want to run that application on local for debugging purposes.
+You will need to send a message to the queue/topic of `App1` with the following metadata:
+```json
+{
+    "IsolationKey": "My.IsolationKey",
+    "ApplicationName": "App1"
+}
+```
+Your local app will receive the message and process it.
+
+### Complex case
+Now let's say that in your environment you have the following microservices: `App1`, `App2`, `App3`, `App4`, `App5`.
+They communicate with each other through messages. 
+The entry point of your ecosystem is `App1`, but you want to debug `App2` and `App3` locally.
+
+You will need to send a message to the queue/topic of `App1` with the following metadata:
+```json
+{
+    "IsolationKey": "My.IsolationKey",
+    "ApplicationName": "App2,App3"
+}
+```
+The isolation metadata will be transferred to any message sent during the processing of the isolated message.
+
+Meaning that your local apps will be able to receive subsequent isolated messages allowing you to debug them.