Specify the name of Track 1 SDK to avoid confusion with Track 0

sdk/servicebus/Azure.Messaging.ServiceBus/MigrationGuide.md

@@ -24,9 +24,9 @@ There were several areas of consistent feedback expressed across the Azure clien
 
 To try and improve the development experience across Azure services, including Service Bus, a set of uniform [design guidelines](https://azure.github.io/azure-sdk/general_introduction.html) was created for all languages to drive a consistent experience with established API patterns for all services. A set of [.NET-specific guidelines](https://azure.github.io/azure-sdk/dotnet_introduction.html) was also introduced to ensure that .NET clients have a natural and idiomatic feel that mirrors that of the .NET base class libraries. Further details are available in the guidelines for those interested.
 
-The modern Service Bus client library provides the ability to share in some of the cross-service improvements made to the Azure development experience, such as using the new `Azure.Identity` library to share a single authentication between clients and a unified diagnostics pipeline offering a common view of the activities across each of the client libraries. 
+The new Service Bus library `Azure.Messaging.ServiceBus` provides the ability to share in some of the cross-service improvements made to the Azure development experience, such as using the new `Azure.Identity` library to share a single authentication between clients and a unified diagnostics pipeline offering a common view of the activities across each of the client libraries. 
 
-While we believe that there is significant benefit to adopting the modern version of the Service Bus library, it is important to be aware that the legacy version has not been officially deprecated. It will continue to be supported with security and bug fixes as well as receiving some minor refinements. However, in the near future it will not be under active development and new features are unlikely to be added.
+While we believe that there is significant benefit to adopting the new Service Bus library `Azure.Messaging.ServiceBus`, it is important to be aware that the previous two versions `WindowsAzure.ServiceBus` and `Microsoft.Azure.ServiceBus` have not been officially deprecated. They will continue to be supported with security and bug fixes as well as receiving some minor refinements. However, in the near future they will not be under active development and new features are unlikely to be added to them.
 
 ## General changes
 
@@ -38,16 +38,16 @@ In the case of Service Bus, the modern client libraries have packages and namesp
 
 ### Client hierarchy
 
-In the interest of simplifying the API surface we've made a single top level client called `ServiceBusClient`, rather than one for each of queue, topic, subscription and session. This acts as the single entry point in contrast with multiple entry points from before. You can create senders and receivers off of this client to the queue/topic/subscription/session of your choice and start sending/receiving messages.
+In the interest of simplifying the API surface we've made a single top level client called `ServiceBusClient`, rather than one for each of queue, topic, subscription and session. This acts as the single entry point in contrast with multiple entry points from before. You can create senders and receivers from this client to the queue/topic/subscription/session of your choice and start sending/receiving messages.
 
 #### Approachability
-By having a single entry point, the `ServiceBusClient` helps with the discoverability of the API as you can explore all available features through methods off of a single client, as opposed to searching through documentation or exploring namespace for the types that you can instantiate. Whether sending or receiving, or using sessions or not, users will start their applications by constructing the same client.
+By having a single entry point, the `ServiceBusClient` helps with the discoverability of the API as you can explore all available features through methods from a single client, as opposed to searching through documentation or exploring namespace for the types that you can instantiate. Whether sending or receiving, using sessions or not, you will start your applications by constructing the same client.
 
 #### Consistency
-Having similar methods to create senders, receivers and receivers for individual sessions on the same client provides consistency and predictability on the various features of the library. We have attempted to have the session/non-session usage be as seamless as possible. This allows users to make less changes to their code when they want to move from sessions to non-sessions or the other way around.
+Having similar methods to create senders, receivers and receivers for individual sessions on the same client provides consistency and predictability on the various features of the library. We have attempted to have the session/non-session usage be as seamless as possible. This allows you to make less changes to your code when you want to move from sessions to non-sessions or the other way around.
 
-#### Resource usage
-By using a single top-level client, we can implicitly share a single AMQP connection for all operations that an application performs. In the previous library, connection sharing was implicit when using the `SessionClient`, but when using other clients, users would need to explicitly pass in a `ServiceBusConnection` object in order to share a connection. By making this sharing be implicit to a ServiceBusClient instance, we can help ensure that applications will not use multiple connections unless they explicitly opt in by creating multiple `ServiceBusClient` instances.
+#### Connection Pooling
+By using a single top-level client, we can implicitly share a single AMQP connection for all operations that an application performs. In the previous library `Microsoft.Azure.ServiceBus`, connection sharing was implicit when using the `SessionClient`, but when using other clients, you would need to explicitly pass in a `ServiceBusConnection` object in order to share a connection. By making this connection sharing be implicit to a `ServiceBusClient` instance, we can help ensure that applications will not use multiple connections unless they explicitly opt in by creating multiple `ServiceBusClient` instances.
 
 
 ### Client constructors
@@ -67,7 +67,7 @@ ServiceBusClient client = new ServiceBusClient(connectionString);
 
 ### Sending messages
 
-In v4, you could send messages either by using a `QueueClient` (or `TopicClient` if you are targetting a topic) or the `MessageSender`.
+Previously, in `Microsoft.Azure.ServiceBus`, you could send messages either by using a `QueueClient` (or `TopicClient` if you are targetting a topic) or the `MessageSender`.
 While the `QueueClient` supported the simple send operation, the `MessageSender` supported that and advanced scenarios like scheduling to send messages
 at a later time and cancelling such scheduled messages.
 
@@ -84,10 +84,10 @@ MessageSender sender = new MessageSender(connectionString, queueName);
 await sender.SendAsync(message);
 ```
 
-In v7, we combine all the send related features under a common class `ServiceBusSender` that you can create off of the top level client using the `CreateSender()` method.
+Now in `Azure.Messaging.ServiceBus`, we combine all the send related features under a common class `ServiceBusSender` that you can create from the top level client using the `CreateSender()` method which takes the queue or topic you want to target.
 This provides a one stop shop for all your send related needs. 
 
-While we continue to support sending bytes in the message, if you are working with strings, you can now create a message directly without having to convert it to bytes first.
+We continue to support sending bytes in the message. If you are working with strings, you can now create a message directly without having to convert it to bytes first.
 
 ```cs
 // create the client
@@ -103,10 +103,10 @@ ServiceBusMessage message = new ServiceBusMessage("Hello world!");
 await sender.SendMessageAsync(message);
 ```
 
-While we continue to support sending a list of messages in a single call, this feature has always had the potential to fail unexpectedly when the messages exceeded the size limit of the sender.
+The feature to send a list of messages in a single call was implemneted by batching all the messages into a single AMQP message and sending that to the service.
+While we continue to support this feature, it always had the potential to fail unexpectedly when the resulting batched AMQP message exceeded the size limit of the sender.
 To help with this, we now provide a safe way to batch multiple messages to be sent at once using the new `ServiceBusMessageBatch` class.
 
-
 ```cs
 ServiceBusMessageBatch messageBatch = await sender.CreateMessageBatchAsync();
 
@@ -128,7 +128,7 @@ await sender.SendMessagesAsync(messageBatch);
 
 ### Receiving messages
 
-In v4, you could receive messages either by using a `QueueClient` (or `SubscriptionClient` if you are targetting a subscription) or the `MessageReceiver`.
+Previously, in `Microsoft.Azure.ServiceBus`, you could receive messages either by using a `QueueClient` (or `SubscriptionClient` if you are targetting a subscription) or the `MessageReceiver`.
 
 While the `QueueClient` supported the simple push model where you could register message and error handlers/callbacks, the `MessageReceiver` provided you with ways to receive messages (both normal and deferred) in batches, settle messages and renew locks.
 
@@ -164,8 +164,9 @@ Console.WriteLine($"Received message with Body:{Encoding.UTF8.GetString(received
 await receiver.CompleteAsync(receivedMessage);
 ```
 
-In v7, we introduce the concept of a "processor" which takes your message and error handlers to provide you a simple way to get started with processing your messages.
-The concept of a "receiver" remains for users who need to have a more fine grained control over the receiving and settling messages.
+Now in `Azure.Messaging.ServiceBus`, we introduce the concept of a "processor" which takes your message and error handlers to provide you a simple way to get started with processing your messages. This provides a graceful shutdown via the `StopProcessingAsync` method which will ensure that no more messages will be received, but at the same time you can continue the prcoessing and settling the messages already in flight.
+
+The concept of a "receiver" remains for users who need to have a more fine grained control over the receiving and settling messages. The difference is that this is now created from the top-level `ServiceBusClient` via the `CreateReceiver()` method that would take the queue or subscription you want to target.
 
 ```cs
 // create the ServiceBusClient
@@ -201,13 +202,15 @@ await receiver.CompleteMessageAsync(receivedMessage);
 ```
 ### Working with sessions
 
-In v4, you had the below options to receive messages from a session enabled queue/subscription
+Previously, in `Microsoft.Azure.ServiceBus`, you had the below options to receive messages from a session enabled queue/subscription
 - Register message and error handlers using the `QueueClient.RegisterSessionHandler()` method to receive messages from an available set of sessions 
 - Use the `SessionClient.AcceptMessageSessionAsync()` method to get an instance of the `MessageSession` class that will be tied to a given sessionId or to the next available session if no sessionId is provided.
 
 While the first option is similar to what you would do in a non session scenario, the second that allows you finer grained control is very different from any other pattern used in the library.
 
-In v7, we simplfify this by giving session variants of the same methods and classes that are available when working with queues/subscriptions that do not have sessions enabled.
+Now in `Azure.Messaging.ServiceBus`, we simplfify this by giving session variants of the same methods and classes that are available when working with queues/subscriptions that do not have sessions enabled.
+
+The below code snippet shows you the session variation of the "processor".
 
 ```cs
 // create a processor to receive events from the next available session
@@ -228,7 +231,7 @@ var options = new ServiceBusSessionProcessorOptions
 ServiceBusProcessor processor = client.CreateSessionProcessor(queueName);
 ```
 
-You have similar options when working with the receivers. Please note that creating a session receiver is an async operation because the library will need to get a lock on the session by connecting to the service first.
+The below code snippet shows you the session variation of the "receiver". Please note that creating a session receiver is an async operation because the library will need to get a lock on the session by connecting to the service first.
 
 ```cs
 // create a receiver to receive events from the next available session