diff --git a/xml/System.Net.Mail/MailAddress.xml b/xml/System.Net.Mail/MailAddress.xml index 344f47d5854..4ead79a9a4d 100644 --- a/xml/System.Net.Mail/MailAddress.xml +++ b/xml/System.Net.Mail/MailAddress.xml @@ -51,26 +51,25 @@ class is used by the and classes to store address information for email messages. -A mail address is composed of a name, name and optionally, a . The can contain non-ASCII characters if you encode them. +A mail address is composed of a [user name](xref:System.Net.Mail.MailAddress.User), [host name](xref:System.Net.Mail.MailAddress.Host), and an optional [display name](xref:System.Net.Mail.MailAddress.DisplayName). can contain non-ASCII characters if you encode them. The class supports the following mail address formats: -- A simple address format of `user@host`. If a is not set, this is the mail address format generated. -- A standard quoted display name format of `"display name" `. If a is set, this is the format generated. +- A simple address format of `user@host`. If a is not set, this is the mail address format that's generated. +- A standard quoted display name format of `"display name" `. If a is set, this is the format that's generated. - - Angle brackets are added around the name and name, if these are not included. For example, `"display name" user@host` is changed to `"display name" `. - - Quotes are added around the , if these are not included. For example, `display name ` is changed to `"display name" `. - - Unicode characters are supported in the property. + - If they're not already included, angle brackets are added around the name and name. For example, `"display name" user@host` is changed to `"display name" `. + - If they're not already included, quotes are added around the . For example, `display name ` is changed to `"display name" `. + - Unicode characters are supported in the property. Within these two formats, the following elements are allowed: -- A name with quotes. For example, `"user name"@host`. -- Consecutive and trailing dots in user names. For example, `user...name..@host`. +- A name with quotes. For example, `"user name"@host`. - Bracketed domain literals. For example, ``. - Comments. For example, `(comment)"display name"(comment)<(comment)user(comment)@(comment)domain(comment)>(comment)`. Comments are removed before transmission. +- .NET 9 and earlier ONLY: Consecutive and trailing dots in user names. For example, `user...name..@host`. (Starting in .NET 10, consecutive dots aren't allowed.) A comma is used to separate elements in a list of mail addresses. As a result, a comma should not be used in unquoted display names in a list. The following mail addresses would be allowed: @@ -90,19 +89,21 @@ The following mail address would not be allowed: `"John "Jr" Doe" ` -When the username is not quoted, all text between the start of the string (or comma) and the address are considered part of the , including comments. For example: +When the username is not quoted, all text between the start of the string (or comma) and the address is considered part of the , including comments. For example: `(non comment) unquoted display (non comment) name (non comment) ` -Although the class accepts a mail address as valid, other mail servers may not accept the mail address. +Although the class accepts a mail address as valid, other mail servers might not accept the mail address. The class does not support the following mail address formats: - Mixed quoted and unquoted display names. For example, `display "name" `. - Groups, as defined in RFC 2822 Section 3.4 published by the IETF. - The obsolete user name formats of `"user"."name"@host`, `user."name"@host` or `"user".name@host`. +- .NET 10 and later versions only: Consecutive dots in the user name, for example, `user...name@host.com`. ## Examples + The following code example demonstrates sending an email message by using the , , and classes. :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet10"::: @@ -167,28 +168,26 @@ The following code example demonstrates sending an email message by using the "` +The `address` parameter can contain a display name and the associated email address if you enclose the address in angle brackets. For example: - White space is permitted between the display name and the angle brackets. +`"Tom Smith "` - The following table shows the property values for a object constructed using the preceding example address. - -|Property|Value| -|--------------|-----------| -||`"Tom Smith"`| -||`"contoso.com"`| -||`"tsmith"`| -||`"tsmith@contoso.com"`| +White space is permitted between the display name and the angle brackets. +The following table shows the property values for a object constructed using the preceding example address. +| Property | Value | +| ---------------------------------------------- | ---------------------- | +| | `"Tom Smith"` | +| | `"contoso.com"` | +| | `"tsmith"` | +| | `"tsmith@contoso.com"` | ## Examples - The following code example uses this constructor to create a object for the recipient of an email message. - :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet9"::: +The following code example uses this constructor to create a object for the recipient of an email message. + +:::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet9"::: ]]> @@ -256,19 +255,17 @@ The following code example demonstrates sending an email message by using the , `displayName` overrides the value specified in `address`. +Leading and trailing white space in the display name is preserved. +If `displayName` contains non-ASCII characters, the iso-8859-1 character set is used for the `displayName` encoding. Encoding non-ASCII characters is discussed in RFC 1522, which is available at [https://www.ietf.org/](https://www.ietf.org/). +If `address` contains a display name, and `displayName` is not `null` and is not equal to , `displayName` overrides the value specified in `address`. ## Examples - The following code example uses this constructor to create instances for the sender and recipient of an email message. - :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet9"::: +The following code example uses this constructor to create instances for the sender and recipient of an email message. + +:::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet9"::: ]]> @@ -336,22 +333,20 @@ The following code example demonstrates sending an email message by using the , `displayName` overrides the value specified in `address`. - - The method does not check if the `displayName` parameter is valid. This method removes surrounding quotes not displayed by the property. Quotes will be added before transmission, except where or is specified in the `displayNameEncoding` parameter. The encoding specified in the `displayNameEncoding` parameter will be applied to the property before transmission or is specified in the `displayNameEncoding` parameter. is the default encoding if none is specified. - - For more information on supported mail address formats, see . +If `address` contains a display name, and `displayName` is not `null` and is not equal to , `displayName` overrides the value specified in `address`. +The constructor does not check if the `displayName` parameter is valid. This method removes surrounding quotes not displayed by the property. Quotes will be added before transmission, except where or is specified in the `displayNameEncoding` parameter. The encoding specified in the `displayNameEncoding` parameter will be applied to the property before transmission or is specified in the `displayNameEncoding` parameter. is the default encoding if none is specified. +For more information on supported mail address formats, see . ## Examples - The following code example uses this constructor to create instances for the sender of an email message. - :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/MailAddress/.ctor/mailasync.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net.Mail/MailAddress/.ctor/mailasync.vb" id="Snippet2"::: +The following code example uses this constructor to create instances for the sender of an email message. + +:::code language="csharp" source="~/snippets/csharp/System.Net.Mail/MailAddress/.ctor/mailasync.cs" id="Snippet2"::: +:::code language="vb" source="~/snippets/visualbasic/System.Net.Mail/MailAddress/.ctor/mailasync.vb" id="Snippet2"::: ]]> @@ -415,15 +410,13 @@ The following code example demonstrates sending an email message by using the information. - - +The value returned by this property does not include the information. ## Examples - The following code example displays the address for an email message recipient. - :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet10"::: +The following code example displays the address for an email message recipient. + +:::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet10"::: ]]> @@ -475,17 +468,15 @@ The following code example demonstrates sending an email message by using the method to get the encoded form of the . - - Some software programs that are used to read email display the property value instead of, or in addition to, the email address. - +Display names that contain non-ASCII characters are returned in human-readable form. Use the method to get the encoded form of the . +Some software programs that are used to read email display the property value instead of, or in addition to, the email address. ## Examples - The following code example displays the for the recipient of an email message. - :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet9"::: +The following code example displays the for the recipient of an email message. + +:::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet9"::: ]]> @@ -585,8 +576,7 @@ The following code example demonstrates sending an email message by using the method returns a hash code of the mail address. This value can be used as a key in hash tables. +The method returns a hash code of the mail address. This value can be used as a key in hash tables. ]]> @@ -638,15 +628,13 @@ The following code example demonstrates sending an email message by using the @@ -693,19 +681,17 @@ The following code example demonstrates sending an email message by using the property is not `null` and not equal to (""), returns a string composed using the following syntax: - - \<@> - - If is `null` or is equal to , returns the value of the property. +The string returned by this method is not necessarily identical to the string specified when the instance was created. If the property is not `null` and not equal to (""), returns a string composed using the following syntax: + \<@> +If is `null` or is equal to , returns the value of the property. ## Examples - The following code example displays the destination of an email message. - :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet7"::: +The following code example displays the destination of an email message. + +:::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet7"::: ]]> @@ -916,15 +902,13 @@ The following code example demonstrates sending an email message by using the