[event-hubs] migrate samples to v2

sdk/eventhub/event-hubs/migrationguide.md

@@ -67,11 +67,11 @@ allowing the `EventHubConsumerClient` to be the single point of entry for receiv
 
 ### Client constructors
 
-| In v2                                             | Equivalent in v5                                                 | Sample                                                                                                                                                                                                                                                                   |
-| ------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `EventHubClient.createFromConnectionString()`     | `new EventHubProducerClient()` or `new EventHubConsumerClient()` | [receiveEvents](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/eventhub/event-hubs/samples/typescript/src/receiveEvents.ts), [sendEvents](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/eventhub/event-hubs/samples/typescript/src/sendEvents.ts) |
-| `EventHubClient.createFromAadTokenCredentials()`  | `new EventHubProducerClient()` or `new EventHubConsumerClient()` | [usingAadAuth](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/eventhub/event-hubs/samples/typescript/src/usingAadAuth.ts)                                                                                                                                     |
-| `EventProcessorHost.createFromConnectionString()` | `new EventHubConsumerClient(..., checkpointStore)`               | [receiveEventsUsingCheckpointStore](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/eventhub/eventhubs-checkpointstore-blob/samples/v1/typescript/src/receiveEventsUsingCheckpointStore.ts)                                                                    |
+| In v2                                             | Equivalent in v5                                                 | Sample                                                                                                                                                                                                                                                                     |
+| ------------------------------------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `EventHubClient.createFromConnectionString()`     | `new EventHubProducerClient()` or `new EventHubConsumerClient()` | [receiveEvents](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/eventhub/event-hubs/samples/v5/typescript/src/receiveEvents.ts), [sendEvents](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/eventhub/event-hubs/samples/v5/typescript/src/sendEvents.ts) |
+| `EventHubClient.createFromAadTokenCredentials()`  | `new EventHubProducerClient()` or `new EventHubConsumerClient()` | [usingAadAuth](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/eventhub/event-hubs/samples/v5/typescript/src/usingAadAuth.ts)                                                                                                                                      |
+| `EventProcessorHost.createFromConnectionString()` | `new EventHubConsumerClient(..., checkpointStore)`               | [receiveEventsUsingCheckpointStore](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/eventhub/eventhubs-checkpointstore-blob/samples/v1/typescript/src/receiveEventsUsingCheckpointStore.ts)                                                                        |
 
 Other noteworthy changes:
 
@@ -87,9 +87,9 @@ This and the need to support improvements to the algorithm used for managing par
 
 ### Sending events
 
-| In v2                              | Equivalent in v5                               | Sample                                                                                                                           |
-| ---------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `EventHubClient.sendBatch(events)` | `EventHubProducerClient.sendBatch(eventBatch)` | [sendEvents](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/eventhub/event-hubs/samples/typescript/src/sendEvents.ts) |
+| In v2                              | Equivalent in v5                               | Sample                                                                                                                            |
+| ---------------------------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `EventHubClient.sendBatch(events)` | `EventHubProducerClient.sendBatch(eventBatch)` | [sendEvents](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/eventhub/event-hubs/samples/v5/typescript/src/sendEvents.ts) |
 
 Other noteworthy changes:
 
@@ -174,9 +174,9 @@ if (batch.count > 0) {
 
 ### Receiving events
 
-| In v2                                                          | Equivalent in v5                     | Sample                                                                                                                                 |
-| -------------------------------------------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
-| `EventHubClient.receive()` and `EventHubClient.receiveBatch()` | `EventHubConsumerClient.subscribe()` | [receiveEvents](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/eventhub/event-hubs/samples/typescript/src/receiveEvents.ts) |
+| In v2                                                          | Equivalent in v5                     | Sample                                                                                                                                  |
+| -------------------------------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `EventHubClient.receive()` and `EventHubClient.receiveBatch()` | `EventHubConsumerClient.subscribe()` | [receiveEvents](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/eventhub/event-hubs/samples/v5/typescript/src/receiveEvents.ts) |
 
 Other noteworthy changes:
 
@@ -226,7 +226,7 @@ const subscription = eventHubConsumerClient.subscribe(
 await subscription.close();
 ```
 
-See [`receiveEvents.ts`](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/eventhub/event-hubs/samples/typescript/src/receiveEvents.ts)
+See [`receiveEvents.ts`](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/eventhub/event-hubs/samples/v5/typescript/src/receiveEvents.ts)
 for a sample program demonstrating this.
 
 #### Migrating from `EventProcessorHost` to `EventHubConsumerClient` for receiving events
@@ -333,7 +333,7 @@ what order, making checkpointing difficult to do correctly.
 
 In V5 the model has been simplified so new events are not delivered until the
 previous batch has been consumed by your event handler. You can see a sample
-demonstrating this [here](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/eventhub/event-hubs/samples/typescript/src/receiveEvents.ts)
+demonstrating this [here](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/eventhub/event-hubs/samples/v5/typescript/src/receiveEvents.ts)
 
 ### Creating EventPosition
 

sdk/eventhub/event-hubs/package.json

@@ -46,17 +46,17 @@
     "audit": "node ../../../common/scripts/rush-audit.js && rimraf node_modules package-lock.json && npm i --package-lock-only 2>&1 && npm audit",
     "build:browser": "tsc -p . && cross-env ONLY_BROWSER=true rollup -c 2>&1",
     "build:node": "tsc -p . && cross-env ONLY_NODE=true rollup -c 2>&1",
-    "build:samples": "dev-tool samples prep && cd dist-samples && tsc",
+    "build:samples": "echo Obsolete.",
     "build:test:browser": "tsc -p . && cross-env ONLY_BROWSER=true rollup -c rollup.test.config.js 2>&1",
     "build:test:node": "tsc -p . && cross-env ONLY_NODE=true rollup -c rollup.test.config.js 2>&1",
     "build:test": "tsc -p . && rollup -c rollup.test.config.js 2>&1",
     "build:types": "downlevel-dts types/latest types/3.1",
     "build": "tsc -p . && rollup -c 2>&1 && api-extractor run --local && npm run build:types",
-    "check-format": "prettier --list-different --config ../../../.prettierrc.json --ignore-path ../../../.prettierignore \"src/**/*.ts\" \"test/**/*.ts\" \"*.{js,json}\"",
+    "check-format": "prettier --list-different --config ../../../.prettierrc.json --ignore-path ../../../.prettierignore \"src/**/*.ts\" \"test/**/*.ts\" \"samples-dev/**/*.ts\" \"*.{js,json}\"",
     "clean": "rimraf dist dist-* types *.tgz *.log",
-    "execute:samples": "npm run build:samples && echo Skipped.",
+    "execute:samples": "dev-tool samples run samples-dev",
     "extract-api": "tsc -p . && api-extractor run --local",
-    "format": "prettier --write --config ../../../.prettierrc.json --ignore-path ../../../.prettierignore \"src/**/*.ts\" \"test/**/*.ts\" \"*.{js,json}\"",
+    "format": "prettier --write --config ../../../.prettierrc.json --ignore-path ../../../.prettierignore \"src/**/*.ts\" \"test/**/*.ts\" \"samples-dev/**/*.ts\" \"*.{js,json}\"",
     "integration-test:browser": "karma start --single-run",
     "integration-test:node": "nyc mocha -r esm --require source-map-support/register --reporter ../../../common/tools/mocha-multi-reporter.js --timeout 1200000 --full-trace \"dist-esm/test/internal/*.spec.js\" \"dist-esm/test/public/*.spec.js\" \"dist-esm/test/public/**/*.spec.js\" \"dist-esm/test/internal/**/*.spec.js\"",
     "integration-test": "npm run integration-test:node && npm run integration-test:browser",
@@ -82,11 +82,27 @@
     ]
   },
   "//sampleConfiguration": {
+    "extraFiles": {
+      "./samples-browser": [
+        "browser"
+      ],
+      "./samples-express": [
+        "express"
+      ]
+    },
     "skip": [
       "iothubConnectionString.js",
       "useWithIotHub.js",
       "usingAadAuth.js"
-    ]
+    ],
+    "productName": "Azure Event Hubs",
+    "productSlugs": [
+      "azure",
+      "azure-event-hubs"
+    ],
+    "requiredResources": {
+      "Azure Event Hub": "https://docs.microsoft.com/azure/event-hubs/event-hubs-create"
+    }
   },
   "dependencies": {
     "@azure/abort-controller": "^1.0.0",

sdk/eventhub/event-hubs/sample.env

@@ -1,10 +1,9 @@
-# Used in most samples
+# Used in most samples. Retrieve these values from an Event Hub in the Azure Portal.
 EVENTHUB_CONNECTION_STRING=<connection string WITHOUT an EntityPath>
 EVENTHUB_NAME=<name of a single eventhub>
-EVENTHUB_FQDN=<your-eventhubs-namespace>.servicebus.windows.net
 CONSUMER_GROUP_NAME=<name of a consumer group>
 
-# Used in the useWithIotHub.ts sample
+# Used in the useWithIotHub sample. Retrieve this value from an IoT Hub's built-in endpoints in the Azure Portal.
 IOTHUB_EH_COMPATIBLE_CONNECTION_STRING=<connection string with EntityPath>
 
 # Used to authenticate using Azure AD as a service principal for role-based authentication
@@ -14,4 +13,5 @@ IOTHUB_EH_COMPATIBLE_CONNECTION_STRING=<connection string with EntityPath>
 # https://docs.microsoft.com/javascript/api/@azure/identity/environmentcredential
 AZURE_CLIENT_ID=
 AZURE_TENANT_ID=
-AZURE_CLIENT_SECRET=
+AZURE_CLIENT_SECRET=
+EVENTHUB_FQDN=<your-eventhubs-namespace>.servicebus.windows.net

sdk/eventhub/event-hubs/samples/browserSample/README.md → sdk/eventhub/event-hubs/samples-browser/README.md

@@ -77,11 +77,11 @@ as the redirect URI you added to your app registration. If you're following alon
 
 Take a look at our [API Documentation][apiref] for more information about the APIs that are available in the clients.
 
-[sendevents]: https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/eventhub/event-hubs/samples/browserSample/src/sendEvents.js
-[receiveevents]: https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/eventhub/event-hubs/samples/browserSample/src/receiveEvents.js
-[configuration]: https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/eventhub/event-hubs/samples/browserSample/src/configuration.js
-[app]: https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/eventhub/event-hubs/samples/browserSample/src/index.js
-[htmlpage]: https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/eventhub/event-hubs/samples/browserSample/index.html
+[sendevents]: https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/eventhub/event-hubs/samples/v5/browser/src/sendEvents.js
+[receiveevents]: https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/eventhub/event-hubs/samples/v5/browser/src/receiveEvents.js
+[configuration]: https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/eventhub/event-hubs/samples/v5/browser/src/configuration.js
+[app]: https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/eventhub/event-hubs/samples/v5/browser/src/index.js
+[htmlpage]: https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/eventhub/event-hubs/samples/v5/browser/index.html
 [apiref]: https://docs.microsoft.com/javascript/api/@azure/event-hubs
 [azhubacct]: https://docs.microsoft.com/azure/event-hubs/event-hubs-node-get-started-send
 [aziothub]: https://docs.microsoft.com/azure/iot-hub/iot-hub-node-node-module-twin-getstarted

sdk/eventhub/event-hubs/samples/typescript/src/iothubConnectionString.ts → sdk/eventhub/event-hubs/samples-dev/iothubConnectionString.ts

@@ -1,26 +1,21 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT Licence.
 
-/*
-  This sample demonstrates how to convert an Iot Hub connection string to
-  an Event Hubs connection string that points to the built-in messaging endpoint.
-
-  The Event Hubs connection string is then used with the EventHubConsumerClient to
-  receive events.
+/**
+ * @summary Demonstrates how to convert an IoT Hub connection string to an Event Hubs connection string that points to the built-in messaging endpoint.
+ */
 
-  More information about the built-in messaging endpoint can be found at:
-  https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-messages-read-builtin
-*/
+/*
+ * The Event Hubs connection string is then used with the EventHubConsumerClient to receive events.
+ *
+ * More information about the built-in messaging endpoint can be found at:
+ * https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-messages-read-builtin
+ */
 
 import * as crypto from "crypto";
 import { Buffer } from "buffer";
-import {
-  AmqpError,
-  Connection,
-  ReceiverEvents,
-  isAmqpError as rheaIsAmqpError,
-  parseConnectionString
-} from "rhea-promise";
+import { AmqpError, Connection, ReceiverEvents, parseConnectionString } from "rhea-promise";
+import rheaPromise from "rhea-promise";
 import { EventHubConsumerClient, earliestEventPosition } from "@azure/event-hubs";
 
 // Load the .env file if it exists
@@ -32,7 +27,7 @@ dotenv.config();
  * @param err - An unknown error.
  */
 function isAmqpError(err: any): err is AmqpError {
-  return rheaIsAmqpError(err);
+  return rheaPromise.isAmqpError(err);
 }
 
 const consumerGroup = process.env["CONSUMER_GROUP_NAME"] || "";

sdk/eventhub/event-hubs/samples/typescript/src/receiveEvents.ts → sdk/eventhub/event-hubs/samples-dev/receiveEvents.ts

@@ -1,21 +1,11 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT Licence.
 
-/*
-  This sample demonstrates how to use the EventHubConsumerClient to process events from all partitions
-  of a consumer group in an Event Hubs instance.
-
-  If your Event Hub instance doesn't have any events, then please run "sendEvents.ts" sample
-  to populate it before running this sample.
-
-  For an example that uses checkpointing, see the sample in the eventhubs-checkpointstore-blob package
-  on GitHub at the following link:
-
-  https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/eventhub/eventhubs-checkpointstore-blob/samples/typescript/src/receiveEventsUsingCheckpointStore.ts
-
-  Note: If you are using version 2.1.0 or lower of @azure/event-hubs library, then please use the samples at
-  https://github.com/Azure/azure-sdk-for-js/tree/%40azure/event-hubs_2.1.0/sdk/eventhub/event-hubs/samples instead.
-*/
+/**
+ * @summary Demonstrates how to use the EventHubConsumerClient to process events from all partitions of a consumer group in an Event Hub.
+ *
+ * @azsdk-weight 50
+ */
 
 import { EventHubConsumerClient, earliestEventPosition } from "@azure/event-hubs";
 

sdk/eventhub/event-hubs/samples/typescript/src/sendEvents.ts → sdk/eventhub/event-hubs/samples-dev/sendEvents.ts

@@ -1,13 +1,11 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT Licence.
 
-/*
-  This sample demonstrates how the send() function can be used to send events to Event Hubs.
-  See https://docs.microsoft.com/en-us/azure/event-hubs/event-hubs-about to learn about Event Hubs.
-
-  Note: If you are using version 2.1.0 or lower of @azure/event-hubs library, then please use the samples at
-  https://github.com/Azure/azure-sdk-for-js/tree/%40azure/event-hubs_2.1.0/sdk/eventhub/event-hubs/samples instead.
-*/
+/**
+ * @summary Demonstrates how to send events to an Event Hub.
+ *
+ * @azsdk-weight 60
+ */
 
 import { EventHubProducerClient } from "@azure/event-hubs";
 

sdk/eventhub/event-hubs/samples/typescript/src/useWithIotHub.ts → sdk/eventhub/event-hubs/samples-dev/useWithIotHub.ts

@@ -1,9 +1,10 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT Licence.
 
-/*
- This sample demonstrates how to use the EventHubClient with an IotHub instance
-*/
+/**
+ * @summary Demonstrates how to use the EventHubConsumerClient to receive messages from an IoT Hub.
+ */
+
 import { EventHubConsumerClient } from "@azure/event-hubs";
 
 // Load the .env file if it exists

sdk/eventhub/event-hubs/samples-dev/usingAadAuth.ts

@@ -0,0 +1,58 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT Licence.
+
+/**
+ * @summary Demonstrates how to instantiate EventHubsClient using AAD token credentials obtained from using service principal secrets.
+ *
+ * @azsdk-weight 40
+ */
+
+/*
+ * Setup :
+ *   Register a new application in AAD and assign the "Azure Event Hubs Data Owner" role to it
+ *    - See https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app
+ *      to register a new application in the Azure Active Directory.
+ *    - Note down the CLIENT_ID and TENANT_ID from the above step.
+ *    - In the "Certificates & Secrets" tab, create a secret and note that down.
+ *    - In the Azure portal, go to your Even Hubs resource and click on the Access control (IAM)
+ *      tab. Here, assign the "Azure Event Hubs Data Owner" role to the registered application.
+ *    - For more information on Event Hubs RBAC setup, learn more at https://docs.microsoft.com/en-us/azure/event-hubs/event-hubs-role-based-access-control)
+ *
+ */
+
+import { EventHubConsumerClient } from "@azure/event-hubs";
+import { DefaultAzureCredential } from "@azure/identity";
+
+// Load the .env file if it exists
+import * as dotenv from "dotenv";
+dotenv.config();
+
+// Define Event Hubs Endpoint and related entity name here here
+const eventHubsFullyQualifiedName = process.env["EVENTHUB_FQDN"] || ""; // <your-eventhubs-namespace>.servicebus.windows.net
+const eventHubName = process.env["EVENTHUB_NAME"] || "";
+const consumerGroup = process.env["CONSUMER_GROUP_NAME"] || "";
+
+// Define AZURE_TENANT_ID, AZURE_CLIENT_ID and AZURE_CLIENT_SECRET of your AAD application in your environment
+
+export async function main(): Promise<void> {
+  console.log(`Running usingAadAuth sample`);
+
+  const credential = new DefaultAzureCredential();
+  const client = new EventHubConsumerClient(
+    consumerGroup,
+    eventHubsFullyQualifiedName,
+    eventHubName,
+    credential
+  );
+  /*
+   Refer to other samples, and place your code here
+   to send/receive events
+  */
+  await client.close();
+
+  console.log(`Exiting usingAadAuth sample`);
+}
+
+main().catch((error) => {
+  console.error("Error running sample:", error);
+});