Migration Guide?

[Duncanduncability]

Hi, I'm looking for advice for how to migrate from v6.8.1 to the new v7. Any idea when new docs and examples will be available?

[lukebakken]

Hello, thanks for your interest.

As of now, the best examples are the demo applications and test suites. I'm in the process of updating the tutorial code as well as the tutorials on the website.

In short, though, these are the main changes:

• Rename IModel to IChannel everywhere.
• Correctly use async / await with the updated API.
• If you are using publisher confirmations, the library now efficiently tracks them for you. See this code for an example.
• Create BasicProperties using new instead of the old way.

[michaelklishin]

Yay, tutorial 7 for .NET is coming :D

[mgroetan]

I've found that the "EventingBasicConsumer" class has been renamed to the not so logically "AsyncEventingBasicConsumer".

[lukebakken]

Yes, we followed TPL guidelines to ensure that methods and other entities use the Async suffix or (in this case), prefix.

[lukebakken]

@Duncanduncability - I just finished updating and merging the tutorial code - https://github.com/rabbitmq/rabbitmq-tutorials/tree/main/dotnet

[lechu445]

The other change worth mentioning in the migration guide is when you used IModel.ConfirmSelect() now you should set CreateChannelOptions.PublisherConfirmationsEnabled to true in IConnection.CreateChannelAsync.

This change was introduced in #1687.

[eithe]

I am trying to update our tests that uses Moq, Xunit and FluentAssertions, but QueueDeclareAsync is now an IChannel extension method which makes it more difficult to mock. Was this by intention?

public class RabbitMqClientTest
{
    private (Mock<IRabbitMqConnection>, IMessageQueue) GetMocks()
    {
        var mockRabbitMqConnection = new Mock<IRabbitMqConnection>();
        var mockChannel = new Mock<IChannel>();
        var mockProperties = new Mock<IBasicProperties>();
        mockChannel.Setup(x => x.IsOpen).Returns(true);
        mockChannel.Setup(x => x.GetNextPublishSequenceNumberAsync(It.IsAny<CancellationToken>())).ReturnsAsync(1UL);
        mockChannel.Setup(x => x.QueueDeclareAsync(It.IsAny<string>(), It.IsAny<bool>(), It.IsAny<bool>(), It.IsAny<bool>(), It.IsAny<IDictionary<string, object>>(), false, It.IsAny<CancellationToken>()))
            .ReturnsAsync(new QueueDeclareOk("test_queue", 1, 1));
        mockChannel.Setup(x => x.BasicAckAsync(It.IsAny<ulong>(), It.IsAny<bool>(), It.IsAny<CancellationToken>())).Returns(new ValueTask());
        mockChannel.SetupAdd(x => x.BasicAcksAsync += It.IsAny<AsyncEventHandler<BasicAckEventArgs>>());
        mockChannel.SetupAdd(x => x.BasicNacksAsync += It.IsAny<AsyncEventHandler<BasicNackEventArgs>>());
        mockChannel.Setup(x => x.BasicPublishAsync(It.IsAny<string>(), It.IsAny<string>(), It.IsAny<bool>(), It.IsAny<BasicProperties>(), It.IsAny<ReadOnlyMemory<byte>>(), It.IsAny<CancellationToken>())).Returns(new ValueTask());
        mockChannel.Setup(x => x.BasicConsumeAsync(It.IsAny<string>(), It.IsAny<bool>(), It.IsAny<string>(), It.IsAny<bool>(), It.IsAny<bool>(),
            It.IsAny<IDictionary<string, object>>(), It.IsAny<IAsyncBasicConsumer>(), It.IsAny<CancellationToken>())).ReturnsAsync("test_consumer");
        mockRabbitMqConnection.Setup(x => x.Channel).Returns(mockChannel.Object);
        var sut = new RabbitMqClient(mockRabbitMqConnection.Object, Mock.Of<ILogger<RabbitMqClient>>(), Mock.Of<IRedisClient>());
        return (mockRabbitMqConnection, sut);
    }

    private IMessageQueue GetMessageQueue()
    {
        var mocks = GetMocks();
        IMessageQueue sut = mocks.Item2;
        return sut;
    }

    [Fact]
    public void CanInstantiateClient()
    {
        var mocks = GetMocks();
        IRabbitMqConnection rmqc = mocks.Item1.Object;
        rmqc.Should().NotBeNull();
        IMessageQueue sut = mocks.Item2;
        sut.Should().NotBeNull();
        sut.Should().BeOfType<RabbitMqClient>();
    }

    [Fact]
    public async Task CanProduce()
    {
        var sut = GetMessageQueue();
        var result = await sut.Produce(MessageConstants.TestExchange, new Message<string> { Caller = "test", Content = "Test string", Id = Guid.NewGuid() }, false);

        result.Should().BeOfType<MessageQueueResult>();
        result.IsError.Should().BeFalse();
        result.SequenceNumber.Should().Be(1);
    }

    [Fact]
    public async void CanSetupConsumer()
    {
        var sut = GetMessageQueue();
        var result = await sut.Consume<string>(MessageConstants.TestExchange, MessageConstants.TestQueue, DoWork);
        result.Should().NotBeNull();
        result.Should().Be("test_consumer");
    }

    private async Task<bool> DoWork<T>(IMessage<T> message, CancellationToken cancellationToken)
    {
        message.Should().NotBeNull();
        return true;
    }
}

Which results in

System.NotSupportedException : Unsupported expression: x => x.QueueDeclareAsync(It.IsAny<string>(), It.IsAny<bool>(), It.IsAny<bool>(), It.IsAny<bool>(), It.IsAny<IDictionary<string, object>>(), False, It.IsAny<CancellationToken>())
Extension methods (here: IChannelExtensions.QueueDeclareAsync) may not be used in setup / verification expressions.

[lukebakken]

Use IChannel.QueueDeclareAsync - https://github.com/rabbitmq/rabbitmq-dotnet-client/blob/v7.0.0/projects/RabbitMQ.Client/IChannel.cs#L341-L354

[lechu445]

I'm looking for advice for how to migrate from v6.8.1 to the new v7

@Duncanduncability the migration guide you can find here https://github.com/rabbitmq/rabbitmq-dotnet-client/blob/main/v7-MIGRATION.md

[michaelklishin]

And everyone is welcome to contribute to it :)

[lechu445]

Some changes that I found during migration:

• all IBasicConsumer should be replaced with IAsyncBasicConsumer (IMO this breaking change was unnecessary)
• all IModel should be replaced with IChannel
• IChannel does not contain BasicRecoverOk event that was existing in IModel
• for AsyncEventingBasicConsumer all events now have -Async suffix (example ShutdownAsync)
• AsyncEventingBasicConsumer has removed ConsumerCancelled event
• BasicDeliverEventArgs changed from property initialization to constructor initialization
• IChannel.BasicPublishAsync takes a new parameter mandatory

[michaelklishin]

BasicRecoverOk can be added back but basic.recover has had no real purpose in the protocol for over a decade. You arguably should stop using it instead.

[lukebakken]

basic.recover has had no real purpose in the protocol for over a decade

That's why I removed BasicRecoverOk. I'll make a note about it. Thank you for following up @lechu445. How has version 7 been performing for you?

[lechu445]

I have a low throughput app therefore I din't observe any significant performance gain. I had no issues so far. I am waiting for release HealthChecks.RabbitMQ with the upgraded version Xabaril/AspNetCore.Diagnostics.HealthChecks#2323.

[lechu445]

It is also not clear how to replace IModel.WaitForConfirmsOrDie with provided timeout. Should it be set to IChannel.ContinuationTimeout or is it a different thing?

I found here #1234 (comment) only encougare to replace IModel.WaitForConfirmsOrDie with publisher confirms but its documentation does not mention about the timeout.

[lukebakken]

In the 6.x library, IModel.WaitForConfirmsOrDie depends on publisher confirmations - you can't call IModel.WaitForConfirmsOrDie without first having called IModel.ConfirmSelect.

In version 7, you enable publisher confirmations when you create the channel, via CreateChannelOptions, then, when you call BasicPublishAsync, pass a CancellationToken with your desired timeout value for receiving the single (or multiple) confirmations.

Please see this example code that I put together to address this comment.

I will make a note to clarify how to set a confirmation timeout in version 7 of this library.

[niemyjski]

This change is kind of confusing looking at the 7.0 breaking changes.

_factory = new ConnectionFactory
        {
            Uri = new Uri(options.ConnectionString),
            AutomaticRecoveryEnabled = true,
            DispatchConsumersAsync = true
        };

DispatchConsumersAsync where did this get moved to now?

[lukebakken]

DispatchConsumersAsync is no longer necessary, as all consumers are async in version 7. Thanks for pointing this out.

[ZajacPiotr98]

Hello.

Is this appropriate to pass cancellation token to the IChannel BasicConsumeAsync or any other method that invokes ModelSendAsync? When Cancellation request and task cancelled exception is thrown while Connection class is processing an action in the MainLoop, then connection is closing
CloseReason: AMQP close-reason, initiated by Library, code=541, text='A task was canceled.', classId=0, methodId=0, exception=System.Threading.Tasks.TaskCanceledException: A task was canceled. at RabbitMQ.Client.Impl.BasicConsumeAsyncRpcContinuation.HandleCommandAsync(IncomingCommand cmd) at RabbitMQ.Client.Impl.Channel.HandleCommandAsync(IncomingCommand cmd, CancellationToken cancellationToken) at RabbitMQ.Client.Framing.Connection.ProcessFrameAsync(InboundFrame frame, CancellationToken cancellationToken) at RabbitMQ.Client.Framing.Connection.ReceiveLoopAsync(CancellationToken mainLoopCancellationToken) at RabbitMQ.Client.Framing.Connection.MainLoop()

[lukebakken]

Is this appropriate to pass cancellation token to the IChannel BasicConsumeAsync or any other method that invokes ModelSendAsync?

Yes you should be able to do this without closing the connection. Thanks for reporting the issue.

[lukebakken]

#1750

[ZajacPiotr98]

I think passing already cancelled cancellation token will trigger exception already on the await _rpcSemaphore.WaitAsync(k.CancellationToken). The problem occurs when it's passed to the Connection

[lukebakken]

@ZajacPiotr98 would you mind adding that comment to the issue itself, and continuing all discussion there? Thank you.

#1750

[gokcengintertech]

Maybe it's just me but I haven't had a clear understanding of how to replace those structures in 7.0.0?

• WaitForConfirms / ConfirmSelect
• ConsumerCancelled

Especially when it comes to WaitForConfirms, I was able to configure the client while sending a message in 6.x and now it seems it's moved to CreateChannelOptions so I kind of feel it can only be configured per channel not the message. Please correct me if I'm wrong there.

[lukebakken]

it can only be configured per channel not the message

It has always been per-channel. In 6.x you could only call WaitForConfirms if ConfirmSelect had been called on the channel first.

When the channel has confirmations enabled, and you await the result of BasicPublishAsync you are awaiting the confirmation.

See this comment and linked code.

As for ConsumerCancelled, it appears we re-named that event:

https://github.com/search?q=repo%3Arabbitmq%2Frabbitmq-dotnet-client%20ConsumerCancelled&type=code

https://github.com/rabbitmq/rabbitmq-dotnet-client/blob/main/projects/Test/Integration/TestAsyncConsumerCancelNotify.cs#L77-L86

[jehrenzweig-captionhealth]

I'm trying to figure out how to upgrade from 6.8.1 to 7.0.0, & I could use some pointers about how to replace references to the following:

• IBasicPublishBatch interface
• ConnectionFactory.DispatchConsumersAsync property
• IModel.CreateBasicPublishBatch() method

[lukebakken]

• v7 Client Performance Degraded vs v6 with MassTransit #1721 (comment)
• Migration Guide? #1720 (comment)

[jehrenzweig-captionhealth]

Thank you!