Merge pull request #77 from mayuanyang/better-readme

mayuanyang · web-flow · commit e40c0ca8efa9 · 2025-08-05T08:14:46.000+10:00
add wiki
diff --git a/wiki/advanced-features.md b/wiki/advanced-features.md
@@ -0,0 +1,41 @@
+# Advanced Features
+
+Mediator.Net offers several advanced features to enhance its functionality.
+
+## Context Services
+
+Share services between middleware and handlers:
+
+```csharp
+// In middleware
+public Task Execute(TContext context, CancellationToken cancellationToken)
+{
+    context.RegisterService(new AuditInfo { Timestamp = DateTime.UtcNow });
+    return Task.CompletedTask;
+}
+
+// In handler
+public async Task Handle(IReceiveContext<MyCommand> context, CancellationToken cancellationToken)
+{
+    if (context.TryGetService(out AuditInfo auditInfo))
+    {
+        // Use the audit info
+    }
+}
+```
+
+## Publishing Events from Handlers
+
+```csharp
+public async Task Handle(IReceiveContext<CreateOrderCommand> context, CancellationToken cancellationToken)
+{
+    // Process the command
+    var order = new Order(context.Message.CustomerId);
+    
+    // Publish domain event
+    await context.Publish(new OrderCreatedEvent 
+    { 
+        OrderId = order.Id, 
+        CustomerId = order.CustomerId 
+    });
+}
diff --git a/wiki/contributing.md b/wiki/contributing.md
@@ -0,0 +1,3 @@
+# Contributing
+
+We welcome contributions! Please see our [Contributing Guide](../CONTRIBUTING.md) for details.
diff --git a/wiki/dependency-injection-integration.md b/wiki/dependency-injection-integration.md
@@ -0,0 +1,37 @@
+# Dependency Injection Integration
+
+Mediator.Net integrates with various dependency injection containers to manage the lifecycle of handlers and other components.
+
+## Microsoft.Extensions.DependencyInjection
+
+```bash
+Install-Package Mediator.Net.MicrosoftDependencyInjection
+```
+
+```csharp
+services.AddMediator(builder => 
+{
+    builder.RegisterHandlers(typeof(Program).Assembly);
+});
+```
+
+## Autofac
+
+```bash
+Install-Package Mediator.Net.Autofac
+```
+
+```csharp
+var builder = new ContainerBuilder();
+var mediatorBuilder = new MediatorBuilder()
+    .RegisterHandlers(typeof(Program).Assembly);
+
+builder.RegisterMediator(mediatorBuilder);
+var container = builder.Build();
+```
+
+## Other Supported Containers
+
+- **SimpleInjector**: `Mediator.Net.SimpleInjector`
+- **StructureMap**: `Mediator.Net.StructureMap`
+- **Ninject**: `Mediator.Net.Ninject`
diff --git a/wiki/documentation.md b/wiki/documentation.md
@@ -0,0 +1,9 @@
+# Documentation
+
+For more detailed documentation, examples, and advanced scenarios, visit our [Wiki](https://github.com/mayuanyang/Mediator.Net/wiki).
+
+For additional resources and support, please refer to the following:
+
+- [Contributing Guide](../CONTRIBUTING.md)
+- [License](../LICENSE.txt)
+- [Support](../README.md#️-support)
diff --git a/wiki/features.md b/wiki/features.md
@@ -0,0 +1,11 @@
+# Features
+
+Mediator.Net offers the following features:
+
+- **Command/Query Separation**: Clear separation between commands, queries, and events.
+- **Pipeline Support**: Extensible middleware pipeline for cross-cutting concerns.
+- **Streaming Support**: Handle multiple responses with `IAsyncEnumerable`.
+- **Dependency Injection**: Built-in support for popular IoC containers.
+- **Event Publishing**: Publish events from within handlers.
+- **Flexible Registration**: Both explicit and assembly scanning registration.
+- **Middleware Ecosystem**: Rich collection of pre-built middlewares.
diff --git a/wiki/handler-registration.md b/wiki/handler-registration.md
@@ -0,0 +1,23 @@
+# Handler Registration
+
+Mediator.Net supports two methods for registering handlers: assembly scanning and explicit registration.
+
+## Assembly Scanning (Recommended)
+
+```csharp
+var mediator = new MediatorBuilder()
+    .RegisterHandlers(typeof(Program).Assembly)
+    .Build();
+```
+
+## Explicit Registration
+
+```csharp
+var mediator = new MediatorBuilder()
+    .RegisterHandlers(() => new List<MessageBinding>
+    {
+        new MessageBinding(typeof(CreateUserCommand), typeof(CreateUserCommandHandler)),
+        new MessageBinding(typeof(GetUserQuery), typeof(GetUserQueryHandler)),
+        new MessageBinding(typeof(UserCreatedEvent), typeof(UserCreatedEventHandler))
+    })
+    .Build();
diff --git a/wiki/index.md b/wiki/index.md
@@ -0,0 +1,17 @@
+# Mediator.Net Wiki
+
+This is the wiki for the Mediator.Net project. Below are the sections that provide detailed information about the project.
+
+- [Features](features.md)
+- [Installation](installation.md)
+- [Quick Start](quick-start.md)
+- [Usage Examples](usage-examples.md)
+- [Handler Registration](handler-registration.md)
+- [Pipeline & Middleware](pipeline-middleware.md)
+- [Dependency Injection Integration](dependency-injection-integration.md)
+- [Official Middleware Packages](official-middleware-packages.md)
+- [Advanced Features](advanced-features.md)
+- [Documentation](documentation.md)
+- [Contributing](contributing.md)
+- [License](license.md)
+- [Support](support.md)
diff --git a/wiki/installation.md b/wiki/installation.md
@@ -0,0 +1,14 @@
+# Installation
+
+To install Mediator.Net, you can use NuGet or the .NET CLI.
+
+## Using NuGet
+
+```bash
+Install-Package Mediator.Net
+```
+
+## Using .NET CLI
+
+```bash
+dotnet add package Mediator.Net
diff --git a/wiki/license.md b/wiki/license.md
@@ -0,0 +1,3 @@
+# License
+
+This project is licensed under the MIT License - see the [LICENSE.txt](../LICENSE.txt) file for details.
diff --git a/wiki/official-middleware-packages.md b/wiki/official-middleware-packages.md
@@ -0,0 +1,29 @@
+# Official Middleware Packages
+
+Mediator.Net provides several official middleware packages to extend its functionality.
+
+## Serilog Logging
+
+```bash
+Install-Package Mediator.Net.Middlewares.Serilog
+```
+
+```csharp
+.ConfigureGlobalReceivePipe(x => x.UseSerilog(LogEventLevel.Information))
+```
+
+## Unit of Work
+
+```bash
+Install-Package Mediator.Net.Middlewares.UnitOfWork
+```
+
+Provides `CommittableTransaction` support for transactional operations.
+
+## EventStore Integration
+
+```bash
+Install-Package Mediator.Net.Middlewares.EventStore
+```
+
+Automatically persists events to EventStore.
diff --git a/wiki/pipeline-middleware.md b/wiki/pipeline-middleware.md
@@ -0,0 +1,85 @@
+# Pipeline & Middleware
+
+Mediator.Net supports five types of pipelines for different scenarios:
+
+![Pipeline Architecture](https://cloud.githubusercontent.com/assets/3387099/21959127/9a065420-db09-11e6-8dbc-ca0069894e1c.png)
+
+## Pipeline Types
+
+| Pipeline | Description | Triggers For |
+|----------|-------------|--------------|
+| **GlobalReceivePipeline** | Executes for all messages | Commands, Requests, Events |
+| **CommandReceivePipeline** | Executes only for commands | ICommand |
+| **RequestReceivePipeline** | Executes only for requests | IRequest |
+| **EventReceivePipeline** | Executes only for events | IEvent |
+| **PublishPipeline** | Executes when events are published | IEvent (outgoing) |
+
+## Creating Custom Middleware
+
+### 1. Create Middleware Extension
+
+```csharp
+public static class LoggingMiddleware
+{
+    public static void UseLogging<TContext>(
+        this IPipeConfigurator<TContext> configurator, 
+        ILogger logger = null)
+        where TContext : IContext<IMessage>
+    {
+        logger ??= configurator.DependencyScope?.Resolve<ILogger>();
+        configurator.AddPipeSpecification(new LoggingMiddlewareSpecification<TContext>(logger));
+    }
+}
+```
+
+### 2. Create Middleware Specification
+
+```csharp
+public class LoggingMiddlewareSpecification<TContext> : IPipeSpecification<TContext> 
+    where TContext : IContext<IMessage>
+{
+    private readonly ILogger _logger;
+
+    public LoggingMiddlewareSpecification(ILogger logger)
+    {
+        _logger = logger;
+    }
+
+    public bool ShouldExecute(TContext context, CancellationToken cancellationToken) => true;
+
+    public Task BeforeExecute(TContext context, CancellationToken cancellationToken)
+    {
+        _logger.LogInformation("Processing message: {MessageType}", context.Message.GetType().Name);
+        return Task.CompletedTask;
+    }
+
+    public Task Execute(TContext context, CancellationToken cancellationToken)
+    {
+        return Task.CompletedTask;
+    }
+
+    public Task AfterExecute(TContext context, CancellationToken cancellationToken)
+    {
+        _logger.LogInformation("Completed processing: {MessageType}", context.Message.GetType().Name);
+        return Task.CompletedTask;
+    }
+
+    public void OnException(Exception ex, TContext context)
+    {
+        _logger.LogError(ex, "Error processing message: {MessageType}", context.Message.GetType().Name);
+        throw ex;
+    }
+}
+```
+
+## Configuring Pipelines
+
+```csharp
+var mediator = new MediatorBuilder()
+    .RegisterHandlers(typeof(Program).Assembly)
+    .ConfigureGlobalReceivePipe(x => x.UseLogging())
+    .ConfigureCommandReceivePipe(x => x.UseValidation())
+    .ConfigureRequestPipe(x => x.UseCaching())
+    .ConfigureEventReceivePipe(x => x.UseEventStore())
+    .ConfigurePublishPipe(x => x.UseOutboxPattern())
+    .Build();
diff --git a/wiki/quick-start.md b/wiki/quick-start.md
@@ -0,0 +1,66 @@
+# Quick Start
+
+## Basic Setup
+
+To get started with Mediator.Net, you can create and configure the mediator as follows:
+
+```csharp
+// Create and configure mediator
+var mediaBuilder = new MediatorBuilder();
+var mediator = mediaBuilder.RegisterHandlers(typeof(Program).Assembly).Build();
+```
+
+## Define Messages and Handlers
+
+Define your messages and handlers as shown below:
+
+```csharp
+// Command (no response)
+public class CreateUserCommand : ICommand
+{
+    public string Name { get; set; }
+    public string Email { get; set; }
+}
+
+public class CreateUserCommandHandler : ICommandHandler<CreateUserCommand>
+{
+    public async Task Handle(IReceiveContext<CreateUserCommand> context, CancellationToken cancellationToken)
+    {
+        // Handle the command
+        var user = new User(context.Message.Name, context.Message.Email);
+        // Save user...
+        
+        // Publish an event
+        await context.Publish(new UserCreatedEvent { UserId = user.Id });
+    }
+}
+
+// Request/Response
+public class GetUserQuery : IRequest<UserDto>
+{
+    public int UserId { get; set; }
+}
+
+public class GetUserQueryHandler : IRequestHandler<GetUserQuery, UserDto>
+{
+    public async Task<UserDto> Handle(IReceiveContext<GetUserQuery> context, CancellationToken cancellationToken)
+    {
+        // Handle the query and return response
+        return new UserDto { Id = context.Message.UserId, Name = "John Doe" };
+    }
+}
+
+// Event
+public class UserCreatedEvent : IEvent
+{
+    public int UserId { get; set; }
+}
+
+public class UserCreatedEventHandler : IEventHandler<UserCreatedEvent>
+{
+    public async Task Handle(IReceiveContext<UserCreatedEvent> context, CancellationToken cancellationToken)
+    {
+        // Handle the event
+        Console.WriteLine($"User {context.Message.UserId} was created!");
+    }
+}
diff --git a/wiki/support.md b/wiki/support.md
@@ -0,0 +1,7 @@
+# Support
+
+For support and questions, please refer to the following resources:
+
+- [Documentation](../README.md#-documentation)
+- [Stack Overflow](http://stackoverflow.com/questions/tagged/memdiator.net) (use the `mediator.net` tag)
+- [Issues](https://github.com/mayuanyang/Mediator.Net/issues)
diff --git a/wiki/usage-examples.md b/wiki/usage-examples.md

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Contributing`
	`2`	`+`
	`3`	`+We welcome contributions! Please see our [Contributing Guide](../CONTRIBUTING.md) for details.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# License`
	`2`	`+`
	`3`	`+This project is licensed under the MIT License - see the [LICENSE.txt](../LICENSE.txt) file for details.`