Added Getting Started section with sample (#133)

* Refactored sample * Added TransactionalBox.Sample.WebApi.InMemory * Added Getting Started section in docs * Refactored sample for learning
adimiko · Apr 8, 2024 · 24d3de3 · 24d3de3
1 parent 980c69e
commit 24d3de3
Show file tree

Hide file tree

Showing 13 changed files with 313 additions and 9 deletions.
diff --git a/TransactionalBox.sln b/TransactionalBox.sln
@@ -95,6 +95,8 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "TransactionalBox.InboxWorke
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "TransactionalBox.Inbox.Storage.InMemory", "source\TransactionalBox.Inbox.Storage.InMemory\TransactionalBox.Inbox.Storage.InMemory.csproj", "{1BF21145-4651-40BD-897A-0CDFB2913FA6}"
 EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "TransactionalBox.Sample.WebApi.InMemory", "samples\TransactionalBox.Sample.WebApi.InMemory\TransactionalBox.Sample.WebApi.InMemory.csproj", "{5C2EB157-F976-42F9-8B26-42A50898714C}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -273,6 +275,10 @@ Global
 		{1BF21145-4651-40BD-897A-0CDFB2913FA6}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{1BF21145-4651-40BD-897A-0CDFB2913FA6}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{1BF21145-4651-40BD-897A-0CDFB2913FA6}.Release|Any CPU.Build.0 = Release|Any CPU
+		{5C2EB157-F976-42F9-8B26-42A50898714C}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{5C2EB157-F976-42F9-8B26-42A50898714C}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{5C2EB157-F976-42F9-8B26-42A50898714C}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{5C2EB157-F976-42F9-8B26-42A50898714C}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -321,6 +327,7 @@ Global
 		{F1A53222-8BB9-45A7-8DC6-3050E1908C87} = {8FC46C4A-3C0C-458F-ACF5-F35F728A2988}
 		{AC95B0C2-49E0-4A20-AF37-447D1ECA96AC} = {8FC46C4A-3C0C-458F-ACF5-F35F728A2988}
 		{1BF21145-4651-40BD-897A-0CDFB2913FA6} = {8FC46C4A-3C0C-458F-ACF5-F35F728A2988}
+		{5C2EB157-F976-42F9-8B26-42A50898714C} = {D018E603-5AE9-4B1B-BF33-04EB0B5D6913}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {2D01E2B0-80D8-4BCE-BE98-29AC821F4F2B}

diff --git a/documentation/docs/getting-started.md b/documentation/docs/getting-started.md
@@ -4,8 +4,105 @@ sidebar_position: 2
 
 # Getting Started
 
-Let's discover **TransactionalBox in less than 5 minutes**.
+Let's discover **TransactionalBox in less than 5 minutes**.   
+Don't worry about the number of packages and if you don't understand something. I will try to introduce you step by step to the transactional box.
 
-## Installation
+## Configuration
+### Install packages
+```csharp
+dotnet add package TransactionalBox.Outbox.Storage.InMemory
+dotnet add package TransactionalBox.OutboxWorker.Storage.InMemory
+dotnet add package TransactionalBox.OutboxWorker.Transport.InMemory
+dotnet add package TransactionalBox.InboxWorker.Transport.InMemory
+dotnet add package TransactionalBox.InboxWorker.Storage.InMemory
+dotnet add package TransactionalBox.Inbox.Storage.InMemory
+```
+### Register
+```csharp
+using TransactionalBox;
+using TransactionalBox.Outbox;
+using TransactionalBox.Outbox.Storage.InMemory;
+using TransactionalBox.OutboxWorker;
+using TransactionalBox.OutboxWorker.Storage.InMemory;
+using TransactionalBox.OutboxWorker.Transport.InMemory;
+using TransactionalBox.InboxWorker;
+using TransactionalBox.InboxWorker.Transport.InMemory;
+using TransactionalBox.InboxWorker.Storage.InMemory;
+using TransactionalBox.Inbox;
+using TransactionalBox.Inbox.Storage.InMemory;
+```
 
-TODO Examples
+```csharp
+builder.Services.AddTransactionalBox(x =>
+{
+    x.AddOutbox(storage => storage.UseInMemory())
+     .WithWorker(
+        storage => storage.UseInMemory(),
+        transport => transport.UseInMemory());
+
+    x.AddInbox(storage => storage.UseInMemory())
+     .WithWorker(
+        storage => storage.UseInMemory(),
+        transport => transport.UseInMemory());
+},
+settings => settings.ServiceId = "ServiceName");
+```
+## Usage
+### Outbox
+#### Declare outbox message
+```csharp
+public sealed class ExampleMessage : IOutboxMessage
+{
+    public string Name { get; init; }
+
+    public int Age { get; init; }
+}
+```
+#### Add message to outbox (to send)
+
+```csharp
+public sealed class AddMessageToOutbox
+{
+    private readonly IOutbox _outbox;
+
+    public AddMessageToOutbox(IOutbox outbox) 
+    {
+        _outbox = outbox;
+    }
+
+    public async Task Example()
+    {
+        var message = new ExampleMessage()
+        {
+            Name = "Name",
+            Age = 25,
+        };
+
+        await _outbox.Add(message, envelope => envelope.Receiver = "ServiceName");
+    }
+}
+```
+
+### Inbox
+#### Declare inbox message
+```csharp
+public sealed class ExampleMessage : IInboxMessage
+{
+    public string Name { get; init; }
+
+    public int Age { get; init; }
+}
+```
+#### Handle message
+
+```csharp
+internal sealed class ExampleMessageHandler : IInboxMessageHandler<ExampleMessage>
+{
+    public async Task Handle(ExampleMessage message, IExecutionContext executionContext)
+    {
+        // Your Logic
+    }
+}
+```
+## Summary
+Follow the workflow of your code with breakpoints. Enjoy learning :stuck_out_tongue_winking_eye:.
diff --git a/samples/TransactionalBox.Sample.WebApi.InMemory/Program.cs b/samples/TransactionalBox.Sample.WebApi.InMemory/Program.cs
@@ -0,0 +1,56 @@
+using TransactionalBox;
+using TransactionalBox.Outbox;
+using TransactionalBox.Outbox.Storage.InMemory;
+using TransactionalBox.OutboxWorker;
+using TransactionalBox.OutboxWorker.Storage.InMemory;
+using TransactionalBox.OutboxWorker.Transport.InMemory;
+using TransactionalBox.InboxWorker;
+using TransactionalBox.InboxWorker.Transport.InMemory;
+using TransactionalBox.InboxWorker.Storage.InMemory;
+using TransactionalBox.Inbox;
+using TransactionalBox.Inbox.Storage.InMemory;
+using TransactionalBox.Base.Inbox.Storage.InMemory;
+using TransactionalBox.Base.Outbox.Storage.InMemory;
+using Microsoft.AspNetCore.Mvc;
+using TransactionalBox.Sample.WebApi.InMemory.ServiceWithOutbox;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddEndpointsApiExplorer();
+builder.Services.AddSwaggerGen();
+builder.Services.AddScoped<ExampleServiceWithOutbox>();
+
+builder.Services.AddTransactionalBox(x =>
+{
+    x.AddOutbox(storage => storage.UseInMemory())
+     .WithWorker(
+        storage => storage.UseInMemory(),
+        transport => transport.UseInMemory());
+
+    x.AddInbox(storage => storage.UseInMemory())
+     .WithWorker(
+        storage => storage.UseInMemory(),
+        transport => transport.UseInMemory());
+},
+settings => settings.ServiceId = "ServiceName");
+
+var app = builder.Build();
+
+// Configure the HTTP request pipeline.
+if (app.Environment.IsDevelopment())
+{
+    app.UseSwagger();
+    app.UseSwaggerUI();
+}
+
+app.UseHttpsRedirection();
+
+app.MapPost("/add-message-to-outbox", async (ExampleServiceWithOutbox exampleServiceWithOutbox) => await exampleServiceWithOutbox.Execute());
+
+app.MapGet("/get-messages-from-outbox", async (IOutboxStorageReadOnly outboxStorageReadOnly) => outboxStorageReadOnly.OutboxMessages);
+
+app.MapGet("/get-messages-from-inbox", async (IInboxStorageReadOnly inboxStorage) => inboxStorage.InboxMessages);
+
+app.MapGet("/get-idempotent-messages-from-inbox", async (IInboxStorageReadOnly inboxStorage) => inboxStorage.IdempotentInboxKeys);
+
+app.Run();
diff --git a/samples/TransactionalBox.Sample.WebApi.InMemory/Properties/launchSettings.json b/samples/TransactionalBox.Sample.WebApi.InMemory/Properties/launchSettings.json
@@ -0,0 +1,41 @@
+{
+  "$schema": "http://json.schemastore.org/launchsettings.json",
+  "iisSettings": {
+    "windowsAuthentication": false,
+    "anonymousAuthentication": true,
+    "iisExpress": {
+      "applicationUrl": "http://localhost:1454",
+      "sslPort": 44334
+    }
+  },
+  "profiles": {
+    "http": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "launchUrl": "swagger",
+      "applicationUrl": "http://localhost:5152",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
+    },
+    "https": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "launchUrl": "swagger",
+      "applicationUrl": "https://localhost:7070;http://localhost:5152",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
+    },
+    "IIS Express": {
+      "commandName": "IISExpress",
+      "launchBrowser": true,
+      "launchUrl": "swagger",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
+    }
+  }
+}
diff --git a/samples/TransactionalBox.Sample.WebApi.InMemory/ServiceWithInbox/ExampleMessage.cs b/samples/TransactionalBox.Sample.WebApi.InMemory/ServiceWithInbox/ExampleMessage.cs
@@ -0,0 +1,11 @@
+using TransactionalBox.Inbox;
+
+namespace TransactionalBox.Sample.WebApi.InMemory.ServiceWithInbox
+{
+    public sealed class ExampleMessage : IInboxMessage
+    {
+        public string Name { get; init; }
+
+        public int Age { get; init; }
+    }
+}
diff --git a/samples/TransactionalBox.Sample.WebApi.InMemory/ServiceWithInbox/ExampleMessageHandler.cs b/samples/TransactionalBox.Sample.WebApi.InMemory/ServiceWithInbox/ExampleMessageHandler.cs
@@ -0,0 +1,13 @@
+using TransactionalBox.Inbox;
+using TransactionalBox.Inbox.Contexts;
+
+namespace TransactionalBox.Sample.WebApi.InMemory.ServiceWithInbox
+{
+    internal sealed class ExampleMessageHandler : IInboxMessageHandler<ExampleMessage>
+    {
+        public async Task Handle(ExampleMessage message, IExecutionContext executionContext)
+        {
+            // Your Logic
+        }
+    }
+}
diff --git a/samples/TransactionalBox.Sample.WebApi.InMemory/ServiceWithOutbox/ExampleMessage.cs b/samples/TransactionalBox.Sample.WebApi.InMemory/ServiceWithOutbox/ExampleMessage.cs
@@ -0,0 +1,11 @@
+using TransactionalBox.Outbox;
+
+namespace TransactionalBox.Sample.WebApi.InMemory.ServiceWithOutbox
+{
+    public sealed class ExampleMessage : IOutboxMessage
+    {
+        public string Name { get; init; }
+
+        public int Age { get; init; }
+    }
+}
diff --git a/...les/TransactionalBox.Sample.WebApi.InMemory/ServiceWithOutbox/ExampleServiceWithOutbox.cs b/...les/TransactionalBox.Sample.WebApi.InMemory/ServiceWithOutbox/ExampleServiceWithOutbox.cs
@@ -0,0 +1,25 @@
+using TransactionalBox.Outbox;
+
+namespace TransactionalBox.Sample.WebApi.InMemory.ServiceWithOutbox
+{
+    public sealed class ExampleServiceWithOutbox
+    {
+        private readonly IOutbox _outbox;
+
+        public ExampleServiceWithOutbox(IOutbox outbox)
+        {
+            _outbox = outbox;
+        }
+
+        public async Task Execute()
+        {
+            var message = new ExampleMessage()
+            {
+                Name = "Name",
+                Age = 25,
+            };
+
+            await _outbox.Add(message, envelope => envelope.Receiver = "ServiceName");
+        }
+    }
+}
diff --git a/...es/TransactionalBox.Sample.WebApi.InMemory/TransactionalBox.Sample.WebApi.InMemory.csproj b/...es/TransactionalBox.Sample.WebApi.InMemory/TransactionalBox.Sample.WebApi.InMemory.csproj
@@ -0,0 +1,24 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <InvariantGlobalization>true</InvariantGlobalization>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.AspNetCore.OpenApi" />
+    <PackageReference Include="Swashbuckle.AspNetCore" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\source\TransactionalBox.Inbox.Storage.InMemory\TransactionalBox.Inbox.Storage.InMemory.csproj" />
+    <ProjectReference Include="..\..\source\TransactionalBox.InboxWorker.Storage.InMemory\TransactionalBox.InboxWorker.Storage.InMemory.csproj" />
+    <ProjectReference Include="..\..\source\TransactionalBox.InboxWorker.Transport.InMemory\TransactionalBox.InboxWorker.Transport.InMemory.csproj" />
+    <ProjectReference Include="..\..\source\TransactionalBox.Outbox.Storage.InMemory\TransactionalBox.Outbox.Storage.InMemory.csproj" />
+    <ProjectReference Include="..\..\source\TransactionalBox.OutboxWorker.Storage.InMemory\TransactionalBox.OutboxWorker.Storage.InMemory.csproj" />
+    <ProjectReference Include="..\..\source\TransactionalBox.OutboxWorker.Transport.InMemory\TransactionalBox.OutboxWorker.Transport.InMemory.csproj" />
+  </ItemGroup>
+
+</Project>
diff --git a/samples/TransactionalBox.Sample.WebApi.InMemory/appsettings.Development.json b/samples/TransactionalBox.Sample.WebApi.InMemory/appsettings.Development.json
@@ -0,0 +1,8 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  }
+}
diff --git a/samples/TransactionalBox.Sample.WebApi.InMemory/appsettings.json b/samples/TransactionalBox.Sample.WebApi.InMemory/appsettings.json
@@ -0,0 +1,9 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  },
+  "AllowedHosts": "*"
+}
diff --git a/samples/TransactionalBox.Sample.WebApi/InboxMessages/ExampleMessageHandler.cs b/samples/TransactionalBox.Sample.WebApi/InboxMessages/ExampleMessageHandler.cs
@@ -5,18 +5,20 @@ namespace TransactionalBox.Sample.WebApi.InboxMessages
 {
     internal sealed class ExampleMessageHandler : IInboxMessageHandler<ExampleMessage>
     {
+        /*
         private readonly SampleDbContext _context;
 
         public ExampleMessageHandler(SampleDbContext dbContext) 
         {
             _context = dbContext;
         }
+        */
 
         public async Task Handle(ExampleMessage message, IExecutionContext executionContext)
         {
             // Logic
             // TODO config AutoSaveChanges = false (default)
-            await _context.SaveChangesAsync(executionContext.CancellationToken);
+            //await _context.SaveChangesAsync(executionContext.CancellationToken);
         }
     }
 }