Skip to content

Commit

Permalink
standards work
Browse files Browse the repository at this point in the history
  • Loading branch information
@drusellers
drusellers committed Nov 14, 2024
1 parent 1f349e9 commit d455350
Showing 1 changed file with 70 additions and 65 deletions.
135 changes: 70 additions & 65 deletions doc/content/3.documentation/2.configuration/0.index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,10 @@ To use MassTransit, add the _MassTransit_ package (from NuGet) and start with th
```csharp
using MassTransit;

services.AddMassTransit(x =>
services.AddMassTransit(cfg =>
{
// A Transport
x.UsingRabbitMq((context, cfg) =>
cfg.UsingRabbitMq((context, rabbit) =>
{
});
});
Expand All @@ -24,9 +24,9 @@ In this configuration, the following variables are used:

| Variable | Type | Description |
|-----------|:----------------------------------|-------------------------------------------------------------------------------------------|
| `x` | `IBusRegistrationConfigurator` | Configure the bus instance (not transport specific) and the underlying service collection |
| `cfg` | `IBusRegistrationConfigurator` | Configure the bus instance (not transport specific) and the underlying service collection |
| `context` | `IBusRegistrationContext` | The configured bus context, also implements `IServiceProvider` |
| `cfg` | `IRabbitMqBusFactoryConfigurator` | Configure the bus specific to the transport (each transport has its own interface type |
| `rabbit` | `IRabbitMqBusFactoryConfigurator` | Configure the bus specific to the transport (each transport has its own interface type |

:::alert{type="info"}
The callback passed to the _UsingRabbitMq_ method is invoked after the service collection has been built. Any methods to configure the bus instance (using `x`) should be called outside of this callback.
Expand Down Expand Up @@ -93,13 +93,13 @@ To consume messages, one or more consumers must be added and receive endpoints c
To add a consumer and automatically configure a receive endpoint for the consumer, call one of the [_AddConsumer_](/documentation/configuration/bus/consumers) methods and call [_ConfigureEndpoints_](documentation/configuration#configure-endpoints) as shown below.

```csharp
services.AddMassTransit(x =>
services.AddMassTransit(cfg =>
{
x.AddConsumer<SubmitOrderConsumer>();
cfg.AddConsumer<SubmitOrderConsumer>();

x.UsingRabbitMq((context, cfg) =>
cfg.UsingRabbitMq((context, rabbit) =>
{
cfg.ConfigureEndpoints(context);
rabbit.ConfigureEndpoints(context);
});
});
```
Expand All @@ -124,7 +124,7 @@ Learn about the default conventions as well as how to tailor the naming style to
To exclude a consumer, saga, or routing slip activity from automatic configuration, use the _ExcludeFromConfigureEndpoints_ extension method when adding the consumer:

```csharp
x.AddConsumer<SubmitOrderConsumer>()
cfg.AddConsumer<SubmitOrderConsumer>()
.ExcludeFromConfigureEndpoints()
```

Expand Down Expand Up @@ -153,23 +153,23 @@ If multiple consumer types share the same receive endpoint, and more than one of
To apply receive endpoint settings or configure middleware for all receive endpoints configured by `ConfigureEndpoints`, a callback can be added.

```csharp
x.AddConfigureEndpointsCallback((name, cfg) =>
cfg.AddConfigureEndpointsCallback((name, ep) =>
{
cfg.UseMessageRetry(r => r.Immediate(2));
ep.UseMessageRetry(r => r.Immediate(2));
});
```

When `ConfigureEndpoints` is called, any registered callbacks will be called for every recieve endpoint endpoint. Each callback will only be called _once_ per receive endpoint.

To conditionally apply transport-specific settings, the `cfg` parameter can be pattern-matched to the transport type as shown below.
To conditionally apply transport-specific settings, the `ep` parameter can be pattern-matched to the transport type as shown below.

```csharp
x.AddConfigureEndpointsCallback((name, cfg) =>
cfg.AddConfigureEndpointsCallback((name, ep) =>
{
if (cfg is IRabbitMqReceiveEndpointConfigurator rmq)
if (ep is IRabbitMqReceiveEndpointConfigurator rmq)
rmq.SetQuorumQueue(3);

cfg.UseMessageRetry(r => r.Immediate(2));
ep.UseMessageRetry(r => r.Immediate(2));
});
```

Expand Down Expand Up @@ -227,16 +227,21 @@ _ConfigureEndpoints_ uses an `IEndpointNameFormatter` to format the queue names
The endpoint name formatters can also be customized by constructing a new instance and configuring MassTransit to use it.

```csharp
x.SetEndpointNameFormatter(new KebabCaseEndpointNameFormatter(prefix: "Dev", includeNamespace: false));
cfg.SetEndpointNameFormatter(new KebabCaseEndpointNameFormatter(prefix: "Dev", includeNamespace: false));
```

By specifying a prefix, the endpoint name would be `dev-submit-order`. This is useful when sharing a single broker with multiple developers (Amazon SQS is account-wide, for instance).

::callout{type="info"}

#summary
When using MultiBus with different endpoint name formatters for each bus...

When using [MultiBus](/documentation/configuration/multibus) with different endpoint name formatters for each bus...

#content

Specify the endpoint name formatter when calling `ConfigureEndpoints` as shown.

```csharp
cfg.ConfigureEndpoints(context, new KebabCaseEndpointNameFormatter(prefix: "Mobile", includeNamespace: false));
```
Expand All @@ -251,15 +256,15 @@ The previous examples use conventions to configure receive endpoints. Alternativ
To explicitly configure endpoints, use the _ConfigureConsumer_ or _ConfigureConsumers_ method.

```csharp
services.AddMassTransit(x =>
services.AddMassTransit(cfg =>
{
x.AddConsumer<SubmitOrderConsumer>();
cfg.AddConsumer<SubmitOrderConsumer>();

x.UsingRabbitMq((context, cfg) =>
cf.UsingRabbitMq((context, rabbit) =>
{
cfg.ReceiveEndpoint("order-service", e =>
rabbit.ReceiveEndpoint("order-service", ep =>
{
e.ConfigureConsumer<SubmitOrderConsumer>(context);
ep.ConfigureConsumer<SubmitOrderConsumer>(context);
});
});
});
Expand All @@ -282,18 +287,18 @@ Receive endpoints have transport-independent settings that can be configured.
In the following example, the _PrefetchCount_ is set to 32 and the _ConcurrentMessageLimit_ is set to 28.

```csharp
services.AddMassTransit(x =>
services.AddMassTransit(cfg =>
{
x.AddConsumer<SubmitOrderConsumer>();
cfg.AddConsumer<SubmitOrderConsumer>();

x.UsingRabbitMq((context, cfg) =>
cfg.UsingRabbitMq((context, rabbit) =>
{
cfg.PrefetchCount = 32; // applies to all receive endpoints
rabbit.PrefetchCount = 32; // applies to all receive endpoints
cfg.ReceiveEndpoint("order-service", e =>
rabbit.ReceiveEndpoint("order-service", ep =>
{
e.ConcurrentMessageLimit = 28; // only applies to this endpoint
e.ConfigureConsumer<SubmitOrderConsumer>(context);
ep.ConcurrentMessageLimit = 28; // only applies to this endpoint
ep.ConfigureConsumer<SubmitOrderConsumer>(context);
});
});
});
Expand All @@ -306,18 +311,18 @@ services.AddMassTransit(x =>
Some consumers only need to receive messages while connected, and any messages published while disconnected should be discarded. This can be achieved by using a TemporaryEndpointDefinition to configure the receive endpoint.

```csharp
services.AddMassTransit(x =>
services.AddMassTransit(cfg =>
{
x.AddConsumer<SubmitOrderConsumer>();
cfg.AddConsumer<SubmitOrderConsumer>();

x.UsingInMemory((context, cfg) =>
cfg.UsingInMemory((context, mem) =>
{
cfg.ReceiveEndpoint(new TemporaryEndpointDefinition(), e =>
mem.ReceiveEndpoint(new TemporaryEndpointDefinition(), ep =>
{
e.ConfigureConsumer<SubmitOrderConsumer>(context);
ep.ConfigureConsumer<SubmitOrderConsumer>(context);
});

cfg.ConfigureEndpoints(context);
mem.ConfigureEndpoints(context);
});
});
```
Expand Down Expand Up @@ -378,18 +383,18 @@ class SubmitOrderConsumerDefinition :
To configure the endpoint for a consumer registration, or override the endpoint configuration in the definition, the `Endpoint` method can be added to the consumer registration. This will create an endpoint definition for the consumer, and register it in the container. This method is available on consumer and saga registrations, with separate execute and compensate endpoint methods for activities.

```csharp
services.AddMassTransit(x =>
services.AddMassTransit(cfg =>
{
x.AddConsumer<SubmitOrderConsumer, SubmitOrderConsumerDefinition>()
.Endpoint(e =>
cfg.AddConsumer<SubmitOrderConsumer, SubmitOrderConsumerDefinition>()
.Endpoint(ep =>
{
// override the default endpoint name
e.Name = "order-service-extreme";
ep.Name = "order-service-extreme";

// more options shown below
});

x.UsingRabbitMq((context, cfg) => cfg.ConfigureEndpoints(context));
cfg.UsingRabbitMq((context, rabbit) => rabbit.ConfigureEndpoints(context));
});
```

Expand All @@ -412,41 +417,41 @@ When the endpoint is configured after the _AddConsumer_ method, the configuratio
1. Specifying `EndpointName = "submit-order-extreme"` in the constructor which cannot be overridden

```csharp
x.AddConsumer<SubmitOrderConsumer, SubmitOrderConsumerDefinition>()
cfg.AddConsumer<SubmitOrderConsumer, SubmitOrderConsumerDefinition>()

public SubmitOrderConsumerDefinition()
{
EndpointName = "submit-order-extreme";
}
```

2. Specifying `.Endpoint(x => x.Name = "submit-order-extreme")` in the consumer registration, chained to `AddConsumer`
2. Specifying `.Endpoint(ep => ep.Name = "submit-order-extreme")` in the consumer registration, chained to `AddConsumer`

```csharp
x.AddConsumer<SubmitOrderConsumer, SubmitOrderConsumerDefinition>()
.Endpoint(x => x.Name = "submit-order-extreme");
cfg.AddConsumer<SubmitOrderConsumer, SubmitOrderConsumerDefinition>()
.Endpoint(ep => ep.Name = "submit-order-extreme");

public SubmitOrderConsumerDefinition()
{
Endpoint(x => x.Name = "not used");
Endpoint(ep => ep.Name = "not used");
}
```

3. Specifying `Endpoint(x => x.Name = "submit-order-extreme")` in the constructor, which creates an endpoint definition
3. Specifying `Endpoint(ep => ep.Name = "submit-order-extreme")` in the constructor, which creates an endpoint definition

```csharp
x.AddConsumer<SubmitOrderConsumer, SubmitOrderConsumerDefinition>()
cfg.AddConsumer<SubmitOrderConsumer, SubmitOrderConsumerDefinition>()

public SubmitOrderConsumerDefinition()
{
Endpoint(x => x.Name = "submit-order-extreme");
Endpoint(ep => ep.Name = "submit-order-extreme");
}
```

4. Unspecified, the endpoint name formatter is used (in this case, the endpoint name is `SubmitOrder` using the default formatter)

```csharp
x.AddConsumer<SubmitOrderConsumer, SubmitOrderConsumerDefinition>()
cfg.AddConsumer<SubmitOrderConsumer, SubmitOrderConsumerDefinition>()

public SubmitOrderConsumerDefinition()
{
Expand All @@ -462,46 +467,46 @@ State machine sagas should be added before class-based sagas, and the class-base
::

```csharp
services.AddMassTransit(r =>
services.AddMassTransit(cfg =>
{
// add a state machine saga, with the in-memory repository
r.AddSagaStateMachine<OrderStateMachine, OrderState>()
cfg.AddSagaStateMachine<OrderStateMachine, OrderState>()
.InMemoryRepository();

// add a consumer saga with the in-memory repository
r.AddSaga<OrderSaga>()
cfg.AddSaga<OrderSaga>()
.InMemoryRepository();

// add a saga by type, without a repository. The repository should be registered
// in the container elsewhere
r.AddSaga(typeof(OrderSaga));
cfg.AddSaga(typeof(OrderSaga));

// add a state machine saga by type, including a saga definition for that saga
r.AddSagaStateMachine(typeof(OrderState), typeof(OrderStateDefinition))
cfg.AddSagaStateMachine(typeof(OrderState), typeof(OrderStateDefinition))

// add all saga state machines by type
r.AddSagaStateMachines(Assembly.GetExecutingAssembly());
cfg.AddSagaStateMachines(Assembly.GetExecutingAssembly());

// add all sagas in the specified assembly
r.AddSagas(Assembly.GetExecutingAssembly());
cfg.AddSagas(Assembly.GetExecutingAssembly());

// add sagas from the namespace containing the type
r.AddSagasFromNamespaceContaining<OrderSaga>();
r.AddSagasFromNamespaceContaining(typeof(OrderSaga));
cfg.AddSagasFromNamespaceContaining<OrderSaga>();
cfg.AddSagasFromNamespaceContaining(typeof(OrderSaga));
});
```

To add a saga registration and configure the consumer endpoint in the same expression, a definition can automatically be created.

```csharp
services.AddMassTransit(r =>
services.AddMassTransit(cfg =>
{
r.AddSagaStateMachine<OrderStateMachine, OrderState>()
cfg.AddSagaStateMachine<OrderStateMachine, OrderState>()
.NHibernateRepository()
.Endpoint(e =>
.Endpoint(ep =>
{
e.Name = "order-state";
e.ConcurrentMessageLimit = 8;
ep.Name = "order-state";
ep.ConcurrentMessageLimit = 8;
});
});
```
Expand All @@ -510,9 +515,9 @@ Supported saga persistence storage engines are documented in the [saga documenta


```csharp
services.AddMassTransit(x =>
services.AddMassTransit(cfg =>
{
x.AddConsumer<ValueEnteredEventConsumer>();
cfg.AddConsumer<ValueEnteredEventConsumer>();

x.SetKebabCaseEndpointNameFormatter();

Expand Down

0 comments on commit d455350

Please sign in to comment.