Cette documentation est archivée et n’est pas conservée.

Ping, classe

Remarque : cette classe est nouvelle dans le .NET Framework version 2.0.

Permet à une application de déterminer si un ordinateur distant est accessible sur le réseau.

Espace de noms : System.Net.NetworkInformation
Assembly : System (dans system.dll)

public class Ping : Component, IDisposable
public class Ping extends Component implements IDisposable
public class Ping extends Component implements IDisposable

Les applications utilisent la classe Ping pour détecter si un ordinateur distant est accessible.

La topologie de réseau peut déterminer si Ping peut contacter un hôte distant avec succès. La présence et la configuration des proxies, le matériel de traduction d'adresses réseau ou les pare-feu peuvent empêcher Ping de réussir. Un Ping réussi indique uniquement que l'hôte distant peut être atteint sur le réseau ; la présence de services de niveau supérieur (tels qu'un serveur Web) sur l'hôte distant n'est pas garantie.

Cette classe fournit une fonctionnalité semblable à l'outil de ligne de commande Ping.exe. Les méthodes Send et SendAsync envoient un message ICMP (Internet Control Message Protocol) de demande d'écho à un ordinateur distant et attendent de recevoir un message ICMP de réponse à écho de cet ordinateur. Pour une description détaillée des messages ICMP, consultez la RFC 792, disponible à l'adresse http://www.ietf.org.

Les types suivants sont utilisés avec la classe Ping et sont décrits en détail ci-dessous.

Nom de type

Description

IPStatus

Définit des codes d'état qui décrivent le résultat d'un message de demande d'écho ICMP.

PingOptions

Vous permet de configurer ou de récupérer les paramètres qui contrôlent combien de fois le paquet demandé peut être transféré (Ttl) et s'il peut être fragmenté (DontFragment).

PingReply

Contient les résultats d'une demande d'écho ICMP.

PingException

Levée si une erreur irrécupérable se produit.

PingCompletedEventArgs

Contient les données associées aux événements PingCompleted qui sont déclenchés lorsqu'un appel SendAsync se termine ou est annulé.

PingCompletedEventHandler

Délégué qui fournit la méthode de rappel appelée lorsqu'un appel SendAsync se termine ou est annulé.

Les méthodes Send et SendAsync retournent la réponse dans un objet PingReply. La propriété PingReply.Status retourne une valeur IPStatus pour indiquer le résultat de la demande.

Lorsque vous envoyez la demande, vous devez spécifier l'ordinateur distant. Vous pouvez fournir pour cela une chaîne de nom d'hôte, une adresse IP sous forme de chaîne ou un objet IPAddress.

Vous pouvez également spécifier l'un des types d'informations suivants :

  • Données accompagnant la demande. buffer vous permet de connaître la durée nécessaire au déplacement d'un paquet de taille donnée vers et à partir de l'hôte distant et l'unité de transmission maximale du chemin d'accès réseau. (Consultez les surcharges Send ou SendAsync qui prennent un paramètre buffer.)

  • Si le paquet d'écho ICMP peut être fragmenté en transit. (Consultez la propriété DontFragment et les surcharges Send ou SendAsync qui prennent un paramètre options.)

  • Combien de fois des nœuds de routage, tels que des routeurs ou des passerelles, peuvent transférer le paquet avant qu'il n'atteigne l'ordinateur de destination ou qu'il soit ignoré. (Consultez Ttl et les surcharges Send ou SendAsync qui prennent un paramètre options.)

  • Délai imparti pour la réception de la réponse. (Consultez les surcharges Send ou SendAsync qui prennent un paramètre timeout.)

La classe Ping propose des méthodes synchrones et asynchrones pour envoyer la demande. Si votre application doit être bloquée en attendant une réponse, utilisez les méthodes Send ; ces méthodes sont synchrones. Si votre application ne doit pas être bloquée, utilisez les méthodes SendAsync asynchrones. Un appel à SendAsync est exécuté dans son propre thread qui est alloué automatiquement à partir du pool de threads. Lorsque l'opération asynchrone se termine, elle déclenche l'événement PingCompleted. Les applications utilisent un délégué PingCompletedEventHandler pour spécifier la méthode appelée pour les événements PingCompleted. Vous devez ajouter un délégué PingCompletedEventHandler à l'événement avant d'appeler SendAsync. La méthode du délégué reçoit un objet PingCompletedEventArgs qui contient un objet PingReply qui décrit le résultat de l'appel SendAsync.

Vous ne pouvez pas utiliser la même instance de la classe Ping pour générer plusieurs demandes d'écho ICMP simultanées. L'appel à Send pendant qu'un appel SendAsync est en cours ou l'appel à SendAsync plusieurs fois avant que tous les appels précédents ne soient terminés provoque une exception InvalidOperationException.

L'exemple de code suivant illustre l'utilisation de la classe Ping de manière synchrone.

using System;
using System.Net;
using System.Net.NetworkInformation;
using System.Text;

namespace Examples.System.Net.NetworkInformation.PingTest
{
    public class PingExample
    {
        // args[0] can be an IPaddress or host name.
        public static void Main (string[] args)
        {
            Ping pingSender = new Ping ();
            PingOptions options = new PingOptions ();

            // Use the default Ttl value which is 128,
            // but change the fragmentation behavior.
            options.DontFragment = true;

            // Create a buffer of 32 bytes of data to be transmitted.
            string data = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
            byte[] buffer = Encoding.ASCII.GetBytes (data);
            int timeout = 120;
            PingReply reply = pingSender.Send (args[0], timeout, buffer, options);
            if (reply.Status == IPStatus.Success)
            {
                Console.WriteLine ("Address: {0}", reply.Address.ToString ());
                Console.WriteLine ("RoundTrip time: {0}", reply.RoundtripTime);
                Console.WriteLine ("Time to live: {0}", reply.Options.Ttl);
                Console.WriteLine ("Don't fragment: {0}", reply.Options.DontFragment);
                Console.WriteLine ("Buffer size: {0}", reply.Buffer.Length);
            }
        }
    }
}

L'exemple de code suivant illustre l'utilisation de la classe Ping de manière asynchrone.

using System;
using System.Text;
using System.Net;
using System.Net.NetworkInformation;
using System.ComponentModel;
using System.Threading;

namespace Examples.System.Net.NetworkInformation.PingTest
{
    public class PingExample
    {
        public static void Main (string[] args)
        {
            if (args.Length == 0)
                throw new ArgumentException ("Ping needs a host or IP Address.");

            string who = args[0];
            AutoResetEvent waiter = new AutoResetEvent (false);

            Ping pingSender = new Ping ();

            // When the PingCompleted event is raised,
            // the PingCompletedCallback method is called.
            pingSender.PingCompleted += new PingCompletedEventHandler (PingCompletedCallback);

            // Create a buffer of 32 bytes of data to be transmitted.
            string data = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
            byte[] buffer = Encoding.ASCII.GetBytes (data);

            // Wait 12 seconds for a reply.
            int timeout = 12000;

            // Set options for transmission:
            // The data can go through 64 gateways or routers
            // before it is destroyed, and the data packet
            // cannot be fragmented.
            PingOptions options = new PingOptions (64, true);

            Console.WriteLine ("Time to live: {0}", options.Ttl);
            Console.WriteLine ("Don't fragment: {0}", options.DontFragment);

            // Send the ping asynchronously.
            // Use the waiter as the user token.
            // When the callback completes, it can wake up this thread.
            pingSender.SendAsync(who, timeout, buffer, options, waiter);

            // Prevent this example application from ending.
            // A real application should do something useful
            // when possible.
            waiter.WaitOne ();
            Console.WriteLine ("Ping example completed.");
        }

        public static void PingCompletedCallback (object sender, PingCompletedEventArgs e)
        {
            // If the operation was canceled, display a message to the user.
            if (e.Cancelled)
            {
                Console.WriteLine ("Ping canceled.");

                // Let the main thread resume. 
                // UserToken is the AutoResetEvent object that the main thread 
                // is waiting for.
                ((AutoResetEvent)e.UserState).Set ();
            }

            // If an error occurred, display the exception to the user.
            if (e.Error != null)
            {
                Console.WriteLine ("Ping failed:");
                Console.WriteLine (e.Error.ToString ());

                // Let the main thread resume. 
                ((AutoResetEvent)e.UserState).Set();
            }

            PingReply reply = e.Reply;

            DisplayReply (reply);

            // Let the main thread resume.
            ((AutoResetEvent)e.UserState).Set();
        }

        public static void DisplayReply (PingReply reply)
        {
            if (reply == null)
                return;

            Console.WriteLine ("ping status: {0}", reply.Status);
            if (reply.Status == IPStatus.Success)
            {
                Console.WriteLine ("Address: {0}", reply.Address.ToString ());
                Console.WriteLine ("RoundTrip time: {0}", reply.RoundtripTime);
                Console.WriteLine ("Time to live: {0}", reply.Options.Ttl);
                Console.WriteLine ("Don't fragment: {0}", reply.Options.DontFragment);
                Console.WriteLine ("Buffer size: {0}", reply.Buffer.Length);
            }
        }
    }
}

System.Object
   System.MarshalByRefObject
     System.ComponentModel.Component
      System.Net.NetworkInformation.Ping

Les membres statiques publics (Shared en Visual Basic) de ce type sont thread-safe. Il n'est pas garanti que les membres d'instance soient thread-safe.

Windows 98, Windows 2000 SP4, Windows Millennium Edition, Windows Server 2003, Windows XP Édition Media Center, Windows XP Professionnel Édition x64, Windows XP SP2, Windows XP Starter Edition

Le .NET Framework ne prend pas en charge toutes les versions de chaque plate-forme. Pour obtenir la liste des versions prises en charge, consultez Configuration requise.

.NET Framework

Prise en charge dans : 2.0
Afficher: