SmtpClient-Klasse

Die SmtpClient-Klasse wird zum Senden von E-Mail-Nachrichten an einen SMTP-Server für die Übermittlung verwendet. Das SMTP-Protokoll ist im RFC 2821 definiert, der unter http://www.ietf.org (nur auf Englisch verfügbar) zur Verfügung steht.

Mit den Klassen in der folgenden Tabelle werden E-Mail-Nachrichten erstellt, die mithilfe von SmtpClient gesendet werden können.

Um mit SmtpClient eine E-Mail-Nachricht zu erstellen und zu senden, müssen Sie die folgenden Informationen angeben:

• Der SMTP-Hostserver, den Sie zum Senden von E-Mail-Nachrichten verwenden. Weitere Informationen finden Sie in der Host-Eigenschaft und der Port-Eigenschaft.

• Anmeldeinformationen für die Authentifizierung, sofern für den SMTP-Server erforderlich. Siehe die Credentials-Eigenschaft.

• Die E-Mail-Adresse des Absenders. Siehe die Send-Methode und die SendAsync-Methode, die einen from-Parameter verwenden. Siehe auch die MailMessage.From-Eigenschaft.

• Die E-Mail-Adressen der Empfänger. Siehe die Send-Methode und die SendAsync-Methode, die einen recipient-Parameter verwenden. Siehe auch die MailMessage.To-Eigenschaft.

• Der Nachrichteninhalt. Siehe die Send-Methode und die SendAsync-Methode, die einen body-Parameter verwenden. Siehe auch die MailMessage.Body-Eigenschaft.

Um eine Anlage in eine E-Mail-Nachricht einzufügen, erstellen Sie zunächst die Anlage mit der Attachment-Klasse, und fügen Sie sie dann mit der MailMessage.Attachments-Eigenschaft zur Nachricht hinzu. Je nach dem von den Empfängern verwendeten E-Mail-Reader und dem Dateityp der Anlage können einige Empfänger die Anlage möglicherweise nicht lesen. Für Clients, die die Anlage nicht in ihrem ursprünglichen Format anzeigen können, können Sie mithilfe der MailMessage.AlternateViews-Eigenschaft alternative Ansichten festlegen.

Mit der Anwendungs- oder Computerkonfigurationsdatei können Sie Host- und Anschlussstandardwerte sowie Standardanmeldeinformationen für alle SmtpClient-Objekte angeben. Weitere Informationen finden Sie unter <mailSettings>-Element (Netzwerkeinstellungen).

Um die E-Mail-Nachricht zu senden und die Ausführung während des Wartens auf die Übertragung der E-Mail-Nachricht an den SMTP-Server zu blockieren, verwenden Sie eine der synchronen Send-Methoden. Um die weitere Ausführung des Hauptthreads des Programms während der Übertragung der E-Mail-Nachricht zuzulassen, verwenden Sie einer der asynchronen SendAsync-Methoden. Das SendCompleted-Ereignis wird ausgelöst, wenn ein SendAsync-Vorgang abgeschlossen wird. Um dieses Ereignis zu empfangen, müssen Sie SendCompleted einen SendCompletedEventHandler-Delegaten hinzufügen. Der SendCompletedEventHandler-Delegat muss auf eine Rückrufmethode verweisen, die die Benachrichtigung über SendCompleted-Ereignisse behandelt. Um eine asynchrone E-Mail-Übertragung abzubrechen, verwenden Sie die SendAsyncCancel-Methode.

Hinweis
Wenn eine E-Mail-Übertragung gerade ausgeführt wird und Sie SendAsync oder Send erneut aufrufen, empfangen Sie eine InvalidOperationException.

Die von der aktuellen Instanz der SmtpClient-Klasse zum SMTP-Server hergestellte Verbindung kann wiederverwendet werden, wenn eine Anwendung mehrere Meldungen an den gleichen SMTP-Server senden möchte. Dies ist besonders nützlich, wenn Authentifizierung oder Verschlüsselung verwendet wird, um eine Verbindung zum SMTP-Server herzustellen. Das Authentifizieren und Einrichten einer TLS-Sitzung können aufwendige Operationen sein. Eine Anforderung, um erneut eine Verbindung für jede Meldung einzurichten, wenn eine große Menge von E-Mails zum gleichen SMTP-Server gesendet werden, kann bedeutende Auswirkungen auf die Leistung haben. Es gibt eine Reihe von Anwendungen für hohe E-Mail-Aufkommen, die E-Mail-Statusupdates, Newsletterverteilungen oder E-Mail-Warnungen senden. Auch unterstützen viele E-Mail-Clientanwendungen einen Offline-Betrieb, in dem Benutzer viele E-Mails verfassen können, die später gesendet werden, wenn eine Verbindung zum SMTP-Server hergestellt wird. Es ist typisch, dass ein E-Mail-Client alle SMTP-Meldungen an einen bestimmten SMTP-Server (bereitgestellt vom Internetdienstanbieter) sendet, der dann diese E-Mail an andere SMTP-Server weiterleitet.

Die SmtpClient-Klassenimplementierung legt SMTP-Verbindungen zusammen, damit es den Aufwand vermeiden kann, für jede Nachricht erneut eine Verbindung zum gleichen Server einzurichten. Eine Anwendung darf das gleiche SmtpClient-Objekt wiederverwenden, um viele unterschiedliche E-Mails an den gleichen SMTP-Server und viele unterschiedliche SMTP-Server zu senden. Daher gibt es keine Möglichkeit zu bestimmen, wann eine Anwendung das Verwenden des SmtpClient-Objekts beendet hat und es bereinigt werden sollte.

Wenn eine SMTP-Sitzung beendet wird und der Client die Verbindung beenden möchte, muss er eine QUIT-Meldung an den Server senden, um anzugeben, dass es keine weiteren Meldungen zu senden hat. Dies ermöglicht es dem Server, Ressourcen freizugeben, die der Verbindung vom Client zugeordnet sind und Meldungen verarbeiten, die vom Client gesendet wurden.

Die SmtpClient-Klasse verfügt über keine Finalize-Methode, deshalb muss eine Anwendung Dispose aufrufen, um explizit Ressourcen freizugeben. Die Dispose-Methode durchläuft alle hergestellten Verbindungen mit dem in der Host-Eigenschaft angegebenen SMTP-Server und sendet eine QUIT-Meldung, gefolgt vom normalen Beenden der TCP-Verbindung. Die Dispose-Methode gibt zudem die vom Socket verwendeten nicht verwalteten Ressourcen frei und verwirft optional die verwalteten Ressourcen.

Rufen Sie Dispose auf, wenn Sie SmtpClient nicht mehr benötigen. Die Dispose-Methode bewirkt, dass SmtpClient nicht mehr verwendet werden kann. Nach dem Aufruf von Dispose müssen Sie alle Verweise auf SmtpClient freigeben, sodass der vom SmtpClient belegte Speicher bei der Garbage Collection wieder zugänglich gemacht werden kann.

Im folgenden Codebeispiel wird das asynchrone Senden einer E-Mail-Nachricht veranschaulicht.

using System;
using System.Net;
using System.Net.Mail;
using System.Net.Mime;
using System.Threading;
using System.ComponentModel;
namespace Examples.SmptExamples.Async
{
    public class SimpleAsynchronousExample
    {
        static bool mailSent = false;
        private static void SendCompletedCallback(object sender, AsyncCompletedEventArgs e)
        {
            // Get the unique identifier for this asynchronous operation.
             String token = (string) e.UserState;

            if (e.Cancelled)
            {
                 Console.WriteLine("[{0}] Send canceled.", token);
            }
            if (e.Error != null)
            {
                 Console.WriteLine("[{0}] {1}", token, e.Error.ToString());
            } else
            {
                Console.WriteLine("Message sent.");
            }
            mailSent = true;
        }
        public static void Main(string[] args)
        {
            // Command line argument must the the SMTP host.
            SmtpClient client = new SmtpClient(args[0]);
            // Specify the e-mail sender.
            // Create a mailing address that includes a UTF8 character
            // in the display name.
            MailAddress from = new MailAddress("jane@contoso.com", 
               "Jane " + (char)0xD8+ " Clayton", 
            System.Text.Encoding.UTF8);
            // Set destinations for the e-mail message.
            MailAddress to = new MailAddress("ben@contoso.com");
            // Specify the message content.
            MailMessage message = new MailMessage(from, to);
            message.Body = "This is a test e-mail message sent by an application. ";
            // Include some non-ASCII characters in body and subject.
            string someArrows = new string(new char[] {'\u2190', '\u2191', '\u2192', '\u2193'});
            message.Body += Environment.NewLine + someArrows;
            message.BodyEncoding =  System.Text.Encoding.UTF8;
            message.Subject = "test message 1" + someArrows;
            message.SubjectEncoding = System.Text.Encoding.UTF8;
            // Set the method that is called back when the send operation ends.
            client.SendCompleted += new 
            SendCompletedEventHandler(SendCompletedCallback);
            // The userState can be any object that allows your callback 
            // method to identify this send operation.
            // For this example, the userToken is a string constant.
            string userState = "test message1";
            client.SendAsync(message, userState);
            Console.WriteLine("Sending message... press c to cancel mail. Press any other key to exit.");
            string answer = Console.ReadLine();
            // If the user canceled the send, and mail hasn't been sent yet,
            // then cancel the pending operation.
            if (answer.StartsWith("c") && mailSent == false)
            {
                client.SendAsyncCancel();
            }
            // Clean up.
            message.Dispose();
            Console.WriteLine("Goodbye.");
        }
    }
}

.NET Framework

.NET Framework Client Profile

Windows 7, Windows Vista SP1 oder höher, Windows XP SP3, Windows XP SP2 x64 Edition, Windows Server 2008 (Server Core wird nicht unterstützt), Windows Server 2008 R2 (Server Core wird mit SP1 oder höher unterstützt), Windows Server 2003 SP2

Referenz

Weitere Ressourcen