NServiceBus

https://docs.particular.net/
Admin
NServiceBus is an open-source .NET messaging framework for building distributed systems with...
Tokens:2,113,435
Snippets:19,422
Trust Score:9.7
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### Install as Windows service - example

Source: https://docs.particular.net/nservicebus/hosting/nservicebus-host/installation.md

Example of the /install command with typical parameters: service name, display name, description, endpoint configuration type, username, and password.

```shell
NServiceBus.Host.exe /install
/serviceName:"MyPublisher"
/displayName:"My Publisher Service"
/description:"Service for publishing event messages"
/endpointConfigurationType:"QualifiedNameSpace.EndpointConfigType, AssemblyName"
/username:"corp\serviceuser"
/password:"p@ssw0rd!"
```

--------------------------------

### Start mode

Source: https://docs.particular.net/nservicebus/hosting/windows-service.md

The Windows Service start mode can be configured at creation time using the start parameter. The example shows the generic syntax and a concrete example.

```shell
sc.exe create [ServiceName] start= {auto | demand | disabled} binpath= [BinaryPathName]
sc.exe create SalesEndpoint start= demand binpath= "c:\SalesEndpoint\SalesEndpoint.exe --run-as-service"
```

--------------------------------

### Enable installers based on command line arguments

Source: https://docs.particular.net/nservicebus/operations/installers.md

Enable installers based on command line arguments. The example checks for the "/runInstallers" argument (case-insensitive) and calls EnableInstallers if present.

```csharp
var runInstallers = Environment.GetCommandLineArgs().Any(x => string.Equals(x, "/runInstallers", StringComparison.OrdinalIgnoreCase));

if (runInstallers)
{
    endpointConfiguration.EnableInstallers();
}
```

--------------------------------

### Run ServiceControl container with --setup-and-run

Source: https://docs.particular.net/servicecontrol/servicecontrol-instances/deployment/containers.md

Combines setup and run operations in one container start. Runs setup when the container starts, then the application runs normally, removing the need for a separate init container and repeating setup on updates.

```shell
# Using docker run
docker run {OPTIONS} particular/servicecontrol --setup-and-run
```

--------------------------------

### Run ServiceControl Audit with --setup-and-run

Source: https://docs.particular.net/servicecontrol/audit-instances/deployment/containers.md

Combines setup and run operations in a single container start. Runs setup when the container starts, then runs the application normally. Removes the need for a separate init container.

```shell
# Using docker run
docker run {OPTIONS} particular/servicecontrol-audit --setup-and-run
```

--------------------------------

### Run installer setup with externally managed container

Source: https://docs.particular.net/nservicebus/operations/installers_core_8.md

Use this code when setup requires access to services provided via an externally managed dependency injection container. It creates an installer with the externally managed container and passes the built IServiceProvider to Setup.

```csharp
public static async Task Main()
{
    var endpointConfiguration = new EndpointConfiguration("my-endpoint");
    // configure endpoint

    var serviceCollection = new ServiceCollection();
    // custom registrations

    var installer = Installer.CreateInstallerWithExternallyManagedContainer(endpointConfiguration, serviceCollection);

    var serviceProvider = serviceCollection.BuildServiceProvider();

    await installer.Setup(serviceProvider);
}
```

--------------------------------

### Run installers with the installer API

Source: https://docs.particular.net/nservicebus/operations/installers.md

Use the installer API to run all necessary installation steps when special privileges are required to set up the endpoint. The API always runs installers regardless of whether the endpoint has configured EnableInstallers. The example shows both the default behavior (stop the host after running installers) and the option to continue the host by setting InstallersShutdownBehavior.Continue.

```csharp
var hostBuilder = new HostApplicationBuilder();
var endpointConfiguration = new EndpointConfiguration("someEndpoint");

hostBuilder.Services.AddNServiceBusEndpoint(endpointConfiguration);

// On run, this will run the installers and then stop the host
hostBuilder.Services.AddNServiceBusInstallers();

// OR, this will run the installers and allow the host to continue
hostBuilder.Services.AddNServiceBusInstallers(options =>
    options.ShutdownBehavior = InstallersShutdownBehavior.Continue);

// This will run the installers with the requested ShutdownBehavior
await hostBuilder.Build()
    .RunAsync();
```

--------------------------------

### Start method for Docker endpoint

Source: https://docs.particular.net/nservicebus/hosting/docker-host/index_templates_2.md

The `Start()` method in `Host.cs` configures the endpoint with a placeholder for common configuration, sets the serializer to NewtonsoftJson, defines a critical error action, and uses LearningTransport and LearningPersistence when running in interactive debug mode. It also enables installers and starts the endpoint.

```csharp
public async Task Start()
{
    try
    {
        // TODO: consider moving common endpoint configuration into a shared project
        // for use by all endpoints in the system
        var endpointConfiguration = new EndpointConfiguration(EndpointName);

        // TODO: ensure the most appropriate serializer is chosen
        // https://docs.particular.net/nservicebus/serialization/
        endpointConfiguration.UseSerialization<NewtonsoftJsonSerializer>();

        endpointConfiguration.DefineCriticalErrorAction(OnCriticalError);

        // TODO: remove this condition after choosing a transport, persistence and deployment method suitable for production
        if (Environment.UserInteractive && Debugger.IsAttached)
        {
            // TODO: choose a durable transport for production
            // https://docs.particular.net/transports/
            var transportExtensions = endpointConfiguration.UseTransport<LearningTransport>();

            // TODO: choose a durable persistence for production
            // https://docs.particular.net/persistence/
            endpointConfiguration.UsePersistence<LearningPersistence>();

            // TODO: create a script for deployment to production
            endpointConfiguration.EnableInstallers();
        }

        // TODO: replace the license.xml file with a valid license file

        // TODO: perform any further start up operations before or after starting the endpoint
        endpoint = await Endpoint.Start(endpointConfiguration);
    }
    catch (Exception ex)
    {
        FailFast("Failed to start.", ex);
    }
}
```

--------------------------------

### Publish MassTransit event in Worker loop

Source: https://docs.particular.net/samples/pipeline/masstransit-messages/index_core_9.md

Publishes a MassTransitEvent every second until the worker's cancellation token is requested. This loop runs inside the Worker background service and is unchanged from the MassTransit Getting Started guide.

```csharp
while (!cts.Token.IsCancellationRequested)
{
    await bus.Publish(new MassTransitEvent { Text = $"The time is {DateTimeOffset.Now}" });
    await Task.Delay(1000, cts.Token);
}
```

--------------------------------

### Run installers with Installer.Setup

Source: https://docs.particular.net/nservicebus/operations/installers_core_9.md

Runs all necessary installation steps for the endpoint using the installer API. Requires elevated permissions to administer resources such as database tables, queues, or directories. The installer APIs always run installers, regardless of whether the endpoint has configured EnableInstallers.

```csharp
var endpointConfiguration = new EndpointConfiguration("my-endpoint");
// configure endpoint

await Installer.Setup(endpointConfiguration);
```

--------------------------------

### Combined setup and run with --setup-and-run

Source: https://docs.particular.net/servicecontrol/monitoring-instances/deployment/containers.md

Runs setup and then the application in a single container invocation, simplifying deployment by removing the need for a separate init container.

```shell
# Using docker run
docker run {OPTIONS} particular/servicecontrol-monitoring --setup-and-run
```

--------------------------------

### Run installers explicitly in setup mode

Source: https://docs.particular.net/nservicebus/hosting/extensions-hosting_extensions.hosting_1.md

Use this snippet to run NServiceBus installers only in a dedicated setup mode, avoiding startup time and permission issues. It checks for the -s or /s command-line flag, runs the installer, and then returns. The commented lines show where to enable installers for development and where to continue with host.RunAsync().

```csharp
var isSetup = args.Contains("-s") || args.Contains("/s");

if (isSetup)
{
    // Installers are useful in development. Consider disabling in production.
    // https://docs.particular.net/nservicebus/operations/installers
    // endpointConfiguration.EnableInstallers();

    await Installer.Setup(endpointConfiguration);
    return;
}

// Continue and eventually invoke:
// await host.RunAsync();

```

--------------------------------

### Install as Windows service - syntax

Source: https://docs.particular.net/nservicebus/hosting/nservicebus-host/installation.md

Command-line syntax for installing the host as a Windows service. The /install argument also triggers the installers.

```shell
NServiceBus.Host.exe /install
[/serviceName:<string>]
[/displayName:<string>]
[/description:<string>]
[/endpointConfigurationType:<string>]
[/endpointName:<string>]
[/scannedAssemblies:<string>]
[/dependsOn:<string>]
[/sideBySide]
[/startManually]
[/username:<string>]
[/password:<string>]
[<profile>]
```

--------------------------------

### Feature Setup method

Source: https://docs.particular.net/nservicebus/pipeline/features.md

Implement the Setup method to configure the feature, register services, and add pipeline behaviors. The context provides Settings, Services, and Pipeline.

```csharp
protected override void Setup(FeatureConfigurationContext context)
{
    var configurationValue = context.Settings.Get<string>("Key");

    context.Services.AddSingleton(new MessageHandlerDependency());

    context.Pipeline.Register(new CustomBehavior(configurationValue), "custom pipeline behavior");
}
```

--------------------------------

### Register installer from a Feature class

Source: https://docs.particular.net/nservicebus/operations/installers.md

Register a custom installer from a Feature class that requires it. The Setup method uses the FeatureConfigurationContext to add the installer.

```csharp
public class MyFeature : Feature
{
    protected override void Setup(FeatureConfigurationContext context)
    {
        context.AddInstaller<MyInstaller>();
    }
}
```

--------------------------------

### Implement INeedToInstallSomething for a custom installer

Source: https://docs.particular.net/nservicebus/operations/installers.md

Implement the INeedToInstallSomething interface to create a custom installer. The Install method receives an identity and a cancellation token, and returns a completed task after performing installation work.

```csharp
public class MyInstaller : INeedToInstallSomething
{
    public Task Install(string identity, CancellationToken cancellationToken)
    {
        // Code to install something

        return Task.CompletedTask;
    }
}
```

--------------------------------

### In-process host configuration using Startup.cs

Source: https://docs.particular.net/nservicebus/upgrades/azure-functions-service-bus-in-process-isolated-worker.md

Example of an in-process host configuration using the FunctionsStartup attribute and Startup class. This is the old approach that is replaced by Program.cs when migrating to the isolated worker model.

```csharp
[assembly: FunctionsStartup(typeof(Startup))]
[assembly: NServiceBusTriggerFunction(Startup.EndpointName)]

class Startup : FunctionsStartup
{
    public const string EndpointName = "DemoEndpoint";

    public override void Configure(IFunctionsHostBuilder builder)
    {
        builder.UseNServiceBus();
    }
}
```

--------------------------------

### ServiceControl install folder path

Source: https://docs.particular.net/servicecontrol/upgrades/4to5/alternative.md

Navigate to the ServiceControl install folder in an elevated command prompt before running the setup command.

```text
C:\Program Files (x86)\Particular Software\Particular.ServiceControl
```

--------------------------------

### Saga Start Conflict Exception

Source: https://docs.particular.net/persistence/learning/index_core_7.md

Example exception thrown when starting a saga and the saga data file already exists.

```text
System.IO.IOException: The file 'S:\.sagas\OrderSaga\944b7efb-7146-adf1-d6ae-968f0d7757fa.json' already exists.
```

--------------------------------

### local.settings.json example

Source: https://docs.particular.net/nservicebus/hosting/azure-functions-service-bus/in-process/index_asbfunctions_3.md

Example of local.settings.json for local development, showing how to set the PARTICULARSOFTWARE_LICENSE environment variable.

```json
{
  "IsEncrypted": false,
  "Values": {
    ...
    "PARTICULARSOFTWARE_LICENSE": "<?xml version=\"1.0\" encoding=\"utf-8\"?><license id=\"1222e1d1-2222-4a46-b1c6-943c442ca710\" expiration=\"2113-11-30T00:00:00.0000000\" type=\"Standard\" LicenseType=\"Standard\" LicenseVersion=\"4.0\" MaxMessageThroughputPerSecond=\"Max\" WorkerThreads=\"Max\" AllowedNumberOfWorkerNodes=\"Max\">. . .</license>"
  }
}
```

--------------------------------

### Enable installers at startup

Source: https://docs.particular.net/nservicebus/operations/installers.md

Enable installers to always run at startup. By default, installers are disabled.

```csharp
endpointConfiguration.EnableInstallers();
```

--------------------------------

### Enable installers via command-line argument

Source: https://docs.particular.net/nservicebus/operations/installers_core_7.md

Enables installers based on a command-line argument. If the argument "/runInstallers" is present, it enables installers, creates the endpoint (which runs installers but does not start the instance), and then exits the process.

```csharp
var runInstallers = Environment.GetCommandLineArgs().Any(x => string.Equals(x, "/runInstallers", StringComparison.OrdinalIgnoreCase));

if (runInstallers)
{
    endpointConfiguration.EnableInstallers();
    // This will run the installers but not start the instance.
    await Endpoint.Create(endpointConfiguration);
    Environment.Exit(0);
}
```

--------------------------------

### Enable installers based on machine name convention

Source: https://docs.particular.net/nservicebus/operations/installers.md

Enable installers based on a machine name convention. The example enables installers when the machine name does not end with "-PROD".

```csharp
if (!Environment.MachineName.EndsWith("-PROD"))
{
    endpointConfiguration.EnableInstallers();
}
```

--------------------------------

### Enable installers at startup

Source: https://docs.particular.net/nservicebus/operations/installers_core_7.md

Enables installers to run automatically at endpoint startup. The comment indicates that calling Endpoint.Start will run the installers.

```csharp
endpointConfiguration.EnableInstallers();

// this will run the installers
await Endpoint.Start(endpointConfiguration);
```

--------------------------------

### Run installers with externally managed container

Source: https://docs.particular.net/nservicebus/operations/installers_core_9.md

Runs installers when setup requires access to services provided via an externally managed dependency injection container. Provide the configured IServiceProvider to the installer API. The installer APIs always run installers, regardless of whether the endpoint has configured EnableInstallers.

```csharp
var endpointConfiguration = new EndpointConfiguration("my-endpoint");
// configure endpoint

var serviceCollection = new ServiceCollection();
// custom registrations

var installer = Installer.CreateInstallerWithExternallyManagedContainer(endpointConfiguration, serviceCollection);

var serviceProvider = serviceCollection.BuildServiceProvider();

await installer.Setup(serviceProvider);
```

--------------------------------

### Run container in setup mode with --setup

Source: https://docs.particular.net/servicecontrol/monitoring-instances/deployment/containers.md

Runs the container in setup mode to create required message queues and perform upgrade tasks. The container exits after setup; use --rm to auto-remove.

```shell
# Using docker run
docker run --rm {OPTIONS} particular/servicecontrol-monitoring --setup
```

--------------------------------

### Use PlatformRunMode.Run to skip setup

Source: https://docs.particular.net/nuget/Particular.Aspire.Hosting.ServicePlatform

Use WithRunMode(PlatformRunMode.Run) to start ServiceControl instances without performing setup, assuming queues and database structures already exist. This is useful in production where setup is performed separately.

```csharp
var error = platform.AddServiceControlErrorInstance("servicecontrol", serviceControlDb)
    .WithRunMode(PlatformRunMode.Run);

platform.AddServiceControlAuditInstance("audit", error, serviceControlDb)
    .WithRunMode(PlatformRunMode.Run);

platform.AddServiceControlMonitoringInstance("monitoring")
    .WithRunMode(PlatformRunMode.Run);
```

--------------------------------

### Install NServiceBus Host as Windows Service with Production and PerformanceCounters profiles

Source: https://docs.particular.net/nservicebus/hosting/nservicebus-host/profiles.md

Command to install the host as a Windows Service with the specified profiles. The profiles used during installation are saved and used every time the host starts.

```shell
.\NServiceBus.Host.exe /install nservicebus.production nservicebus.performancecounters
```
Tokens:
Raw