SmtpClient Klasa

Definicja

Przestrzeń nazw:

System.Net.Mail

Zestaw:

System.Net.Mail.dll

Źródło:

SmtpClient.cs

Umożliwia aplikacjom wysyłanie wiadomości e-mail przy użyciu protokołu SMTP (Simple Mail Transfer Protocol). Typ SmtpClient jest przestarzały na niektórych platformach i nie jest zalecany w innych; aby uzyskać więcej informacji, zobacz sekcję Uwagi.

public ref class SmtpClient : IDisposable

[System.Runtime.Versioning.UnsupportedOSPlatform("browser")]
public class SmtpClient : IDisposable

[<System.Runtime.Versioning.UnsupportedOSPlatform("browser")>]
type SmtpClient = class
    interface IDisposable

Public Class SmtpClient
Implements IDisposable

Dziedziczenie

Object

SmtpClient

Atrybuty

UnsupportedOSPlatformAttribute

Implementuje

IDisposable

Przykłady

Poniższy przykład kodu pokazuje wysyłanie wiadomości e-mail asynchronicznie.

#using <System.dll>
using namespace System;
using namespace System::Net;
using namespace System::Net::Mail;
using namespace System::Net::Mime;
using namespace System::Threading;
using namespace System::ComponentModel;

static bool mailSent;

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 != nullptr)
    {
        Console::WriteLine("[{0}] {1}", token, 
            e->Error->ToString());
    } else
    {
        Console::WriteLine("Message sent.");
    }
    mailSent = true;
}

int main(array<String^>^ args)
{
    if (args->Length > 1)
    {
        // Command-line argument must be the SMTP host.
        SmtpClient^ client = gcnew SmtpClient(args[1]);
        // Specify the email sender.
        // Create a mailing address that includes a UTF8 
        // character in the display name.
        MailAddress^ from = gcnew MailAddress("jane@contoso.com",
            "Jane " + (wchar_t)0xD8 + " Clayton",
            System::Text::Encoding::UTF8);
        // Set destinations for the email message.
        MailAddress^ to = gcnew MailAddress("ben@contoso.com");
        // Specify the message content.
        MailMessage^ message = gcnew MailMessage(from, to);
        message->Body = "This is a test email message sent" +
            " by an application. ";
        // Include some non-ASCII characters in body and 
        // subject.
        String^ someArrows = gcnew String(gcnew array<wchar_t>{L'\u2190', 
            L'\u2191', L'\u2192', L'\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 += gcnew
            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->ToLower()->StartsWith("c") && mailSent == false)
        {
            client->SendAsyncCancel();
        }
        // Clean up.
        delete message;
        client = nullptr;
        Console::WriteLine("Goodbye.");
    }
    else
    {
        Console::WriteLine("Please give SMTP server name!");
    }
}

using System;
using System.Net;
using System.Net.Mail;
using System.Net.Mime;
using System.Threading;
using System.ComponentModel;
namespace Examples.SmtpExamples.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 be the SMTP host.
            SmtpClient client = new SmtpClient(args[0]);
            // Specify the email 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 email message.
            MailAddress to = new MailAddress("ben@contoso.com");
            // Specify the message content.
            MailMessage message = new MailMessage(from, to);
            message.Body = "This is a test email 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.");
        }
    }
}

Imports System.Net
Imports System.Net.Mail
Imports System.Net.Mime
Imports System.Threading
Imports System.ComponentModel

Namespace Examples.SmtpExamples.Async
    Public Class SimpleAsynchronousExample
        Private Shared mailSent As Boolean = False
        Private Shared Sub SendCompletedCallback(ByVal sender As Object, ByVal e As AsyncCompletedEventArgs)
            ' Get the unique identifier for this asynchronous operation.
            Dim token As String = CStr(e.UserState)

            If e.Cancelled Then
                Console.WriteLine("[{0}] Send canceled.", token)
            End If
            If e.Error IsNot Nothing Then
                Console.WriteLine("[{0}] {1}", token, e.Error.ToString())
            Else
                Console.WriteLine("Message sent.")
            End If
            mailSent = True
        End Sub
        Public Shared Sub Main(ByVal args() As String)
            ' Command line argument must the SMTP host.
            Dim client As New SmtpClient(args(0))
            ' Specify the email sender.
            ' Create a mailing address that includes a UTF8 character
            ' in the display name.
            Dim mailFrom As New MailAddress("jane@contoso.com", "Jane " & ChrW(&HD8) & " Clayton", System.Text.Encoding.UTF8)
            ' Set destinations for the email message.
            Dim mailTo As New MailAddress("ben@contoso.com")
            ' Specify the message content.
            Dim message As New MailMessage(mailFrom, mailTo)
            message.Body = "This is a test email message sent by an application. "
            ' Include some non-ASCII characters in body and subject.
            Dim someArrows As New String(New Char() {ChrW(&H2190), ChrW(&H2191), ChrW(&H2192), ChrW(&H2193)})
            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.
            AddHandler client.SendCompleted, AddressOf 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.
            Dim userState As String = "test message1"
            client.SendAsync(message, userState)
            Console.WriteLine("Sending message... press c to cancel mail. Press any other key to exit.")
            Dim answer As String = Console.ReadLine()
            ' If the user canceled the send, and mail hasn't been sent yet,
            ' then cancel the pending operation.
            If answer.StartsWith("c") AndAlso mailSent = False Then
                client.SendAsyncCancel()
            End If
            ' Clean up.
            message.Dispose()
            Console.WriteLine("Goodbye.")
        End Sub
    End Class
End Namespace

Uwagi

Klasa SmtpClient służy do wysyłania wiadomości e-mail na serwer SMTP na potrzeby dostarczania. Protokół SMTP jest zdefiniowany w dokumencie RFC 2821, który jest dostępny pod adresem https://www.ietf.org.

Ważne

Nie zalecamy używania SmtpClient klasy do nowego programowania, ponieważ SmtpClient nie obsługuje wielu nowoczesnych protokołów. Zamiast tego użyj zestawu MailKit lub innych bibliotek. Aby uzyskać więcej informacji, zobacz SmtpClient nie powinien być używany w usłudze GitHub.

Klasa SmtpClient jest przestarzała w środowisku Xamarin. Jednak:

• Jest on zawarty w wersjach .NET Standard 2.0 i nowszych, dlatego musi być częścią dowolnej implementacji platformy .NET, która obsługuje te wersje.
• Jest obecny i może być używany w .NET Framework 4 do .NET Framework 4.8.
• Jest on używany na platformie .NET Core, ale jego użycie nie jest zalecane.

Klasy przedstawione w poniższej tabeli służą do konstruowania wiadomości e-mail, które można wysyłać przy użyciu polecenia SmtpClient.

Klasa	Opis
Attachment	Reprezentuje załączniki plików. Ta klasa umożliwia dołączanie plików, strumieni lub tekstu do wiadomości e-mail.
MailAddress	Reprezentuje adres e-mail nadawcy i adresatów.
MailMessage	Reprezentuje wiadomość e-mail.

Aby skonstruować i wysłać wiadomość e-mail przy użyciu metody SmtpClient, należy określić następujące informacje:

• Serwer hosta SMTP używany do wysyłania wiadomości e-mail. Host Zobacz właściwości iPort.

• Poświadczenia uwierzytelniania, jeśli jest to wymagane przez serwer SMTP. Credentials Zobacz właściwość .

• Adres e-mail nadawcy. Send Zobacz metody iSendAsync, które przyjmują from parametr . Zobacz MailMessage.From również właściwość .

• Adres e-mail lub adresy adresatów. Send Zobacz metody iSendAsync, które przyjmują recipient parametr . Zobacz MailMessage.To również właściwość .

• Zawartość wiadomości. Send Zobacz metody iSendAsync, które przyjmują body parametr . Zobacz MailMessage.Body również właściwość .

Aby dołączyć załącznik z wiadomością e-mail, najpierw utwórz załącznik przy użyciu Attachment klasy, a następnie dodaj go do wiadomości przy użyciu MailMessage.Attachments właściwości . W zależności od czytnika wiadomości e-mail używanego przez adresatów i typu pliku załącznika niektórzy adresaci mogą nie być w stanie odczytać załącznika. W przypadku klientów, którzy nie mogą wyświetlić załącznika w oryginalnym formularzu, można określić widoki alternatywne przy użyciu MailMessage.AlternateViews właściwości .

W .NET Framework można użyć plików konfiguracji aplikacji lub maszyny, aby określić domyślne wartości hostów, portów i poświadczeń dla wszystkich SmtpClient obiektów. Aby uzyskać więcej informacji, zobacz <mailSettings> , element (ustawienia sieci). Platforma .NET Core nie obsługuje ustawień domyślnych. Aby obejść ten problem, należy ustawić odpowiednie właściwości SmtpClient bezpośrednio.

Aby wysłać wiadomość e-mail i zablokować podczas oczekiwania na przesłanie wiadomości e-mail na serwer SMTP, użyj jednej z metod synchronicznych Send . Aby umożliwić głównemu wątkowi programu kontynuowanie wykonywania podczas przesyłania wiadomości e-mail, użyj jednej z metod asynchronicznych SendAsync . Zdarzenie SendCompleted jest wywoływane po zakończeniu SendAsync operacji. Aby odebrać to zdarzenie, musisz dodać delegata SendCompletedEventHandler do SendCompletedelementu . Delegat SendCompletedEventHandler musi odwoływać się do metody wywołania zwrotnego obsługującej powiadomienia o zdarzeniach SendCompleted . Aby anulować asynchroniczną transmisję wiadomości e-mail, użyj SendAsyncCancel metody .

Uwaga

Jeśli trwa przesyłanie wiadomości e-mail i dzwonisz lub Send ponownie, otrzymasz SendAsync wiadomość InvalidOperationException.

Połączenie ustanowione przez bieżące wystąpienie SmtpClient klasy do serwera SMTP może być ponownie używane, jeśli aplikacja chce wysłać wiele komunikatów do tego samego serwera SMTP. Jest to szczególnie przydatne, gdy uwierzytelnianie lub szyfrowanie jest używane do nawiązywania połączenia z serwerem SMTP. Proces uwierzytelniania i ustanawiania sesji protokołu TLS może być kosztowny. Wymaganie ponownego nawiązania połączenia dla każdej wiadomości podczas wysyłania dużej ilości wiadomości e-mail do tego samego serwera SMTP może mieć znaczący wpływ na wydajność. Istnieje wiele dużych aplikacji poczty e-mail, które wysyłają aktualizacje stanu poczty e-mail, dystrybucje biuletynów lub alerty e-mail. Wiele aplikacji klienckich poczty e-mail obsługuje tryb pozawierszowy, w którym użytkownicy mogą tworzyć wiele wiadomości e-mail wysyłanych później po nawiązaniu połączenia z serwerem SMTP. Zazwyczaj klient poczty e-mail wysyła wszystkie wiadomości SMTP do określonego serwera SMTP (dostarczonego przez dostawcę usług internetowych), który następnie przekazuje tę wiadomość e-mail do innych serwerów SMTP.

Implementacja SmtpClient klasy tworzy pule połączeń SMTP, aby uniknąć narzutów związanych z ponownym ustanawianiem połączenia dla każdego komunikatu na tym samym serwerze. Aplikacja może ponownie używać tego samego SmtpClient obiektu do wysyłania wielu różnych wiadomości e-mail na ten sam serwer SMTP i do wielu różnych serwerów SMTP. W związku z tym nie ma możliwości określenia, kiedy aplikacja została zakończona przy użyciu SmtpClient obiektu i powinna zostać wyczyszczona.

Po zakończeniu sesji SMTP i zakończeniu połączenia klient musi wysłać komunikat QUIT do serwera, aby wskazać, że nie ma więcej komunikatów do wysłania. Dzięki temu serwer może zwolnić zasoby skojarzone z połączeniem z klientem i przetworzyć komunikaty, które zostały wysłane przez klienta.

Klasa SmtpClient nie Finalize ma metody, więc aplikacja musi wywołać metodę Dispose , aby jawnie zwolnić zasoby. Metoda Dispose wykonuje iterację po wszystkich ustanowionych połączeniach z serwerem SMTP określonym we Host właściwości i wysyła komunikat QUIT, a następnie bezpiecznie kończąc połączenie TCP. Metoda Dispose zwalnia również niezarządzane zasoby używane przez Socket program i opcjonalnie usuwa zasoby zarządzane.

Po Dispose zakończeniu połączenia użyj polecenia SmtpClient. Metoda Dispose pozostawia SmtpClient obiekt w stanie bezużytecznym. Po wywołaniu Disposemetody należy zwolnić wszystkie odwołania do SmtpClient modułu , aby moduł odśmiecania pamięci mógł odzyskać pamięć zajmowaną przez SmtpClient moduł.

Konstruktory

SmtpClient()	Inicjuje SmtpClient nowe wystąpienie klasy przy użyciu ustawień pliku konfiguracji.
SmtpClient(String)	Inicjuje SmtpClient nowe wystąpienie klasy, która wysyła wiadomość e-mail przy użyciu określonego serwera SMTP.
SmtpClient(String, Int32)	Inicjuje SmtpClient nowe wystąpienie klasy, która wysyła wiadomość e-mail przy użyciu określonego serwera SMTP i portu.

Właściwości

ClientCertificates	Określ, które certyfikaty mają być używane do ustanawiania połączenia Secure Sockets Layer (SSL).
Credentials	Pobiera lub ustawia poświadczenia używane do uwierzytelniania nadawcy.
DeliveryFormat	Pobiera lub ustawia format dostarczania używany przez SmtpClient program do wysyłania wiadomości e-mail.
DeliveryMethod	Określa sposób obsługi wychodzących wiadomości e-mail.
EnableSsl	Określ, SmtpClient czy do szyfrowania połączenia używa protokołu Secure Sockets Layer (SSL).
Host	Pobiera lub ustawia nazwę lub adres IP hosta używanego do transakcji SMTP.
PickupDirectoryLocation	Pobiera lub ustawia folder, w którym aplikacje zapisują wiadomości e-mail do przetworzenia przez lokalny serwer SMTP.
Port	Pobiera lub ustawia port używany do transakcji SMTP.
ServicePoint	Pobiera połączenie sieciowe używane do przesyłania wiadomości e-mail.
TargetName	Pobiera lub ustawia nazwę dostawcy usług (SPN) do użycia do uwierzytelniania w przypadku korzystania z rozszerzonej ochrony.
Timeout	Pobiera lub ustawia wartość określającą czas, po którym przekroczono limit czasu synchronicznego Send wywołania.
UseDefaultCredentials	Pobiera lub ustawia wartość, która określa Boolean , czy DefaultCredentials są wysyłane z żądaniami.

Metody

Dispose()	Wysyła komunikat QUIT do serwera SMTP, bezpiecznie kończy połączenie TCP i zwalnia wszystkie zasoby używane przez bieżące wystąpienie SmtpClient klasy.
Dispose(Boolean)	Wysyła komunikat QUIT do serwera SMTP, bezpiecznie kończy połączenie TCP, zwalnia wszystkie zasoby używane przez bieżące wystąpienie SmtpClient klasy i opcjonalnie usuwa zasoby zarządzane.
Equals(Object)	Określa, czy dany obiekt jest taki sam, jak bieżący obiekt. (Odziedziczone po Object)
GetHashCode()	Służy jako domyślna funkcja skrótu. (Odziedziczone po Object)
GetType()	Type Pobiera bieżące wystąpienie. (Odziedziczone po Object)
MemberwiseClone()	Tworzy płytkią kopię bieżącego Objectelementu . (Odziedziczone po Object)
OnSendCompleted(AsyncCompletedEventArgs)	SendCompleted Zgłasza zdarzenie.
Send(MailMessage)	Wysyła określony komunikat do serwera SMTP na potrzeby dostarczania.
Send(String, String, String, String)	Wysyła określoną wiadomość e-mail do serwera SMTP na potrzeby dostarczania. Nadawca wiadomości, adresaci, temat i treść wiadomości są określane przy użyciu String obiektów.
SendAsync(MailMessage, Object)	Wysyła określoną wiadomość e-mail do serwera SMTP na potrzeby dostarczania. Ta metoda nie blokuje wątku wywołującego i umożliwia obiektowi wywołującego przekazanie obiektu do metody wywoływanej po zakończeniu operacji.
SendAsync(String, String, String, String, Object)	Wysyła wiadomość e-mail do serwera SMTP na potrzeby dostarczania. Nadawca wiadomości, adresaci, temat i treść wiadomości są określane przy użyciu String obiektów. Ta metoda nie blokuje wątku wywołującego i umożliwia obiektowi wywołującego przekazanie obiektu do metody wywoływanej po zakończeniu operacji.
SendAsyncCancel()	Anuluje operację asynchroniczną, aby wysłać wiadomość e-mail.
SendMailAsync(MailMessage)	Wysyła określony komunikat do serwera SMTP na potrzeby dostarczania jako operację asynchroniczną.
SendMailAsync(MailMessage, CancellationToken)	Wysyła określony komunikat do serwera SMTP na potrzeby dostarczania jako operację asynchroniczną.
SendMailAsync(String, String, String, String)	Wysyła określony komunikat do serwera SMTP na potrzeby dostarczania jako operację asynchroniczną. Nadawca wiadomości, adresaci, temat i treść wiadomości są określane przy użyciu String obiektów.
SendMailAsync(String, String, String, String, CancellationToken)	Wysyła określony komunikat do serwera SMTP na potrzeby dostarczania jako operację asynchroniczną przy użyciu określonego nadawcy, adresatów, podmiotu i ciągów treści.
ToString()	Zwraca ciąg reprezentujący bieżący obiekt. (Odziedziczone po Object)

Zdarzenia

SendCompleted

Występuje po zakończeniu asynchronicznej operacji wysyłania wiadomości e-mail.

Zobacz też

• System.Net.Mime
• Programowanie dla sieci w .NET Framework
• Przykłady programowania sieciowego
• Śledzenie sieci w .NET Framework
• Zabezpieczenia w programowaniu sieciowym