Azure Communication Services (ACS) Email .NET SDK (Public Preview 2 before GA) (#33110)

* AutoGenerated SDK changes from REST API

* Update version in EmailClientOptions

* Add generated SDK after another round of swagger changes

* Add convenience overloads for EmailClient.Send

* Fix failing unit tests

* Add overload for EmailAttachment constructor that takes BinaryData

* Add overload for EmailAttachment that takes BinaryData as parameter

* Restore global.json

* update SDK with long running operation

* revert global.json

* fix build failures

* Update SDK to include changes due to LRO patternn and fix issues that prevent apiview from being generated.

* Remove default value of null for displayName in EmailAddress constructor

* Regenerated SDK after swagger approved by ARB

* fix tests and samples

* fix failing unit tests by removing the generatd StartSend method

* rengerate SDK with updated swagger after ARB feedback

* stash changes

* Implement LRO pattern SDK guidelines

* Removing Models namespace from hand-rolled models as well

* Hide the Id property in EmailSendResult

* Add more unit tests for new scenarios

* update property ContentBytesBase64 to ContentInBase64

* Update samples

* fix errors from merge

* update public API and snippets

* regenerate SDK after merge from remote

* Convert EmailAddress to struct

* Convert Attachment content to base64 only at the end before sending over the wire

* Fix failing unit tests

* regenerate public API

* Rename DisableUserEngagementTracking proprety

* Update Public API surface

* update EmailMessage constructor to reorder parameters and fix tests

* Update recorded tests

* Fix build errors and override EmailsendResult.Serialization.cs

* update recorded tests with sanitized urls

* Update recorded test that was timing out.

* Address feedback - customize EmailModelFacory, split sample md files into individual files, fix links in md files

* fix broken links and add raw github file link in autorest.md

* remove codegenclient and codegensuppresstype

* add asp.net extensions for EmailClient

* actually adding the file for asp.net extensions for EmailClient

* Add missing asp.net extension and rename RestClient

* update public APIs

Author: apattath

sdk/communication/Azure.Communication.Email/README.md

@@ -23,15 +23,14 @@ To create these resource, you can use the [Azure Portal][communication_resource_
 ### Using statements
 ```C# Snippet:Azure_Communication_Email_UsingStatements
 using Azure.Communication.Email;
-using Azure.Communication.Email.Models;
 ```
 
 ### Authenticate the client
 Email clients can be authenticated using the connection string acquired from an Azure Communication Resource in the [Azure Portal][azure_portal].
 
 ```C# Snippet:Azure_Communication_Email_CreateEmailClient
 var connectionString = "<connection_string>"; // Find your Communication Services resource in the Azure portal
-EmailClient client = new EmailClient(connectionString);
+EmailClient emailClient = new EmailClient(connectionString);
 ```
 
 Alternatively, Email clients can also be authenticated using a valid token credential. With this option,
@@ -41,119 +40,168 @@ Alternatively, Email clients can also be authenticated using a valid token crede
 string endpoint = "<endpoint_url>";
 TokenCredential tokenCredential = new DefaultAzureCredential();
 tokenCredential = new DefaultAzureCredential();
-EmailClient client = new EmailClient(new Uri(endpoint), tokenCredential);
+EmailClient emailClient = new EmailClient(new Uri(endpoint), tokenCredential);
 ```
 ## Examples
-### Send an Email Message
-To send an email message, call the `Send` or `SendAsync` function from the `EmailClient`.
-```C# Snippet:Azure_Communication_Email_Send
-// Create the email content
-var emailContent = new EmailContent("This is the subject");
-emailContent.PlainText = "This is the body";
+### Send a simple email message with automatic polling for status
+To send an email message, call the simple overload of `Send` or `SendAsync` function from the `EmailClient`.
+```C# Snippet:Azure_Communication_Email_Send_Simple_AutoPolling
+var emailSendOperation = emailClient.Send(
+    wait: WaitUntil.Completed,
+    from: "<Send email address>" // The email address of the domain registered with the Communication Services resource
+    to: "<recipient email address>"
+    subject: "This is the subject",
+    htmlContent: "<html><body>This is the html body</body></html>");
+Console.WriteLine($"Email Sent. Status = {emailSendOperation.Value.Status}");
+
+/// Get the OperationId so that it can be used for tracking the message for troubleshooting
+string operationId = emailSendOperation.Id;
+Console.WriteLine($"Email operation id = {operationId}");
+```
 
-// Create the recipient list
-var emailRecipients = new EmailRecipients(
-    new List<EmailAddress>
+### Send a simple email message with manual polling for status
+To send an email message, call the simple overload of `Send` or `SendAsync` function from the `EmailClient`.
+```C# Snippet:Azure_Communication_Email_Send_Simple_ManualPolling_Async
+/// Send the email message with WaitUntil.Started
+var emailSendOperation = await emailClient.SendAsync(
+    wait: WaitUntil.Started,
+    from: "<Send email address>" // The email address of the domain registered with the Communication Services resource
+    to: "<recipient email address>"
+    subject: "This is the subject",
+    htmlContent: "<html><body>This is the html body</body></html>");
+
+/// Call UpdateStatus on the email send operation to poll for the status
+/// manually.
+while (true)
+{
+    await emailSendOperation.UpdateStatusAsync();
+    if (emailSendOperation.HasCompleted)
     {
-        new EmailAddress(
-            email: "<recipient email address>"
-            displayName: "<recipient displayname>"
-    });
+        break;
+    }
+    await Task.Delay(100);
+}
 
-// Create the EmailMessage
-var emailMessage = new EmailMessage(
-    sender: "<Send email address>" // The email address of the domain registered with the Communication Services resource
-    emailContent,
-    emailRecipients);
+if (emailSendOperation.HasValue)
+{
+    Console.WriteLine($"Email Sent. Status = {emailSendOperation.Value.Status}");
+}
 
-SendEmailResult sendResult = client.Send(emailMessage);
+/// Get the OperationId so that it can be used for tracking the message for troubleshooting
+string operationId = emailSendOperation.Id;
+Console.WriteLine($"Email operation id = {operationId}");
+```
 
-Console.WriteLine($"Email id: {sendResult.MessageId}");
+### Send an email message with more options
+To send an email message, call the overload of `Send` or `SendAsync` function from the `EmailClient` that takes an `EmailMessage` parameter.
+```C# Snippet:Azure_Communication_Email_Send_With_MoreOptions
+// Create the email content
+var emailContent = new EmailContent("This is the subject")
+{
+    PlainText = "This is the body",
+    Html = "<html><body>This is the html body</body></html>"
+};
+
+// Create the EmailMessage
+var emailMessage = new EmailMessage(
+    fromAddress: "<Send email address>" // The email address of the domain registered with the Communication Services resource
+    toAddress: "<recipient email address>"
+    content: emailContent);
+
+var emailSendOperation = emailClient.Send(
+    wait: WaitUntil.Completed,
+    message: emailMessage);
+Console.WriteLine($"Email Sent. Status = {emailSendOperation.Value.Status}");
+
+/// Get the OperationId so that it can be used for tracking the message for troubleshooting
+string operationId = emailSendOperation.Id;
+Console.WriteLine($"Email operation id = {operationId}");
 ```
 
-### Send an Email Message to Multiple Recipients
+### Send an email message to multiple recipients
 To send an email message to multiple recipients, add an `EmailAddress` object for each recipent type to the `EmailRecipient` object.
 
 ```C# Snippet:Azure_Communication_Email_Send_Multiple_Recipients
 // Create the email content
-var emailContent = new EmailContent("This is the subject");
-emailContent.PlainText = "This is the body";
+var emailContent = new EmailContent("This is the subject")
+{
+    PlainText = "This is the body",
+    Html = "<html><body>This is the html body</body></html>"
+};
 
 // Create the To list
 var toRecipients = new List<EmailAddress>
 {
     new EmailAddress(
-        email: "<recipient email address>"
+        address: "<recipient email address>"
         displayName: "<recipient displayname>"
     new EmailAddress(
-        email: "<recipient email address>"
+        address: "<recipient email address>"
         displayName: "<recipient displayname>"
 };
 
 // Create the CC list
 var ccRecipients = new List<EmailAddress>
 {
     new EmailAddress(
-        email: "<recipient email address>"
+        address: "<recipient email address>"
         displayName: "<recipient displayname>"
     new EmailAddress(
-        email: "<recipient email address>"
+        address: "<recipient email address>"
         displayName: "<recipient displayname>"
 };
 
 // Create the BCC list
 var bccRecipients = new List<EmailAddress>
 {
     new EmailAddress(
-        email: "<recipient email address>"
+        address: "<recipient email address>"
         displayName: "<recipient displayname>"
     new EmailAddress(
-        email: "<recipient email address>"
+        address: "<recipient email address>"
         displayName: "<recipient displayname>"
 };
 
 var emailRecipients = new EmailRecipients(toRecipients, ccRecipients, bccRecipients);
 
 // Create the EmailMessage
 var emailMessage = new EmailMessage(
-    sender: "<Send email address>" // The email address of the domain registered with the Communication Services resource
-    emailContent,
-    emailRecipients);
+    senderAddress: "<Send email address>" // The email address of the domain registered with the Communication Services resource
+    emailRecipients,
+    emailContent);
 
-SendEmailResult sendResult = client.Send(emailMessage);
+EmailSendOperation emailSendOperation = emailClient.Send(WaitUntil.Completed, emailMessage);
+Console.WriteLine($"Email Sent. Status = {emailSendOperation.Value.Status}");
 
-Console.WriteLine($"Email id: {sendResult.MessageId}");
+/// Get the OperationId so that it can be used for tracking the message for troubleshooting
+string operationId = emailSendOperation.Id;
+Console.WriteLine($"Email operation id = {operationId}");
 ```
 
-### Send Email with Attachments
-Azure Communication Services support sending email swith attachments. See [EmailAttachmentType][email_attachmentTypes] for a list of supported attachments
+### Send email with attachments
+Azure Communication Services support sending emails with attachments.
 ```C# Snippet:Azure_Communication_Email_Send_With_Attachments
 // Create the EmailMessage
 var emailMessage = new EmailMessage(
-    sender: "<Send email address>" // The email address of the domain registered with the Communication Services resource
-    emailContent,
-    emailRecipients);
+    fromAddress: "<Send email address>" // The email address of the domain registered with the Communication Services resource
+    toAddress: "<recipient email address>"
+    content: emailContent);
 
 var filePath = "<path to your file>";
 var attachmentName = "<name of your attachment>";
-EmailAttachmentType attachmentType = EmailAttachmentType.Txt;
+var contentType = MediaTypeNames.Text.Plain;
 
-// Convert the file content into a Base64 string
-byte[] bytes = File.ReadAllBytes(filePath);
-string attachmentFileInBytes = Convert.ToBase64String(bytes);
-var emailAttachment = new EmailAttachment(attachmentName, attachmentType, attachmentFileInBytes);
+string content = new BinaryData(File.ReadAllBytes(filePath));
+var emailAttachment = new EmailAttachment(attachmentName, contentType, content);
 
 emailMessage.Attachments.Add(emailAttachment);
 
-SendEmailResult sendResult = client.Send(emailMessage);
-```
-
-### Get Email Message Status
-The `EmailSendResult` from the `Send` call contains a `MessageId` which can be used to query the status of the email.
-```C# Snippet:Azure_Communication_Email_GetSendStatus
-SendEmailResult sendResult = client.Send(emailMessage);
+EmailSendOperation emailSendOperation = emailClient.Send(WaitUntil.Completed, emailMessage);
+Console.WriteLine($"Email Sent. Status = {emailSendOperation.Value.Status}");
 
-SendStatusResult status = client.GetSendStatus(sendResult.MessageId);
+/// Get the OperationId so that it can be used for tracking the message for troubleshooting
+string operationId = emailSendOperation.Id;
+Console.WriteLine($"Email operation id = {operationId}");
 ```
 
 ## Troubleshooting
@@ -184,5 +232,4 @@ This project has adopted the [Microsoft Open Source Code of Conduct][coc]. For m
 [nextsteps]:https://aka.ms/acsemail/qs-sendmail?pivots=programming-language-csharp
 [nuget]: https://www.nuget.org/
 [source]: https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/communication/Azure.Communication.Email/src
-[email_attachmentTypes]: https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/communication/Azure.Communication.Email/src/Generated/Models/EmailAttachmentType.cs
 [domain_overview]: https://aka.ms/acsemail/domainsoverview