Created samples README and sample files

sdk/eventgrid/Azure.Messaging.EventGrid/README.md

@@ -20,19 +20,21 @@ Install the client library from NuGet:
 
 ### Prerequisites
 
-You must have an [Azure subscription](https://azure.microsoft.com/free/) and an Azure resource group with a custom Event Grid topic or domain. Follow this [step-by-step tutorial](https://docs.microsoft.com/en-us/azure/event-grid/custom-event-quickstart-portal) to register the Event Grid resource provider and create Event Grid topics using the [Azure portal](https://portal.azure.com/). The [same tutorial](https://docs.microsoft.com/en-us/azure/event-grid/custom-event-quickstart) can be found using [Azure CLI](https://docs.microsoft.com/cli/azure).
+You must have an [Azure subscription](https://azure.microsoft.com/free/) and an Azure resource group with a custom Event Grid topic or domain. Follow this [step-by-step tutorial](https://docs.microsoft.com/en-us/azure/event-grid/custom-event-quickstart-portal) to register the Event Grid resource provider and create Event Grid topics using the [Azure portal](https://portal.azure.com/).
+
+The [same tutorial](https://docs.microsoft.com/en-us/azure/event-grid/custom-event-quickstart) can be found using [Azure CLI](https://docs.microsoft.com/cli/azure).
 
 ### Authenticate the Client
 
 In order for the client library to interact with a topic or domain, you will need the `endpoint` of the Event Grid topic and a `credential`, which can be created using the topic's access key.
 
-You can find the endpoint for your Event Grid topic either in the [Azure Portal](https://portal.azure.com/) or by using the [Azure CLI](https://docs.microsoft.com/cli/azure) snippet below:
+You can find the endpoint for your Event Grid topic either in the [Azure Portal](https://portal.azure.com/) or by using the [Azure CLI](https://docs.microsoft.com/cli/azure) snippet below.
 
 ```bash
 az eventgrid topic show --name <your-resource-name> --resource-group <your-resource-group-name> --query "endpoint"
 ```
 
-The access key can also be found through the portal, or by using the Azure CLI snippet below:
+The access key can also be found through the [portal](https://docs.microsoft.com/en-us/azure/event-grid/get-access-keys), or by using the Azure CLI snippet below:
 ```bash
 az eventgrid topic key list --name <your-resource-name> --resource-group <your-resource-group-name> --query "key1"
 ```
@@ -45,24 +47,26 @@ EventGridPublisherClient client = new EventGridPublisherClient(
     "<endpoint>",
     new AzureKeyCredential("<access-key>"));
 ```
-You can also create a **Shared Access Signature** to authenticate the client using the same access key, instead passing in the `EventGridSharedAccessSignatureCredential` type:
+You can also create a **Shared Access Signature** to authenticate the client using the same access key. A SAS token can be generated using the endpoint, access key, and a time at which the SAS token becomes invalid for authentication. Pass in the `EventGridSharedAccessSignatureCredential` type:
 ```csharp
 string sasToken = EventGridPublisherClient.BuildSharedAccessSignature(
     "<endpoint>",
-    <tokenExpirationTime>,
+    DateTimeOffset.UtcNow.AddMinutes(60),
     new AzureKeyCredential("<access-key>"));
 
 EventGridPublisherClient client = new EventGridPublisherClient(
     "<endpoint>",
     new EventGridSharedAccessSignatureCredential(sasToken));
 ```
 
+`EventGridPublisherClient` also accepts a set of configuring options through `EventGridPublisherClientOptions`. For example, specifying a custom serializer used to serialize the event data to JSON.
+
 ## Key concepts
 
 For information about general Event Grid concepts: [Concepts in Azure Event Grid](https://docs.microsoft.com/en-us/azure/event-grid/concepts).
 
 ### EventGridPublisherClient
-A **publisher** sends events to Event Grid. Microsoft publishes events for several Azure services. You can publish events from your own application using the `EventGridPublisherClient`.
+A **publisher** sends events to the Event Grid service. Microsoft publishes events for several Azure services. You can publish events from your own application using the `EventGridPublisherClient`.
 
 ### Event schemas
 An **event** is the smallest amount of information that fully describes something that happened in the system. Event Grid supports multiple schemas for encoding events. When a custom topic or domain is created, you specify the schema that will be used when publishing events. While you may configure your topic to use a custom schema, it is more common to use the already-defined [Event Grid schema](https://docs.microsoft.com/en-us/azure/event-grid/event-schema) or [CloudEvents 1.0 schema](https://docs.microsoft.com/en-us/azure/event-grid/cloud-event-schema). [CloudEvents](https://cloudevents.io/) is a Cloud Native Computing Foundation project which produces a specification for describing event data in a common way.
@@ -72,7 +76,7 @@ Regardless of what schema your topic or domain is configured to use, `EventGridP
 ### Event delivery
 Events delivered to consumers by Event Grid are *delivered as JSON*. Depending on the type of consumer being delivered to, the Event Grid service may deliver one or more events as part of a single payload. Handling events will be different based on which schema the event was delivered as. However, the general pattern will remain the same:
 - Parse events from JSON into individual events. Based on the event schema (Event Grid or CloudEvents), you can now access basic information about the event on the envelope (properties that are present for all events, like event time and type).
-- Deserialize the event data. Given an `EventGridEvent` or `CloudEvent`, the user can attempt to access the event payload, or data, by deserializing to a specific type. Note that you can supply a custom serializer at this point to correctly decode the data.
+- Deserialize the event data. Given an `EventGridEvent` or `CloudEvent`, the user can attempt to access the event payload, or data, by deserializing to a specific type. You can supply a custom serializer at this point to correctly decode the data.
 
 ## Examples
 * [Publish Event Grid events to an Event Grid Topic](#publish-event-grid-events-to-an-event-grid-topic)
@@ -83,12 +87,6 @@ Events delivered to consumers by Event Grid are *delivered as JSON*. Depending o
 ### Publish Event Grid events to an Event Grid Topic
 Publishing events to Event Grid is performed using the `EventGridPublisherClient`. Use the provided `SendEvents` method to publish events to the topic.
 ```csharp Snippet:SendEGEventsToTopic
-// Create the publisher client using an AzureKeyCredential
-// Custom topic should be configured to accept events of the Event Grid schema
-EventGridPublisherClient client = new EventGridPublisherClient(
-    new Uri(topicEndpoint),
-    new AzureKeyCredential(topicAccessKey));
-
 // Add EventGridEvents to a list to publish to the topic
 List<EventGridEvent> eventsList = new List<EventGridEvent>
 {
@@ -105,15 +103,10 @@ await client.SendEventsAsync(eventsList);
 ### Publish CloudEvents to an Event Grid Topic
 Publishing events to Event Grid is performed using the `EventGridPublisherClient`. Use the provided `SendEvents` method to publish events to the topic.
 ```csharp Snippet:SendCloudEventsToTopic
-// Create the publisher client using an AzureKeyCredential
-// Custom topic should be configured to accept events of the CloudEvents 1.0 schema
-EventGridPublisherClient client = new EventGridPublisherClient(
-    new Uri(topicEndpoint),
-    new AzureKeyCredential(topicAccessKey));
-
 // Add CloudEvents to a list to publish to the topic
 List<CloudEvent> eventsList = new List<CloudEvent>
 {
+    // CloudEvent with populated data
     new CloudEvent(
         "/cloudevents/example/source",
         "Example.EventType",
@@ -124,7 +117,7 @@ List<CloudEvent> eventsList = new List<CloudEvent>
         "/cloudevents/example/binarydata",
         "Example.EventType",
         new BinaryData("This is binary data"),
-        "example/binary")};
+          "example/binary")};
 
 // Send the events
 await client.SendEventsAsync(eventsList);
@@ -135,12 +128,6 @@ An **event domain** is a management tool for large numbers of Event Grid topics
 
 To publish events to any topic in an Event Domain, push the events to the domain's endpoint the same way you would for a custom topic. The only difference is that you must specify the topic you'd like the event to be delivered to.
 ```csharp Snippet:SendEventsToDomain
-// Create the publisher client using an AzureKeyCredential
-// Domain should be configured to accept events of the Event Grid schema
-EventGridPublisherClient client = new EventGridPublisherClient(
-    new Uri(domainEndpoint),
-    new AzureKeyCredential(domainAccessKey));
-
 // Add EventGridEvents to a list to publish to the domain
 // Don't forget to specify the topic you want the event to be delivered to!
 List<EventGridEvent> eventsList = new List<EventGridEvent>

sdk/eventgrid/Azure.Messaging.EventGrid/samples/README.md

@@ -0,0 +1,17 @@
+---
+page_type: sample
+languages:
+- csharp
+products:
+- azure
+- azure-event-grid
+name: Azure Event Grid samples for .NET
+description: Samples for the Azure.Messaging.EventGrid client library
+---
+
+# Azure Event Grid SDK Samples
+Before starting, take a look at the Azure Event Grid [README](README) for more information on how to create an Event Grid custom topic or domain using the Azure portal/Azure CLI, and retrieving the designated endpoint and credential.
+
+- [Publishing Events to an Event Grid Topic]()
+- [Publishing Events to an Event Grid Domain]()
+- [Receiving and Deserializing Events]()

sdk/eventgrid/Azure.Messaging.EventGrid/samples/Sample1_PublishEventsToTopic.md

@@ -0,0 +1,75 @@
+# Publishing Events to an Event Grid Topic
+
+This sample demonstrates how to publish both Event Grid and CloudEvent 1.0 schema events to the Event Grid service. You can publish events from your own application using the `EventGridPublisherClient`. To begin, separate custom Event Grid topics accepting events of the Event Grid and CloudEvent 1.0 schema must be created.
+
+## Creating and Authenticating `EventGridPublisherClient`
+Once you have your access key and topic endpoint, you can create the publisher client using the `AzureKeyCredential` class as follows:
+```csharp CreateClient
+EventGridPublisherClient client = new EventGridPublisherClient(
+    new Uri(topicEndpoint),
+    new AzureKeyCredential(topicAccessKey));
+```
+`EventGridPublisherClient` also accepts a set of configuring options through `EventGridPublisherClientOptions`. For example, specifying a custom serializer used to serialize the event data to JSON:
+
+```csharp Snippet:CreateClientWithOptions
+EventGridPublisherClientOptions clientOptions = new EventGridPublisherClientOptions()
+{
+    DataSerializer = myCustomDataSerializer
+};
+
+EventGridPublisherClient client = new EventGridPublisherClient(
+    new Uri(topicEndpoint),
+    new AzureKeyCredential(topicAccessKey),
+    clientOptions);
+```
+
+## Publishing Events to Azure Event Grid
+### Using `EventGridEvent`
+After creating the `EventGridPublisherClient` such that the custom topic is configured to accept events of the Event Grid schema, we can now create some events of the `EventGridEvent` type to publish to the topic.
+
+Following that, invoke `SendEvents` or `SendEventsAsync` to publish the events to Azure Event Grid.
+
+Note on `EventGridEvent`: each `EventGridEvent` has a set of required, non-nullable properties, including event data. `EventTime` and `Id` are also required properties that are set by default, but can also be manually set if needed.
+
+```csharp Snippet:SendEGEventsToTopic
+// Add EventGridEvents to a list to publish to the topic
+List<EventGridEvent> eventsList = new List<EventGridEvent>
+{
+    new EventGridEvent(
+        "This is the event data",
+        "ExampleEventSubject",
+        "Example.EventType",
+        "1.0")
+};
+
+// Send the events
+await client.SendEventsAsync(eventsList);
+```
+
+### Using `CloudEvent`
+The process for publishing events of the CloudEvent schema is very similar to that of Event Grid events. Once again, after creating the `EventGridPublisherClient` such that the custom topic is configured to accept events of the CloudEvent 1.0 schema, we can create events of the `CloudEvent` type.
+
+Following that, invoke `SendEvents` or `SendEventsAsync` to publish the events to Azure Event Grid.
+
+Note on `CloudEvent`: each `CloudEvent` has a set of required, non-nullable properties. However, `Data` is *not required*. `Time` and `SpecVersion` are required properties that are set by default, but can also be manually set if needed. `Time` is also set by default, but not required.
+
+```csharp Snippet:SendCloudEventsToTopic
+// Add CloudEvents to a list to publish to the topic
+List<CloudEvent> eventsList = new List<CloudEvent>
+{
+    // CloudEvent with populated data
+    new CloudEvent(
+        "/cloudevents/example/source",
+        "Example.EventType",
+        "This is the event data"),
+
+    // CloudEvents also supports sending binary-valued data
+    new CloudEvent(
+        "/cloudevents/example/binarydata",
+        "Example.EventType",
+        new BinaryData("This is binary data"),
+        "example/binary")};
+
+// Send the events
+await client.SendEventsAsync(eventsList);
+```

sdk/eventgrid/Azure.Messaging.EventGrid/tests/Infrastructure/EventGridTestEnvironment.cs

@@ -24,6 +24,7 @@ public EventGridTestEnvironment() : base("eventgrid")
         public const string CustomEventTopicKeyEnvironmentVariableName = "EVENT_GRID_CUSTOM_EVENT_TOPIC_KEY";
         public const string CustomEventTopicEndpointEnvironmentVariableName = "EVENT_GRID_CUSTOM_EVENT_TOPIC_ENDPOINT";
 
+
         public string TopicHost => GetRecordedVariable(TopicEndpointEnvironmentVariableName);
         public string TopicKey => GetRecordedVariable(TopicKeyEnvironmentVariableName, options => options.IsSecret(SanitizedValue.Base64));
 

sdk/eventgrid/Azure.Messaging.EventGrid/tests/Samples/Sample1_SendEventsToTopic.cs

@@ -4,9 +4,12 @@
 using System;
 using System.Collections.Generic;
 using System.Text;
+using System.Text.Json;
 using System.Threading.Tasks;
 using Azure.Core;
+using Azure.Core.Serialization;
 using NUnit.Framework;
+using NUnit.Framework.Constraints;
 
 namespace Azure.Messaging.EventGrid.Tests.Samples
 {
@@ -17,19 +20,22 @@ public EventGridSamples(bool async)
         {
         }
 
+        // This sample demonstrates how to publish Event Grid schema events to an Event Grid topic.
         [Test]
         public async Task SendEventGridEventsToTopic()
         {
             string topicEndpoint = TestEnvironment.TopicHost;
             string topicAccessKey = TestEnvironment.TopicKey;
 
-            #region Snippet:SendEGEventsToTopic
             // Create the publisher client using an AzureKeyCredential
             // Custom topic should be configured to accept events of the Event Grid schema
+            #region Snippet:CreateClient
             EventGridPublisherClient client = new EventGridPublisherClient(
                 new Uri(topicEndpoint),
                 new AzureKeyCredential(topicAccessKey));
+            #endregion
 
+            #region Snippet:SendEGEventsToTopic
             // Add EventGridEvents to a list to publish to the topic
             List<EventGridEvent> eventsList = new List<EventGridEvent>
             {
@@ -45,22 +51,38 @@ public async Task SendEventGridEventsToTopic()
             #endregion
         }
 
+        // This sample demonstrates how to publish CloudEvents 1.0 schema events to an Event Grid topic.
         [Test]
         public async Task SendCloudEventsToTopic()
         {
             string topicEndpoint = TestEnvironment.CloudEventTopicHost;
             string topicAccessKey = TestEnvironment.CloudEventTopicKey;
 
-            #region Snippet:SendCloudEventsToTopic
+            var myCustomDataSerializer = new JsonObjectSerializer(
+                new JsonSerializerOptions()
+                {
+                    PropertyNamingPolicy = JsonNamingPolicy.CamelCase
+                });
+
             // Create the publisher client using an AzureKeyCredential
             // Custom topic should be configured to accept events of the CloudEvents 1.0 schema
+            #region Snippet:CreateClientWithOptions
+            EventGridPublisherClientOptions clientOptions = new EventGridPublisherClientOptions()
+            {
+                DataSerializer = myCustomDataSerializer
+            };
+
             EventGridPublisherClient client = new EventGridPublisherClient(
                 new Uri(topicEndpoint),
-                new AzureKeyCredential(topicAccessKey));
+                new AzureKeyCredential(topicAccessKey),
+                clientOptions);
+            #endregion
 
+            #region Snippet:SendCloudEventsToTopic
             // Add CloudEvents to a list to publish to the topic
             List<CloudEvent> eventsList = new List<CloudEvent>
             {
+                // CloudEvent with populated data
                 new CloudEvent(
                     "/cloudevents/example/source",
                     "Example.EventType",
@@ -78,19 +100,20 @@ public async Task SendCloudEventsToTopic()
             #endregion
         }
 
+        // This sample demonstrates how to publish Event Grid schema events to a topic within an Event Grid domain.
         [Test]
         public async Task SendEventsToDomain()
         {
             string domainEndpoint = TestEnvironment.DomainHost;
             string domainAccessKey = TestEnvironment.DomainKey;
 
-            #region Snippet:SendEventsToDomain
             // Create the publisher client using an AzureKeyCredential
             // Domain should be configured to accept events of the Event Grid schema
             EventGridPublisherClient client = new EventGridPublisherClient(
                 new Uri(domainEndpoint),
                 new AzureKeyCredential(domainAccessKey));
 
+            #region Snippet:SendEventsToDomain
             // Add EventGridEvents to a list to publish to the domain
             // Don't forget to specify the topic you want the event to be delivered to!
             List<EventGridEvent> eventsList = new List<EventGridEvent>