From aab45b136d7525773a248306c8aaa7c27e1c7361 Mon Sep 17 00:00:00 2001
From: Robin-Manuel Thiel <robin-manuel@thiel1.de>
Date: Wed, 19 Jul 2023 15:09:02 +0200
Subject: [PATCH] Update 04-queries.md

---
 docs/public/docs-general/04-queries.md | 135 +++++++++++++------------
 1 file changed, 70 insertions(+), 65 deletions(-)

diff --git a/docs/public/docs-general/04-queries.md b/docs/public/docs-general/04-queries.md
index 362f8c0..9f96cf7 100644
--- a/docs/public/docs-general/04-queries.md
+++ b/docs/public/docs-general/04-queries.md
@@ -4,72 +4,9 @@
 
 TBD...
 
-### Hello world sample
+## Principles
 
-In this little sample of `Wemogy.CQRS` we will implement a query without parameters with the belonging query handler. Moreover we will register `wemogy.CQRS` in the dependency injection and finally execute the query to get a `Hello World!` string back.
-
-#### The Query model
-
-For each query its required to create a model of the query itself, which contains all information which are required to execute the query.
-
-```csharp
-using Wemogy.CQRS.Queries.Abstractions;
-
-public class HelloWorldQuery : IQuery<string>
-{
-}
-```
-
-#### The Query handler
-
-The second mandatory implementation for a query is a query handler, which contains the actual implementation of the query action.
-
-```csharp
-using System.Threading.Tasks;
-using Wemogy.CQRS.Queries.Abstractions;
-
-public class HelloWorldQueryHandler : IQueryHandler<HelloWorldQuery, string>
-{
-  public Task<string> HandleAsync(HelloWorldQuery query)
-  {
-    return "Hello world!";
-  }
-}
-```
-
-#### Registering the query
-
-It's required to execute `services.AddCQRS();` in your dependency injection file of the assembly which contains the queries. In addition its also supported to pass one or multiple assemblies to the `AddCQRS()` extension method, in case that you need to call it from another assembly.
-
-#### Executing the query
-
-This sample is part of a .NET Core controller class.
-
-```csharp
-using Wemogy.CQRS.Queries.Abstractions;
-
-public class HelloWorldController : ControllerBase
-{
-  private readonly IQueries _queries;
-
-  public HelloWorldController(IQueries queries)
-  {
-    _queries = queries;
-  }
-
-  [HttpGet]
-  public async Task<ActionResult> SayHelloWorld()
-  {
-    // creating the query with all required information
-    var helloWorldQuery = new HelloWorldQuery();
-
-    // executing the query though the IQueries mediator
-    var result = await _queries.QueryAsync(helloWorldQuery);
-
-    return Ok(result);
-  }
-}
-```
+- A Query should always only work exactly one way and not support multiple constuctors or execution ways (ref [GitHub Issue](https://github.com/wemogy/libs-cqrs/issues/51))
 
 ## Query definition
 
@@ -140,6 +77,74 @@ If your query internally talks to a `IDatabaseRepository` service, it's recommen
 
 If your query internally talks to an external API or any other custom data source and you need to filter the results based on the current context, it's recommended to implement this filtering logic in the wrapper implementation of the specific data source.
 
+
+## Example: Hello world
+
+In this little sample of `Wemogy.CQRS` we will implement a query without parameters with the belonging query handler. Moreover we will register `wemogy.CQRS` in the dependency injection and finally execute the query to get a `Hello World!` string back.
+
+### The Query model
+
+For each query its required to create a model of the query itself, which contains all information which are required to execute the query.
+
+```csharp
+using Wemogy.CQRS.Queries.Abstractions;
+
+public class HelloWorldQuery : IQuery<string>
+{
+}
+```
+
+### The Query handler
+
+The second mandatory implementation for a query is a query handler, which contains the actual implementation of the query action.
+
+```csharp
+using System.Threading.Tasks;
+using Wemogy.CQRS.Queries.Abstractions;
+
+public class HelloWorldQueryHandler : IQueryHandler<HelloWorldQuery, string>
+{
+  public Task<string> HandleAsync(HelloWorldQuery query)
+  {
+    return "Hello world!";
+  }
+}
+```
+
+### Registering the query
+
+It's required to execute `services.AddCQRS();` in your dependency injection file of the assembly which contains the queries. In addition its also supported to pass one or multiple assemblies to the `AddCQRS()` extension method, in case that you need to call it from another assembly.
+
+### Executing the query
+
+This sample is part of a .NET Core controller class.
+
+```csharp
+using Wemogy.CQRS.Queries.Abstractions;
+
+public class HelloWorldController : ControllerBase
+{
+  private readonly IQueries _queries;
+
+  public HelloWorldController(IQueries queries)
+  {
+    _queries = queries;
+  }
+
+  [HttpGet]
+  public async Task<ActionResult> SayHelloWorld()
+  {
+    // creating the query with all required information
+    var helloWorldQuery = new HelloWorldQuery();
+
+    // executing the query though the IQueries mediator
+    var result = await _queries.QueryAsync(helloWorldQuery);
+
+    return Ok(result);
+  }
+}
+```
+
 ## FAQ
 
 ### How to allow query executing only for specific context?