EG API Updates (#18369)

* Update API based on review feedback * Update samples * fix * Update wording * Fix sample
Azure · Feb 3, 2021 · 51fbb23 · 51fbb23
1 parent ac31b7f
commit 51fbb23
Show file tree

Hide file tree

Showing 12 changed files with 723 additions and 950 deletions.
diff --git a/sdk/eventgrid/Azure.Messaging.EventGrid/README.md b/sdk/eventgrid/Azure.Messaging.EventGrid/README.md
@@ -169,7 +169,12 @@ Using `CloudEvent`:
 // Parse the JSON payload into a list of events using CloudEvent.Parse
 CloudEvent[] cloudEvents = CloudEvent.Parse(jsonPayloadSampleTwo);
 ```
-From here, one can access the event data by deserializing to a specific type using `GetData<T>()` and passing in a custom serializer if necessary. Below is an example calling `GetData<T>()` using CloudEvents. In order to deserialize to the correct type, the `EventType` property (`Type` for CloudEvents) helps distinguish between different events.
+From here, one can access the event data by deserializing to a specific type using `GetData<T>()`. Calling `GetData()` will either return the event data wrapped in `BinaryData`, which represents the serialized JSON event data as bytes.
+
+Using `GetData<T>()`:
+
+Below is an example calling `GetData<T>()` for CloudEvents. In order to deserialize to the correct type, the `EventType` property (`Type` for CloudEvents) helps distinguish between different events. Custom event data should be deserialized using the generic method `GetData<T>()`. There is also an overload for `GetData<T>()` that accepts a custom `ObjectSerializer` to deserialize the event data.
+
 ```C# Snippet:DeserializePayloadUsingGenericGetData
 foreach (CloudEvent cloudEvent in cloudEvents)
 {
@@ -182,7 +187,7 @@ foreach (CloudEvent cloudEvent in cloudEvents)
             break;
         case "MyApp.Models.CustomEventType":
             // One can also specify a custom ObjectSerializer as needed to deserialize the payload correctly
-            TestPayload testPayload = await cloudEvent.GetDataAsync<TestPayload>(myCustomSerializer);
+            TestPayload testPayload = cloudEvent.GetData().ToObject<TestPayload>(myCustomSerializer);
             Console.WriteLine(testPayload.Name);
             break;
         case SystemEventNames.StorageBlobDeleted:
@@ -193,14 +198,20 @@ foreach (CloudEvent cloudEvent in cloudEvents)
     }
 }
 ```
-Below is an example using the `IsSystemEvent` property along with `AsSystemEventData()` to deserialize system events. 
+
+Using `TryGetSystemEventData()`:
+
+If expecting mostly system events, it may be cleaner to switch on `TryGetSystemEventData()` and use pattern matching to act on the individual events. If an event is not a system event, the method will return false and the out parameter will be null. 
+
+*As a caveat, if you are using a custom event type with an EventType value that later gets added as a system event by the service and SDK, the return value of `TryGetSystemEventData` would change from `false` to `true`. This could come up if you are pre-emptively creating your own custom events for events that are already being sent by the service, but have not yet been added to the SDK. In this case, it is better to use the generic `GetData<T>` method so that your code flow doesn't change automatically after upgrading (of course, you may still want to modify your code to consume the newly released system event model as opposed to your custom model).*
+
 ```C# Snippet:DeserializePayloadUsingAsSystemEventData
 foreach (EventGridEvent egEvent in egEvents)
 {
-    // If the event is a system event, AsSystemEventData() should return the correct system event type
-    if (egEvent.IsSystemEvent)
+    // If the event is a system event, TryGetSystemEventData() will return the deserialized system event
+    if (egEvent.TryGetSystemEventData(out object systemEvent))
     {
-        switch (egEvent.AsSystemEventData())
+        switch (systemEvent)
         {
             case SubscriptionValidationEventData subscriptionValidated:
                 Console.WriteLine(subscriptionValidated.ValidationCode);

diff --git a/sdk/eventgrid/Azure.Messaging.EventGrid/api/Azure.Messaging.EventGrid.netstandard2.0.cs b/sdk/eventgrid/Azure.Messaging.EventGrid/api/Azure.Messaging.EventGrid.netstandard2.0.cs
@@ -1,29 +1,21 @@
 namespace Azure.Messaging.EventGrid
 {
-    public static partial class BinaryDataExtensions
-    {
-        public static Azure.Messaging.EventGrid.CloudEvent ToCloudEvent(this System.BinaryData binaryData) { throw null; }
-        public static Azure.Messaging.EventGrid.EventGridEvent ToEventGridEvent(this System.BinaryData binaryData) { throw null; }
-    }
     public partial class CloudEvent
     {
-        public CloudEvent(string source, string type, object data, string dataContentType = null, System.Type dataSerializationType = null) { }
+        public CloudEvent(string source, string type, object data, System.Type dataSerializationType = null) { }
+        public CloudEvent(string source, string type, System.ReadOnlyMemory<byte> data, string dataContentType) { }
         public string DataContentType { get { throw null; } set { } }
         public string DataSchema { get { throw null; } set { } }
         public System.Collections.Generic.Dictionary<string, object> ExtensionAttributes { get { throw null; } }
         public string Id { get { throw null; } set { } }
-        public bool IsSystemEvent { get { throw null; } }
         public string Source { get { throw null; } set { } }
         public string Subject { get { throw null; } set { } }
         public System.DateTimeOffset? Time { get { throw null; } set { } }
         public string Type { get { throw null; } set { } }
-        public object AsSystemEventData() { throw null; }
         public System.BinaryData GetData() { throw null; }
-        public System.Threading.Tasks.Task<System.BinaryData> GetDataAsync() { throw null; }
-        public System.Threading.Tasks.Task<T> GetDataAsync<T>(Azure.Core.Serialization.ObjectSerializer serializer = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
-        public T GetData<T>(Azure.Core.Serialization.ObjectSerializer serializer = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
-        public static Azure.Messaging.EventGrid.CloudEvent[] Parse(System.BinaryData requestContent) { throw null; }
+        public T GetData<T>(System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
         public static Azure.Messaging.EventGrid.CloudEvent[] Parse(string requestContent) { throw null; }
+        public bool TryGetSystemEventData(out object eventData) { throw null; }
     }
     public partial class EventGridEvent
     {
@@ -32,16 +24,17 @@ public EventGridEvent(string subject, string eventType, string dataVersion, obje
         public System.DateTimeOffset EventTime { get { throw null; } set { } }
         public string EventType { get { throw null; } set { } }
         public string Id { get { throw null; } set { } }
-        public bool IsSystemEvent { get { throw null; } }
         public string Subject { get { throw null; } set { } }
         public string Topic { get { throw null; } set { } }
-        public object AsSystemEventData() { throw null; }
         public System.BinaryData GetData() { throw null; }
-        public System.Threading.Tasks.Task<System.BinaryData> GetDataAsync() { throw null; }
-        public System.Threading.Tasks.Task<T> GetDataAsync<T>(Azure.Core.Serialization.ObjectSerializer serializer = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
-        public T GetData<T>(Azure.Core.Serialization.ObjectSerializer serializer = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
-        public static Azure.Messaging.EventGrid.EventGridEvent[] Parse(System.BinaryData requestContent) { throw null; }
+        public T GetData<T>(System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
         public static Azure.Messaging.EventGrid.EventGridEvent[] Parse(string requestContent) { throw null; }
+        public bool TryGetSystemEventData(out object eventData) { throw null; }
+    }
+    public static partial class EventGridExtensions
+    {
+        public static Azure.Messaging.EventGrid.CloudEvent ToCloudEvent(this System.BinaryData binaryData) { throw null; }
+        public static Azure.Messaging.EventGrid.EventGridEvent ToEventGridEvent(this System.BinaryData binaryData) { throw null; }
     }
     public partial class EventGridPublisherClient
     {

diff --git a/sdk/eventgrid/Azure.Messaging.EventGrid/samples/Sample1_PublishEventsToTopic.md b/sdk/eventgrid/Azure.Messaging.EventGrid/samples/Sample1_PublishEventsToTopic.md
@@ -24,11 +24,18 @@ EventGridPublisherClient client = new EventGridPublisherClient(
     new AzureKeyCredential(topicAccessKey),
     clientOptions);
 ```
-Event Grid also supports authenticating with a shared access signature which allows for providing access to a resource that expires by a certain time without sharing your access key:
-```C# Snippet:CreateWithSas
+Event Grid also supports authenticating with a shared access signature which allows for providing access to a resource that expires by a certain time without sharing your access key. 
+Generally, the workflow would be that one application would generate the SAS string and hand off the string to another application that would consume the string.
+Generate the SAS:
+```C# Snippet:GenerateSas
 var builder = new EventGridSasBuilder(new Uri(topicEndpoint), DateTimeOffset.Now.AddHours(1));
 var keyCredential = new AzureKeyCredential(topicAccessKey);
-var sasCredential = new AzureSasCredential(builder.GenerateSas(keyCredential));
+string sasToken = builder.GenerateSas(keyCredential);
+```
+
+Here is how it would be used from the consumer's perspective:
+```C# Snippet:AuthenticateWithSas
+var sasCredential = new AzureSasCredential(sasToken);
 EventGridPublisherClient client = new EventGridPublisherClient(
     new Uri(topicEndpoint),
     sasCredential);

diff --git a/...ventgrid/Azure.Messaging.EventGrid/samples/Sample3_ParseAndDeserializeEvents.md b/...ventgrid/Azure.Messaging.EventGrid/samples/Sample3_ParseAndDeserializeEvents.md
@@ -40,7 +40,7 @@ foreach (CloudEvent cloudEvent in cloudEvents)
             break;
         case "MyApp.Models.CustomEventType":
             // One can also specify a custom ObjectSerializer as needed to deserialize the payload correctly
-            TestPayload testPayload = await cloudEvent.GetDataAsync<TestPayload>(myCustomSerializer);
+            TestPayload testPayload = cloudEvent.GetData().ToObject<TestPayload>(myCustomSerializer);
             Console.WriteLine(testPayload.Name);
             break;
         case SystemEventNames.StorageBlobDeleted:
@@ -52,16 +52,18 @@ foreach (CloudEvent cloudEvent in cloudEvents)
 }
 ```
 
-### Using `AsSytemEventData()`
-If expecting mostly system events, it may be cleaner to switch on `AsSytemEventData()` and use pattern matching to act on the individual events. In the case where there are unrecognized event types, one can use the returned `BinaryData` to examine the event data.
+### Using `TryGetSystemEventData()`
+If expecting mostly system events, it may be cleaner to switch on `TryGetSystemEventData()` and use pattern matching to act on the individual events. If an event is not a system event, the method will return false and the out parameter will be null. 
+
+*As a caveat, if you are using a custom event type with an EventType value that later gets added as a system event by the service and SDK, the return value of `TryGetSystemEventData` would change from `false` to `true`. This could come up if you are pre-emptively creating your own custom events for events that are already being sent by the service, but have not yet been added to the SDK. In this case, it is better to use the generic `GetData<T>` method so that your code flow doesn't change automatically after upgrading (of course, you may still want to modify your code to consume the newly released system event model as opposed to your custom model).*
 
 ```C# Snippet:DeserializePayloadUsingAsSystemEventData
 foreach (EventGridEvent egEvent in egEvents)
 {
-    // If the event is a system event, AsSystemEventData() should return the correct system event type
-    if (egEvent.IsSystemEvent)
+    // If the event is a system event, TryGetSystemEventData() will return the deserialized system event
+    if (egEvent.TryGetSystemEventData(out object systemEvent))
     {
-        switch (egEvent.AsSystemEventData())
+        switch (systemEvent)
         {
             case SubscriptionValidationEventData subscriptionValidated:
                 Console.WriteLine(subscriptionValidated.ValidationCode);