Update .NET SDK for inline attachments (#45360)

* update .NET SDK with inline attachments * updating samples * Updating tests and samples * reverting change to test environment * updating changelog and reverting target api for client * updating changelog * updating assets.json * updating autorest to point input file to main repo * addressing PR feedback, updating tests * updating csproj version * reverting formatting changes in samples * updating indentation in correct place and regenerating samples * Removing older preview versions from targetable client options
Azure · Sep 20, 2024 · b2cdc90 · b2cdc90
1 parent 3fe6168
commit b2cdc90
Show file tree

Hide file tree

Showing 22 changed files with 332 additions and 26 deletions.
diff --git a/sdk/communication/Azure.Communication.Email/CHANGELOG.md b/sdk/communication/Azure.Communication.Email/CHANGELOG.md
@@ -1,14 +1,11 @@
 # Release History
 
-## 1.1.0-beta.2 (Unreleased)
+## 1.1.0-beta.2 (2024-08-14)
 
 ### Features Added
 
-### Breaking Changes
-
-### Bugs Fixed
-
-### Other Changes
+- Consumers can now provide a value for the `ContentId` property when sending emails with attachments.
+  This allows consumers to reference attachments in the email body using the `cid` scheme. The `ContentId` property can be set on the `EmailAttachment` object.
 
 ## 1.1.0-beta.1 (2024-07-10)
 

diff --git a/sdk/communication/Azure.Communication.Email/README.md b/sdk/communication/Azure.Communication.Email/README.md
@@ -242,6 +242,50 @@ catch ( RequestFailedException ex )
 }
 ```
 
+### Send email with inline attachments
+Azure Communication Services support sending inline attachments.
+Adding an optional `contentId` parameter to the `EmailAttachment` constructor will make the attachment an inline attachment.
+```C# Snippet:Azure_Communication_Email_Send_With_Inline_Attachments
+// Create the email content and reference any inline attachments.
+var emailContent = new EmailContent("This is the subject")
+{
+    PlainText = "This is the body",
+    Html = "<html><body>This is the html body<img src=\"cid:myInlineAttachmentContentId\"></body></html>"
+};
+
+// Create the EmailMessage
+var emailMessage = new EmailMessage(
+    senderAddress: "<Send email address>" // The email address of the domain registered with the Communication Services resource
+    recipientAddress: "<recipient email address>"
+    content: emailContent);
+
+var filePath = "<path to your file>";
+var attachmentName = "<name of your attachment>";
+var contentType = MediaTypeNames.Text.Plain;
+var contentId = "myInlineAttachmentContentId";
+
+var content = new BinaryData(System.IO.File.ReadAllBytes(filePath));
+var emailAttachment = new EmailAttachment(attachmentName, contentType, content);
+emailAttachment.ContentId = contentId;
+
+emailMessage.Attachments.Add(emailAttachment);
+
+try
+{
+    EmailSendOperation emailSendOperation = emailClient.Send(WaitUntil.Completed, 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}");
+}
+catch ( RequestFailedException ex )
+{
+    /// OperationID is contained in the exception message and can be used for troubleshooting purposes
+    Console.WriteLine($"Email send operation failed with error code: {ex.ErrorCode}, message: {ex.Message}");
+}
+```
+
 ## Troubleshooting
 A `RequestFailedException` is thrown as a service response for any unsuccessful requests. The exception contains information about what response code was returned from the service.
 

diff --git a/sdk/communication/Azure.Communication.Email/api/Azure.Communication.Email.netstandard2.0.cs b/sdk/communication/Azure.Communication.Email/api/Azure.Communication.Email.netstandard2.0.cs
@@ -14,6 +14,7 @@ public partial class EmailAttachment
     {
         public EmailAttachment(string name, string contentType, System.BinaryData content) { }
         public System.BinaryData Content { get { throw null; } }
+        public string ContentId { get { throw null; } set { } }
         public string ContentType { get { throw null; } }
         public string Name { get { throw null; } }
     }
@@ -35,12 +36,13 @@ public EmailClient(System.Uri endpoint, Azure.Core.TokenCredential credential, A
     }
     public partial class EmailClientOptions : Azure.Core.ClientOptions
     {
-        public EmailClientOptions(Azure.Communication.Email.EmailClientOptions.ServiceVersion version = Azure.Communication.Email.EmailClientOptions.ServiceVersion.V2023_03_31) { }
+        public EmailClientOptions(Azure.Communication.Email.EmailClientOptions.ServiceVersion version = Azure.Communication.Email.EmailClientOptions.ServiceVersion.V2024_07_01_Preview) { }
         public enum ServiceVersion
         {
             V2021_10_01_Preview = 1,
             V2023_01_15_Preview = 2,
             V2023_03_31 = 3,
+            V2024_07_01_Preview = 4,
         }
     }
     public partial class EmailContent

diff --git a/sdk/communication/Azure.Communication.Email/assets.json b/sdk/communication/Azure.Communication.Email/assets.json
@@ -2,5 +2,5 @@
   "AssetsRepo": "Azure/azure-sdk-assets",
   "AssetsRepoPrefixPath": "net",
   "TagPrefix": "net/communication/Azure.Communication.Email",
-  "Tag": "net/communication/Azure.Communication.Email_7a9919913d"
+  "Tag": "net/communication/Azure.Communication.Email_00a51dd0e7"
 }
diff --git a/sdk/communication/Azure.Communication.Email/samples/README.md b/sdk/communication/Azure.Communication.Email/samples/README.md
@@ -19,14 +19,14 @@ This client library allows to do following operations:
  - Send a simple email message with manual polling for status
  - Specify optional paramters while sending Emails
  - Send an email message to multiple recipients
- - Send an email message with attachments
+ - Send an email message with attachments and inline attachments
 
  #### You can find samples for each of these functions below.
  - Send simple email message with automatic polling for status [synchronously][sample_simpleemail_autopolling] or [asynchronously][sample_simpleemail_autopolling_async]
  - Send simple email message with manual polling for status [asynchronously][sample_simpleemail_manualpolling_async]
  - Specify optional paramters while sending Emails [synchronously][sample_emailwithoptions] or [asynchronously][sample_emailwithoptions_async]
  - Send an email message to multiple recipients [synchronously][sample_email_multiplerecipients] or [asynchronously][sample_email_multiplerecipients_async]
- - Send an email message with attachments [synchronously][sample_email_attachments] or [asynchronously][sample_email_attachments_async]
+ - Send an email message with attachments and inline attachments [synchronously][sample_email_attachments] or [asynchronously][sample_email_attachments_async]
 
 <!-- LINKS -->
 [sample_simpleemail_autopolling]: https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/communication/Azure.Communication.Email/samples/Sample1_SendSimpleEmailWithAutomaticPollingForStatus.md

diff --git a/...unication.Email/samples/Sample1_SendSimpleEmailWithAutomaticPollingForStatus.md b/...unication.Email/samples/Sample1_SendSimpleEmailWithAutomaticPollingForStatus.md
@@ -37,4 +37,4 @@ catch ( RequestFailedException ex )
 }
 ```
 
-[README]: https://learn.microsoft.com/azure/communication-services/quickstarts/email/send-email?tabs=windows&pivots=platform-azcli#prerequisites
+[README]: https://learn.microsoft.com/azure/communication-services/quickstarts/email/send-email?tabs=windows&pivots=platform-azcli#prerequisites
diff --git a/...unication/Azure.Communication.Email/samples/Sample3_SendEmailWithMoreOptions.md b/...unication/Azure.Communication.Email/samples/Sample3_SendEmailWithMoreOptions.md
@@ -47,4 +47,4 @@ catch ( RequestFailedException ex )
 }
 ```
 
-[README]: https://learn.microsoft.com/azure/communication-services/quickstarts/email/send-email?tabs=windows&pivots=platform-azcli#prerequisites
+[README]: https://learn.microsoft.com/azure/communication-services/quickstarts/email/send-email?tabs=windows&pivots=platform-azcli#prerequisites
diff --git a/...tion/Azure.Communication.Email/samples/Sample4_SendEmailToMultipleRecipients.md b/...tion/Azure.Communication.Email/samples/Sample4_SendEmailToMultipleRecipients.md
@@ -81,4 +81,4 @@ catch ( RequestFailedException ex )
 }
 ```
 
-[README]: https://learn.microsoft.com/azure/communication-services/quickstarts/email/send-email?tabs=windows&pivots=platform-azcli#prerequisites
+[README]: https://learn.microsoft.com/azure/communication-services/quickstarts/email/send-email?tabs=windows&pivots=platform-azcli#prerequisites
diff --git a/...munication/Azure.Communication.Email/samples/Sample5_SendEmailWithAttachment.md b/...munication/Azure.Communication.Email/samples/Sample5_SendEmailWithAttachment.md
@@ -47,4 +47,4 @@ catch ( RequestFailedException ex )
 }
 ```
 
-[README]: https://learn.microsoft.com/azure/communication-services/quickstarts/email/send-email?tabs=windows&pivots=platform-azcli#prerequisites
+[README]: https://learn.microsoft.com/azure/communication-services/quickstarts/email/send-email?tabs=windows&pivots=platform-azcli#prerequisites
diff --git a/...ation/Azure.Communication.Email/samples/Sample5_SendEmailWithAttachmentAsync.md b/...ation/Azure.Communication.Email/samples/Sample5_SendEmailWithAttachmentAsync.md
@@ -47,4 +47,4 @@ catch ( RequestFailedException ex )
 }
 ```
 
-[README]: https://learn.microsoft.com/azure/communication-services/quickstarts/email/send-email?tabs=windows&pivots=platform-azcli#prerequisites
+[README]: https://learn.microsoft.com/azure/communication-services/quickstarts/email/send-email?tabs=windows&pivots=platform-azcli#prerequisites
diff --git a/...tion/Azure.Communication.Email/samples/Sample6_SendEmailWithInlineAttachment.md b/...tion/Azure.Communication.Email/samples/Sample6_SendEmailWithInlineAttachment.md
@@ -0,0 +1,60 @@
+# Send Email Message
+
+This sample demonstrates how to send an email message to an individual or a group of recipients.
+
+To get started you'll need a Communication Service Resource.  See [README][README] for prerequisites and instructions.
+
+## Creating an `EmailClient`
+
+Email clients can be authenticated using the connection string acquired from an Azure Communication Resource in the Azure Portal. Alternatively, Email clients can also be authenticated using a valid token credential.
+
+```C# Snippet:Azure_Communication_Email_CreateEmailClient
+var connectionString = "<connection_string>"; // Find your Communication Services resource in the Azure portal
+EmailClient emailClient = new EmailClient(connectionString);
+```
+
+### Send email with attachments
+Azure Communication Services support sending emails with attachments. Adding an optional `contentId` parameter to the `EmailAttachment` constructor will make the attachment an inline attachment.
+See [EmailAttachmentType][email_attachmentTypes] for a list of supported attachments.
+```C# Snippet:Azure_Communication_Email_Send_With_Inline_Attachments
+// Create the email content and reference any inline attachments.
+var emailContent = new EmailContent("This is the subject")
+{
+    PlainText = "This is the body",
+    Html = "<html><body>This is the html body<img src=\"cid:myInlineAttachmentContentId\"></body></html>"
+};
+
+// Create the EmailMessage
+var emailMessage = new EmailMessage(
+    senderAddress: "<Send email address>" // The email address of the domain registered with the Communication Services resource
+    recipientAddress: "<recipient email address>"
+    content: emailContent);
+
+var filePath = "<path to your file>";
+var attachmentName = "<name of your attachment>";
+var contentType = MediaTypeNames.Text.Plain;
+var contentId = "myInlineAttachmentContentId";
+
+var content = new BinaryData(System.IO.File.ReadAllBytes(filePath));
+var emailAttachment = new EmailAttachment(attachmentName, contentType, content);
+emailAttachment.ContentId = contentId;
+
+emailMessage.Attachments.Add(emailAttachment);
+
+try
+{
+    EmailSendOperation emailSendOperation = emailClient.Send(WaitUntil.Completed, 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}");
+}
+catch ( RequestFailedException ex )
+{
+    /// OperationID is contained in the exception message and can be used for troubleshooting purposes
+    Console.WriteLine($"Email send operation failed with error code: {ex.ErrorCode}, message: {ex.Message}");
+}
+```
+
+[README]: https://learn.microsoft.com/azure/communication-services/quickstarts/email/send-email?tabs=windows&pivots=platform-azcli#prerequisites
diff --git a/...Azure.Communication.Email/samples/Sample6_SendEmailWithInlineAttachmentAsync.md b/...Azure.Communication.Email/samples/Sample6_SendEmailWithInlineAttachmentAsync.md
@@ -0,0 +1,60 @@
+# Send Email Message
+
+This sample demonstrates how to send an email message to an individual or a group of recipients.
+
+To get started you'll need a Communication Service Resource.  See [README][README] for prerequisites and instructions.
+
+## Creating an `EmailClient`
+
+Email clients can be authenticated using the connection string acquired from an Azure Communication Resource in the Azure Portal. Alternatively, Email clients can also be authenticated using a valid token credential.
+
+```C# Snippet:Azure_Communication_Email_CreateEmailClient
+var connectionString = "<connection_string>"; // Find your Communication Services resource in the Azure portal
+EmailClient emailClient = new EmailClient(connectionString);
+```
+
+### Send email with attachments
+Azure Communication Services support sending emails with attachments. Adding an optional `contentId` parameter to the `EmailAttachment` constructor will make the attachment an inline attachment.
+See [EmailAttachmentType][email_attachmentTypes] for a list of supported attachments.
+```C# Snippet:Azure_Communication_Email_Send_With_Inline_Attachments_Async
+// Create the email content and reference any inline attachments.
+var emailContent = new EmailContent("This is the subject")
+{
+    PlainText = "This is the body",
+    Html = "<html><body>This is the html body<img src=\"cid:myInlineAttachmentContentId\"></body></html>"
+};
+
+// Create the EmailMessage
+var emailMessage = new EmailMessage(
+    senderAddress: "<Send email address>" // The email address of the domain registered with the Communication Services resource
+    recipientAddress: "<recipient email address>"
+    content: emailContent);
+
+var filePath = "<path to your file>";
+var attachmentName = "<name of your attachment>";
+var contentType = MediaTypeNames.Text.Plain;
+var contentId = "myInlineAttachmentContentId";
+
+var content = new BinaryData(System.IO.File.ReadAllBytes(filePath));
+var emailAttachment = new EmailAttachment(attachmentName, contentType, content);
+emailAttachment.ContentId = contentId;
+
+emailMessage.Attachments.Add(emailAttachment);
+
+try
+{
+    EmailSendOperation emailSendOperation = await emailClient.SendAsync(WaitUntil.Completed, 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}");
+}
+catch ( RequestFailedException ex )
+{
+    /// OperationID is contained in the exception message and can be used for troubleshooting purposes
+    Console.WriteLine($"Email send operation failed with error code: {ex.ErrorCode}, message: {ex.Message}");
+}
+```
+
+[README]: https://learn.microsoft.com/azure/communication-services/quickstarts/email/send-email?tabs=windows&pivots=platform-azcli#prerequisites
diff --git a/sdk/communication/Azure.Communication.Email/src/EmailClientOptions.cs b/sdk/communication/Azure.Communication.Email/src/EmailClientOptions.cs
@@ -17,7 +17,7 @@ public class EmailClientOptions : ClientOptions
         /// The latest version of the Email service.
         /// </summary>
         ///
-        private const ServiceVersion LatestVersion = ServiceVersion.V2023_03_31;
+        private const ServiceVersion LatestVersion = ServiceVersion.V2024_07_01_Preview;
 
         internal string ApiVersion { get; }
 
@@ -28,9 +28,8 @@ public EmailClientOptions(ServiceVersion version = LatestVersion)
         {
             ApiVersion = version switch
             {
-                ServiceVersion.V2021_10_01_Preview => "2021-10-01-preview",
-                ServiceVersion.V2023_01_15_Preview => "2023-01-15-preview",
                 ServiceVersion.V2023_03_31 => "2023-03-31",
+                ServiceVersion.V2024_07_01_Preview => "2024-07-01-preview",
                 _ => throw new ArgumentOutOfRangeException(nameof(version)),
             };
         }
@@ -53,6 +52,10 @@ public enum ServiceVersion
             /// The GA version of the Email service.
             /// </summary>
             V2023_03_31 = 3,
+            /// <summary>
+            /// The Inline Attachments preview version of the Email service.
+            /// </summary>
+            V2024_07_01_Preview = 4,
 #pragma warning restore CA1707 // Identifiers should not contain underscores
         }
     }

diff --git a/sdk/communication/Azure.Communication.Email/src/Generated/EmailRestClient.cs b/sdk/communication/Azure.Communication.Email/src/Generated/EmailRestClient.cs
diff --git a/...unication/Azure.Communication.Email/src/Generated/Models/EmailAttachment.Serialization.cs b/...unication/Azure.Communication.Email/src/Generated/Models/EmailAttachment.Serialization.cs
diff --git a/sdk/communication/Azure.Communication.Email/src/Generated/Models/EmailAttachment.cs b/sdk/communication/Azure.Communication.Email/src/Generated/Models/EmailAttachment.cs
diff --git a/sdk/communication/Azure.Communication.Email/src/Generated/Models/EmailMessage.cs b/sdk/communication/Azure.Communication.Email/src/Generated/Models/EmailMessage.cs
diff --git a/sdk/communication/Azure.Communication.Email/src/Models/EmailAttachment.cs b/sdk/communication/Azure.Communication.Email/src/Models/EmailAttachment.cs
@@ -4,7 +4,6 @@
 #nullable disable
 
 using System;
-using System.Text;
 using Azure.Core;
 
 namespace Azure.Communication.Email
@@ -41,5 +40,10 @@ internal void ValidateAttachmentContent()
         /// Contents of the attachment as BinaryData.
         /// </summary>
         public BinaryData Content { get; }
+
+        /// <summary>
+        /// Optional unique identifier (CID) to reference an inline attachment.
+        /// </summary>
+        public string ContentId { get; set; }
     }
 }