From d455350f89a18e33f3a15d9eb4a01eb5f7ed4ee2 Mon Sep 17 00:00:00 2001 From: Dru Sellers Date: Wed, 13 Nov 2024 20:35:17 -0600 Subject: [PATCH] standards work --- .../2.configuration/0.index.md | 135 +++++++++--------- 1 file changed, 70 insertions(+), 65 deletions(-) diff --git a/doc/content/3.documentation/2.configuration/0.index.md b/doc/content/3.documentation/2.configuration/0.index.md index bbd7e45b10..1f1785ae4e 100755 --- a/doc/content/3.documentation/2.configuration/0.index.md +++ b/doc/content/3.documentation/2.configuration/0.index.md @@ -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) => { }); }); @@ -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. @@ -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(); + cfg.AddConsumer(); - x.UsingRabbitMq((context, cfg) => + cfg.UsingRabbitMq((context, rabbit) => { - cfg.ConfigureEndpoints(context); + rabbit.ConfigureEndpoints(context); }); }); ``` @@ -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() +cfg.AddConsumer() .ExcludeFromConfigureEndpoints() ``` @@ -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)); }); ``` @@ -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)); ``` @@ -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(); + cfg.AddConsumer(); - x.UsingRabbitMq((context, cfg) => + cf.UsingRabbitMq((context, rabbit) => { - cfg.ReceiveEndpoint("order-service", e => + rabbit.ReceiveEndpoint("order-service", ep => { - e.ConfigureConsumer(context); + ep.ConfigureConsumer(context); }); }); }); @@ -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(); + cfg.AddConsumer(); - 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(context); + ep.ConcurrentMessageLimit = 28; // only applies to this endpoint + ep.ConfigureConsumer(context); }); }); }); @@ -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(); + cfg.AddConsumer(); - x.UsingInMemory((context, cfg) => + cfg.UsingInMemory((context, mem) => { - cfg.ReceiveEndpoint(new TemporaryEndpointDefinition(), e => + mem.ReceiveEndpoint(new TemporaryEndpointDefinition(), ep => { - e.ConfigureConsumer(context); + ep.ConfigureConsumer(context); }); - cfg.ConfigureEndpoints(context); + mem.ConfigureEndpoints(context); }); }); ``` @@ -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() - .Endpoint(e => + cfg.AddConsumer() + .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)); }); ``` @@ -412,7 +417,7 @@ 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() + cfg.AddConsumer() public SubmitOrderConsumerDefinition() { @@ -420,33 +425,33 @@ When the endpoint is configured after the _AddConsumer_ method, the configuratio } ``` -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() - .Endpoint(x => x.Name = "submit-order-extreme"); + cfg.AddConsumer() + .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() + cfg.AddConsumer() 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() + cfg.AddConsumer() public SubmitOrderConsumerDefinition() { @@ -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() + cfg.AddSagaStateMachine() .InMemoryRepository(); // add a consumer saga with the in-memory repository - r.AddSaga() + cfg.AddSaga() .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(); - r.AddSagasFromNamespaceContaining(typeof(OrderSaga)); + cfg.AddSagasFromNamespaceContaining(); + 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() + cfg.AddSagaStateMachine() .NHibernateRepository() - .Endpoint(e => + .Endpoint(ep => { - e.Name = "order-state"; - e.ConcurrentMessageLimit = 8; + ep.Name = "order-state"; + ep.ConcurrentMessageLimit = 8; }); }); ``` @@ -510,9 +515,9 @@ Supported saga persistence storage engines are documented in the [saga documenta ```csharp -services.AddMassTransit(x => +services.AddMassTransit(cfg => { - x.AddConsumer(); + cfg.AddConsumer(); x.SetKebabCaseEndpointNameFormatter();