[Event Hubs] Improve Processor Documentation (Azure#27183)

* [Event Hubs] Improve Processor Documentation

The focus of these changes is to clarify that the Azure Storage container
used with the processor must exist and will not be implicitly created.

Author: jsquire

sdk/eventhub/Azure.Messaging.EventHubs.Processor/CHANGELOG.md

@@ -18,6 +18,8 @@ Thank you to our developer community members who helped to make the Event Hubs c
 
 - Remove allocations from Event Source logging by introducing `WriteEvent` overloads to handle cases that would otherwise result in boxing to `object[]` via params array.  _(A community contribution, courtesy of [danielmarbach](https://github.com/danielmarbach))_
 
+- Enhanced README documentation to call attention to the need for the Azure Storage container used with the processor to exist, and highlight that it will not be implicitly created.
+
 ## 5.7.0-beta.3 (2022-02-09)
 
 ### Features Added

sdk/eventhub/Azure.Messaging.EventHubs.Processor/README.md

@@ -20,7 +20,9 @@ The Event Processor client library is a companion to the Azure Event Hubs client
 
 - **Event Hubs namespace with an Event Hub:** To interact with Azure Event Hubs, you'll also need to have a namespace and Event Hub available.  If you are not familiar with creating Azure resources, you may wish to follow the step-by-step guide for [creating an Event Hub using the Azure portal](https://docs.microsoft.com/azure/event-hubs/event-hubs-create).  There, you can also find detailed instructions for using the Azure CLI, Azure PowerShell, or Azure Resource Manager (ARM) templates to create an Event Hub.
 
-- **Azure Storage account with blob storage:** To persist checkpoints as blobs in Azure Storage, you'll need to have an Azure Storage account with blobs available.  If you are not familiar with Azure Storage accounts, you may wish to follow the step-by-step guide for [creating a storage account using the Azure portal](https://docs.microsoft.com/azure/storage/common/storage-quickstart-create-account?toc=%2Fazure%2Fstorage%2Fblobs%2Ftoc.json&tabs=azure-portal).  There, you can also find detailed instructions for using the Azure CLI, Azure PowerShell, or Azure Resource Manager (ARM) templates to create storage accounts.
+- **Azure Storage account with blob storage:** To persist checkpoints and govern ownership in Azure Storage, you'll need to have an Azure Storage account with blobs available.  If you are not familiar with Azure Storage accounts, you may wish to follow the step-by-step guide for [creating a storage account using the Azure portal](https://docs.microsoft.com/azure/storage/common/storage-quickstart-create-account?toc=%2Fazure%2Fstorage%2Fblobs%2Ftoc.json&tabs=azure-portal).  There, you can also find detailed instructions for using the Azure CLI, Azure PowerShell, or Azure Resource Manager (ARM) templates to create storage accounts.
+
+- **Azure Storage blob container:** Checkpoint and ownership data in Azure Storage will be written to blobs in a specific container.  The `EventProcessorClient` requires an existing container and will not implicitly create one to help guard against accidental misconfiguration.  If you are not familiar with Azure Storage containers, you may wish to refer to the documentation on [managing containers](https://docs.microsoft.com/azure/storage/blobs/storage-blob-container-create?tabs=dotnet).  There, you can find detailed instructions for using .NET, the Azure CLI, or Azure PowerShell to create a container.
 
 - **C# 8.0:** The Azure Event Hubs client library makes use of new features that were introduced in C# 8.0.  In order to take advantage of the C# 8.0 syntax, it is recommended that you compile using the [.NET Core SDK](https://dotnet.microsoft.com/download) 3.0 or higher with a [language version](https://docs.microsoft.com/dotnet/csharp/language-reference/configure-language-version#override-a-default) of `latest`.  It is also possible to compile with the .NET Core SDK 2.1.x using a language version of `preview`.   
 
@@ -85,9 +87,14 @@ We guarantee that all client instance methods are thread-safe and independent of
 
 ### Creating an Event Processor client
 
-Since the `EventProcessorClient` has a dependency on Azure Storage blobs for persistence of its state, you'll need to provide a `BlobContainerClient` for the processor, which has been configured for the storage account and container that should be used.
+Since the `EventProcessorClient` has a dependency on Azure Storage blobs for persistence of its state, you'll need to provide a `BlobContainerClient` for the processor, which has been configured for the storage account and container that should be used.  The container used to configure the `EventProcessorClient` must exist.
+
+Because the `EventProcessorClient` has no way of knowing the intent of specifying a container that does not exist, it will not implicitly create the container.  This acts as a guard against a misconfigured container causing a rogue processor unable to share ownership and interfering with other processors in the consumer group.
 
 ```C# Snippet:EventHubs_Processor_ReadMe_Create
+// The container specified when creating the BlobContainerClient must exist; it will
+// not be implicitly created.
+
 var storageConnectionString = "<< CONNECTION STRING FOR THE STORAGE ACCOUNT >>";
 var blobContainerName = "<< NAME OF THE BLOB CONTAINER >>";
 
@@ -96,14 +103,7 @@ var eventHubName = "<< NAME OF THE EVENT HUB >>";
 var consumerGroup = "<< NAME OF THE EVENT HUB CONSUMER GROUP >>";
 
 var storageClient = new BlobContainerClient(storageConnectionString, blobContainerName);
-
-var processor = new EventProcessorClient
-(
-    storageClient,
-    consumerGroup,
-    eventHubsConnectionString,
-    eventHubName
-);
+var processor = new EventProcessorClient(storageClient, consumerGroup, eventHubsConnectionString, eventHubName);
 ```
 
 ### Configure the event and error handlers

sdk/eventhub/Azure.Messaging.EventHubs.Processor/tests/Snippets/ReadMeSnippetsLiveTests.cs

@@ -34,6 +34,9 @@ public void Create()
             #region Snippet:EventHubs_Processor_ReadMe_Create
 
 #if SNIPPET
+            // The container specified when creating the BlobContainerClient must exist; it will
+            // not be implicitly created.
+
             var storageConnectionString = "<< CONNECTION STRING FOR THE STORAGE ACCOUNT >>";
             var blobContainerName = "<< NAME OF THE BLOB CONTAINER >>";
 
@@ -49,14 +52,7 @@ public void Create()
 #endif
 
             var storageClient = new BlobContainerClient(storageConnectionString, blobContainerName);
-
-            var processor = new EventProcessorClient
-            (
-                storageClient,
-                consumerGroup,
-                eventHubsConnectionString,
-                eventHubName
-            );
+            var processor = new EventProcessorClient(storageClient, consumerGroup, eventHubsConnectionString, eventHubName);
 
             #endregion
         }