[Event Hubs Client] Processor Samples Overhaul (#16878)

The focus of these changes is to overhaul the samples, converting the
old-style code samples into markdown while extending them with more
context, better detail, and additional scenarios.  The content
enhancements have taken into account feedback from customers since GA
in the form of issues, Stack Overflow questions, and direct conversations.

A follow-up set of work continue adding onto these with some full
end-to-end scenarios as stand-alone samples.

sdk/eventhub/Azure.Messaging.EventHubs.Processor/Azure.Messaging.EventHubs.Processor.sln

@@ -7,14 +7,10 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Azure.Messaging.EventHubs.P
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Azure.Messaging.EventHubs.Processor.Tests", "tests\Azure.Messaging.EventHubs.Processor.Tests.csproj", "{CD47A186-4375-488B-92C8-C3225BEBE417}"
 EndProject
-Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Azure.Messaging.EventHubs.Processor.Samples", "samples\Azure.Messaging.EventHubs.Processor.Samples.csproj", "{89C3D506-E47C-4034-A3AA-2BD05D8B1EA5}"
-EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Azure.Core.TestFramework", "..\..\core\Azure.Core.TestFramework\src\Azure.Core.TestFramework.csproj", "{7DFF0E65-DC9A-410D-9A11-AD6A06860FE1}"
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "External", "External", "{797FF941-76FD-45FD-AC17-A73DFE2BA621}"
 EndProject
-Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Azure.Messaging.EventHubs", "..\Azure.Messaging.EventHubs\src\Azure.Messaging.EventHubs.csproj", "{C1A4524B-CFFB-48C8-BA16-8E833DBAA1CD}"
-EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -29,25 +25,16 @@ Global
 		{CD47A186-4375-488B-92C8-C3225BEBE417}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{CD47A186-4375-488B-92C8-C3225BEBE417}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{CD47A186-4375-488B-92C8-C3225BEBE417}.Release|Any CPU.Build.0 = Release|Any CPU
-		{89C3D506-E47C-4034-A3AA-2BD05D8B1EA5}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
-		{89C3D506-E47C-4034-A3AA-2BD05D8B1EA5}.Debug|Any CPU.Build.0 = Debug|Any CPU
-		{89C3D506-E47C-4034-A3AA-2BD05D8B1EA5}.Release|Any CPU.ActiveCfg = Release|Any CPU
-		{89C3D506-E47C-4034-A3AA-2BD05D8B1EA5}.Release|Any CPU.Build.0 = Release|Any CPU
 		{7DFF0E65-DC9A-410D-9A11-AD6A06860FE1}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
 		{7DFF0E65-DC9A-410D-9A11-AD6A06860FE1}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{7DFF0E65-DC9A-410D-9A11-AD6A06860FE1}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{7DFF0E65-DC9A-410D-9A11-AD6A06860FE1}.Release|Any CPU.Build.0 = Release|Any CPU
-		{C1A4524B-CFFB-48C8-BA16-8E833DBAA1CD}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
-		{C1A4524B-CFFB-48C8-BA16-8E833DBAA1CD}.Debug|Any CPU.Build.0 = Debug|Any CPU
-		{C1A4524B-CFFB-48C8-BA16-8E833DBAA1CD}.Release|Any CPU.ActiveCfg = Release|Any CPU
-		{C1A4524B-CFFB-48C8-BA16-8E833DBAA1CD}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
 	EndGlobalSection
 	GlobalSection(NestedProjects) = preSolution
 		{7DFF0E65-DC9A-410D-9A11-AD6A06860FE1} = {797FF941-76FD-45FD-AC17-A73DFE2BA621}
-		{C1A4524B-CFFB-48C8-BA16-8E833DBAA1CD} = {797FF941-76FD-45FD-AC17-A73DFE2BA621}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {44BD3BD5-61DF-464D-8627-E00B0BC4B3A3}

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

@@ -10,7 +10,7 @@ The Event Processor client library is a companion to the Azure Event Hubs client
 
 - Managing checkpoints and state for processing in a durable manner using Azure Storage blobs as the underlying data store.
 
-[Source code](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/eventhub/Azure.Messaging.EventHubs.Processor/src) | [Package (NuGet)](https://www.nuget.org/packages/Azure.Messaging.EventHubs.Processor/) | [API reference documentation](https://docs.microsoft.com/dotnet/api/azure.messaging.eventhubs?view=azure-dotnet) | [Product documentation](https://docs.microsoft.com/azure/event-hubs/)
+[Source code](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/eventhub/Azure.Messaging.EventHubs.Processor/src) | [Package (NuGet)](https://www.nuget.org/packages/Azure.Messaging.EventHubs.Processor/) | [API reference documentation](https://docs.microsoft.com/dotnet/api/azure.messaging.eventhubs?view=azure-dotnet) | [Product documentation](https://docs.microsoft.com/azure/event-hubs/)
 
 ## Getting started
 
@@ -46,11 +46,11 @@ dotnet add package Azure.Messaging.EventHubs.Processor
 
 #### Obtain an Event Hubs connection string
 
-For the event processor client to interact with an Event Hub, it will need to understand how to connect and authorize with it.  The easiest means for doing so is to use a connection string, which is created automatically when creating an Event Hubs namespace.  If you aren't familiar with shared access policies in Azure, you may wish to follow the step-by-step guide to [get an Event Hubs connection string](https://docs.microsoft.com/azure/event-hubs/event-hubs-get-connection-string).
+For the Event Hubs client library to interact with an Event Hub, it will need to understand how to connect and authorize with it.  The easiest means for doing so is to use a connection string, which is created automatically when creating an Event Hubs namespace.  If you aren't familiar with using connection strings with Event Hubs, you may wish to follow the step-by-step guide to [get an Event Hubs connection string](https://docs.microsoft.com/azure/event-hubs/event-hubs-get-connection-string).
 
 #### Obtain an Azure Storage connection string
 
-For the event processor client to make use of Azure Storage blobs, it will need to understand how to connect to a storage account and authorize with it.  The most straightforward method of doing so is to use a connection string, which is generated at the time that the storage account is created.  If you aren't familiar with storage accounts in Azure, you may wish to follow the step-by-step guide to [configure Azure Storage connection strings](https://docs.microsoft.com/azure/storage/common/storage-configure-connection-string).
+For the event processor client to make use of Azure Storage blobs for checkpointing, it will need to understand how to connect to a storage account and authorize with it.  The most straightforward method of doing so is to use a connection string, which is generated at the time that the storage account is created.  If you aren't familiar with storage account connection string authorization in Azure, you may wish to follow the step-by-step guide to [configure Azure Storage connection strings](https://docs.microsoft.com/azure/storage/common/storage-configure-connection-string).
 
 ## Key concepts
 
@@ -74,7 +74,7 @@ Since the `EventProcessorClient` has a dependency on Azure Storage blobs for per
 
 ```C# Snippet:EventHubs_Processor_ReadMe_Create
 var storageConnectionString = "<< CONNECTION STRING FOR THE STORAGE ACCOUNT >>";
-var blobContainerName = "<< NAME OF THE BLOBS CONTAINER >>";
+var blobContainerName = "<< NAME OF THE BLOB CONTAINER >>";
 
 var eventHubsConnectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
 var eventHubName = "<< NAME OF THE EVENT HUB >>";
@@ -97,7 +97,7 @@ In order to use the `EventProcessorClient`, handlers for event processing and er
 
 ```C# Snippet:EventHubs_Processor_ReadMe_ConfigureHandlers
 var storageConnectionString = "<< CONNECTION STRING FOR THE STORAGE ACCOUNT >>";
-var blobContainerName = "<< NAME OF THE BLOBS CONTAINER >>";
+var blobContainerName = "<< NAME OF THE BLOB CONTAINER >>";
 
 var eventHubsConnectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
 var eventHubName = "<< NAME OF THE EVENT HUB >>";
@@ -147,7 +147,7 @@ var cancellationSource = new CancellationTokenSource();
 cancellationSource.CancelAfter(TimeSpan.FromSeconds(45));
 
 var storageConnectionString = "<< CONNECTION STRING FOR THE STORAGE ACCOUNT >>";
-var blobContainerName = "<< NAME OF THE BLOBS CONTAINER >>";
+var blobContainerName = "<< NAME OF THE BLOB CONTAINER >>";
 
 var eventHubsConnectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
 var eventHubName = "<< NAME OF THE EVENT HUB >>";
@@ -189,9 +189,9 @@ finally
 
 ### Using an Active Directory principal with the Event Processor client
 
-The [Azure Identity library](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/identity/Azure.Identity/README.md) provides Azure Active Directory authentication support which can be used for the Azure client libraries, including Event Hubs and Azure Storage.
+The [Azure Identity library](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/identity/Azure.Identity/README.md) provides Azure Active Directory authentication support which can be used for the Azure client libraries, including Event Hubs and Azure Storage.
 
-To make use of an Active Directory principal, one of the available identity tokens from the `Azure.Identity` library is also provided when creating the Event Processor client.  In addition, the fully qualified Event Hubs namespace and the name of the desired Event Hub are supplied in lieu of the Event Hubs connection string.
+To make use of an Active Directory principal, one of the available credentials from the `Azure.Identity` library is specified when creating the Event Hubs client.  In addition, the fully qualified Event Hubs namespace and the name of desired Event Hub are supplied in lieu of the Event Hubs connection string.
 
 To make use of an Active Directory principal with Azure Storage blob containers, the fully qualified URL to the container must be provided when creating the storage client.  Details about the valid URI formats for accessing Blob storage may be found in [Naming and Referencing Containers, Blobs, and Metadata](https://docs.microsoft.com/rest/api/storageservices/Naming-and-Referencing-Containers--Blobs--and-Metadata#resource-uri-syntax).  
 
@@ -229,7 +229,7 @@ The Event Processor client makes every attempt to be resilient in the face of ex
 
 In order to allow developers the opportunity to inspect and react to exceptions that occur within the Event Processor client operations, they are surfaced via the `ProcessError` event.  The arguments for this event offer details about the exception and the context in which it was observed.  Developers may perform normal operations on the Event Processor client from within this event handler, such as stopping and/or restarting it in response to errors, but may not otherwise influence the processor's exception behavior.  
 
-For a basic example of implementing the error handler, please see the sample: [Manage the Event Processor when an error is encountered](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/eventhub/Azure.Messaging.EventHubs.Processor/samples/Sample07_RestartProcessingOnError.cs).
+For a basic example of implementing the error handler, please see the sample: [Event Processor Handlers](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/eventhub/Azure.Messaging.EventHubs.Processor/samples/Sample03_EventProcessorHandlers.md#process-error).
 
 #### Exceptions in event handlers
 
@@ -239,7 +239,7 @@ The Event Processor client will not attempt to detect exceptions in developer co
 
 #### Exception details
 
-For detailed information about exceptions that may occur, please refer to the Event Hubs client library [README]( https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/eventhub/Azure.Messaging.EventHubs/README.md#event-hubs-exception) and the service documentation for [Event Hubs messaging exceptions](https://docs.microsoft.com/azure/event-hubs/event-hubs-messaging-exceptions). 
+For detailed information about exceptions that may occur, please refer to the Event Hubs client library [README]( https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/eventhub/Azure.Messaging.EventHubs/README.md#event-hubs-exception) and the service documentation for [Event Hubs messaging exceptions](https://docs.microsoft.com/azure/event-hubs/event-hubs-messaging-exceptions). 
 
 ### Logging and diagnostics