Operational Scripting

In order to provision or de-provision the resources required by an endpoint, the asb-transport command line (CLI) tool can be used.

The tool can be obtained from NuGet and installed using the following command:

dotnet tool install -g NServiceBus.Transport.AzureServiceBus.CommandLine

Once installed, the asb-transport command line tool will be available for use.

asb-transport <command> [options]

Available commands

endpoint create
endpoint subscribe
endpoint unsubscribe
queue create
queue delete

asb-transport endpoint create

Creates infrastructure for an endpoint -- input queue.

asb-transport endpoint create name
                              [--size]
                              [--partitioned]
                              [--forward-dlq-to]

options

-c | --connection-string : Overrides the environment variable 'AzureServiceBus_ConnectionString'

-n | --namespace : Sets the fully qualified namespace to connect with cached credentials, e.g., credentials from Azure PowerShell or CLI. This setting cannot be used in conjunction with the connection string setting.

-s | --size : Queue size in GB (defaults to 5)

-d | --delivery-count: Maximum delivery count until the message will be moved to the deadletter queue (defaults to int.Max)

-p | --partitioned: Enable partitioning

-h | --hierarchy-namespace: Sets the hierarchy namespace for prefixing destinations in the format <hierarchy-namespace>/<topic-or-queue> (available from version 6.1)

-f | --forward-dlq-to: Queue name to auto-forward dead-lettered messages to. The queue will be created if it does not exist. The resolved queue name cannot be the same as the endpoint queue.

asb-transport endpoint subscribe

Creates a new subscription for an endpoint.

asb-transport endpoint subscribe name topic
                              [--subscription]

Options

-c | --connection-string : Overrides the environment variable 'AzureServiceBus_ConnectionString'

-b | --subscription: Subscription name (defaults to endpoint name)

-h | --hierarchy-namespace: Sets the hierarchy namespace for prefixing destinations in the format <hierarchy-namespace>/<topic-or-queue> (available from version 6.1)

asb-transport endpoint unsubscribe

Deletes a subscription for an endpoint.

asb-transport endpoint unsubscribe name topic
                              [--subscription]

Options

-c | --connection-string : Overrides the environment variable 'AzureServiceBus_ConnectionString'

-b | --subscription: Subscription name (defaults to endpoint name)

-h | --hierarchy-namespace: Sets the hierarchy namespace for prefixing destinations in the format <hierarchy-namespace>/<topic-or-queue> (available from version 6.1)

asb-transport queue create

Create a queue using:

asb-transport queue create name
                              [--size]
                              [--partitioned]
                              [--forward-dlq-to]

options

-c | --connection-string : Overrides the environment variable 'AzureServiceBus_ConnectionString'

-s | --size: Queue size in GB (defaults to 5)

-d | --delivery-count: Maximum delivery count until the message will be moved to the deadletter queue (defaults to int.Max)

-p | --partitioned: Enable partitioning

-h | --hierarchy-namespace: Sets the hierarchy namespace for prefixing destinations in the format <hierarchy-namespace>/<topic-or-queue> (available from version 6.1)

-f | --forward-dlq-to: Queue name to auto-forward dead-lettered messages to. The queue will be created if it does not exist. The resolved queue name cannot be the same as the source queue.

See also the Azure CLI option --forward-dead-lettered-messages-to.

asb-transport queue delete

Delete a queue using:

asb-transport queue delete name

options

-c | --connection-string : Overrides the environment variable 'AzureServiceBus_ConnectionString'

-h | --hierarchy-namespace: Sets the hierarchy namespace for prefixing destinations in the format <hierarchy-namespace>/<topic-or-queue> (available from version 6.1)

Migration-specific commands

These commands are dedicated to endpoints that are configured with the migration topology for the purpose of migrating from the single-topic publishing approach (forwarding topology) to topic-per-event approach.

migration endpoint create
migration endpoint subscribe
migration endpoint unsubscribe
migration endpoint subscribe migrated
migration endpoint unsubscribe migrated

asb-transport migration endpoint create

Creates infrastructure for an endpoint: input queue, topic, and subscription.

asb-transport migration endpoint create name
                              [--size]
                              [--partitioned]
                              [--topic]
                              [--topic-to-publish-to] [--topic-to-subscribe-on]
                              [--subscription]
                              [--forward-dlq-to]

options

-c | --connection-string : Overrides the environment variable 'AzureServiceBus_ConnectionString'

-s | --size : Queue size in GB (defaults to 5)

-d | --delivery-count: Maximum delivery count until the message will be moved to the deadletter queue (defaults to int.Max)

-p | --partitioned: Enable partitioning

-t | --topic: Topic name (defaults to 'bundle-1')

-tp | --topic-to-publish-to: The topic name to publish to.

-ts | --topic-to-subscribe-on: The topic name to subscribe on.

-b | --subscription: Subscription name (defaults to endpoint name)

-h | --hierarchy-namespace: Sets the hierarchy namespace for prefixing destinations in the format <hierarchy-namespace>/<topic-or-queue> (available from version 6.1)

-f | --forward-dlq-to: Queue name to auto-forward dead-lettered messages to. The queue will be created if it does not exist. The resolved queue name cannot be the same as the endpoint queue.

The hierarchy namespace option shifts the migration endpoint consistently into the hierarchy meaning the endpoint name and topics will have the hierarchy name applied.

asb-transport migration endpoint subscribe

Creates a new subscription for an endpoint using single-topic approach.

asb-transport migration endpoint subscribe name event-type
                              [--topic]
                              [--subscription]
                              [--rule-name]

Options

-c | --connection-string : Overrides the environment variable 'AzureServiceBus_ConnectionString'

-t | --topic: Topic name to subscribe on (defaults to 'bundle-1')

-b | --subscription: Subscription name (defaults to endpoint name)

-r | --rule-name: Rule name (defaults to event type)

-h | --hierarchy-namespace: Sets the hierarchy namespace for prefixing destinations in the format <hierarchy-namespace>/<topic-or-queue> (available from version 6.1)

The hierarchy namespace option shifts the migration endpoint consistently into the hierarchy meaning the endpoint name and topics will have the hierarchy name applied.

asb-transport migration endpoint unsubscribe

Delete a subscription for an endpoint using single-topic approach.

asb-transport migration endpoint unsubscribe name event-type
                              [--topic]
                              [--subscription]
                              [--rule-name]

Options

-c | --connection-string : Overrides the environment variable 'AzureServiceBus_ConnectionString'

-t | --topic: Topic name to unsubscribe from (defaults to 'bundle-1')

-b | --subscription: Subscription name (defaults to endpoint name)

-r | --rule-name: Rule name (defaults to event type)

-h | --hierarchy-namespace: Sets the hierarchy namespace for prefixing destinations in the format / (available from version 6.1)

The hierarchy namespace option shifts the migration endpoint consistently into the hierarchy meaning the endpoint name and topics will have the hierarchy name applied.

asb-transport migration endpoint subscribe-migrated

Creates a new subscription for an endpoint using topic-per-event approach.

asb-transport migration endpoint subscribe-migrated name topic
                              [--subscription]

Options

-c | --connection-string : Overrides the environment variable 'AzureServiceBus_ConnectionString'

-b | --subscription: Subscription name (defaults to endpoint name)

-h | --hierarchy-namespace: Sets the hierarchy namespace for prefixing destinations in the format <hierarchy-namespace>/<topic-or-queue> (available from version 6.1)

The hierarchy namespace option shifts the migration endpoint consistently into the hierarchy meaning the endpoint name and topics will have the hierarchy name applied.

asb-transport migration endpoint unsubscribe-migrated

Deletes a subscription for an endpoint using topic-per-event approach.

asb-transport migration endpoint unsubscribe-migrated name topic
                              [--subscription]

Options

-c | --connection-string : Overrides the environment variable 'AzureServiceBus_ConnectionString'

-b | --subscription: Subscription name (defaults to endpoint name)

-h | --hierarchy-namespace: Sets the hierarchy namespace for prefixing destinations in the format <hierarchy-namespace>/<topic-or-queue> (available from version 6.1)

The hierarchy namespace option shifts the migration endpoint consistently into the hierarchy meaning the endpoint name and topics will have the hierarchy name applied.

Examples

Provisioning the audit and the error queues

asb-transport queue create audit -c "<connection-string>"
asb-transport queue create error -c "<connection-string>"

Using connection strings

asb-transport [command] [subcommand] -c "<connection-string>"

Using cached credentials

asb-transport [command] [subcommand] -n "somenamespace.servicebus.windows.net"

Provisioning endpoints

Create the topology for an endpoint named MyEndpoint:

asb-transport endpoint create MyEndpoint -c "<connection-string>"

Create the topology for an endpoint named MyEndpoint and forward dead-lettered messages to the error queue:

asb-transport endpoint create MyEndpoint --forward-dlq-to error -c "<connection-string>"

Create a queue and configure dead-letter forwarding to the error queue:

asb-transport queue create MyEndpoint --forward-dlq-to error -c "<connection-string>"

Subscribing to events (migration topology)

Subscribe MyOtherEndpoint to the event Contracts.Events.SomeEvent using the default settings:

asb-transport endpoint subscribe MyOtherEndpoint Contracts.Events.SomeEvent -c "<connection-string>"

Subscribe MyOtherEndpoint to the event Contracts.Events.SomeEvent and override the subscription name to be my-other-endpoint

asb-transport endpoint subscribe MyOtherEndpoint Contracts.Events.SomeEvent -s my-other-endpoint -c "<connection-string>"

Provisioning endpoints that use migration topology

Create the topology for an endpoint named MyEndpoint using the default settings:

asb-transport migration endpoint create MyEndpoint -c "<connection-string>"

Create migration topology and forward dead-lettered messages to the error queue:

asb-transport migration endpoint create MyEndpoint --forward-dlq-to error -c "<connection-string>"

Create the topology for an endpoint named MyEndpoint and override the topic name to be custom-topic and the subscription name to be my-endpoint:

asb-transport migration endpoint create MyEndpoint -t custom-topic -s my-endpoint -c "<connection-string>"

Create the topology for an endpoint named MyEndpoint and override the publish topic name to be custom-publish-topic and the subscription topic name to be custom-subscribe-topic:

asb-transport migration endpoint create MyEndpoint -tp custom-publish-topic -ts custom-subscribe-topic -c "<connection-string>"

Subscribing to events

Subscribe MyOtherEndpoint to the event Contracts.Events.SomeEvent using the default settings:

asb-transport migration endpoint subscribe MyOtherEndpoint Contracts.Events.SomeEvent -c "<connection-string>"

Subscribe MyOtherEndpoint to the event Contracts.Events.SomeEvent using the topic-per-event apprach (after migration):

asb-transport migration endpoint subscribe-migrated MyOtherEndpoint Contracts.Events.SomeEvent -c "<connection-string>"

Subscribe MyOtherEndpoint to the event Contracts.Events.SomeEvent and override the topic name to be custom-topic:

asb-transport migration endpoint subscribe MyOtherEndpoint Contracts.Events.SomeEvent -t custom-topic -c "<connection-string>"

Subscribe MyOtherEndpoint to the event Contracts.Events.SomeEvent and override the subscription name to be my-other-endpoint

asb-transport migration endpoint subscribe MyOtherEndpoint Contracts.Events.SomeEvent -s my-other-endpoint -c "<connection-string>"

Subscribe MyOtherEndpoint to the event Contracts.Events.SomeEvent and override the subscription rule name to be SomeEvent:

asb-transport migration endpoint subscribe MyOtherEndpoint Contracts.Events.SomeEvent -r SomeEvent -c "<connection-string>"

Operational Scripting