Esta documentación está archivada y no tiene mantenimiento.

Ping (Clase)

Nota: esta clase es nueva en la versión 2.0 de .NET Framework.

Permite que una aplicación determine si un equipo remoto está accesible a través de la red.

Espacio de nombres: System.Net.NetworkInformation
Ensamblado: System (en system.dll)

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

Las aplicaciones utilizan la clase Ping para detectar si un equipo remoto es alcanzable.

La topología de red puede determinar si Ping puede ponerse en contacto con un host remoto. La presencia y configuración de servidores proxy, equipos de traducción de direcciones de red (NAT) o firewalls pueden evitar que Ping tenga éxito. Un Ping correcto sólo indica que el host remoto se puede alcanzar en la red; no garantiza la presencia de servicios de un nivel superior (como un servidor Web) en el host remoto.

Esta clase proporciona una funcionalidad similar a la herramienta de línea de comandos Ping.exe. Los métodos Send y SendAsync envían un mensaje de solicitud de eco ICPM (Protocolo de mensajes de control de Internet) a un equipo remoto y esperan un mensaje de respuesta de eco ICMP de ese equipo. Para obtener una descripción detallada de mensajes ICMP, vea RFC 792, disponible en http://www.ietf.org.

Los tipos siguientes se utilizan con la clase Ping y se describen en detalle a continuación.

Nombre de tipo

Descripción

IPStatus

Define códigos de estado que describen el resultado de un mensaje de solicitud de eco ICMP.

PingOptions

Permite configurar o recuperar la configuración que controla cuántas veces se puede reenviar el paquete de solicitud (Ttl) y si se puede fragmentar (DontFragment).

PingReply

Contiene los resultados de un mensaje de solicitud de eco ICMP.

PingException

Se produce si se tiene lugar un error irrecuperable.

PingCompletedEventArgs

Contiene los datos asociados a eventos PingCompleted que se provocan cuando finaliza o se cancela una llamada a SendAsync.

PingCompletedEventHandler

El delegado que proporciona el método de devolución de llamada invocado cuando finaliza o se cancela una llamada a SendAsync.

Los métodos Send y SendAsync devuelven la respuesta en un objeto PingReply. La propiedad PingReply.Status devuelve un valor IPStatus para indicar el resultado de la solicitud.

Al enviar la solicitud, se debe especificar el equipo remoto. Se puede hacer esto proporcionando una cadena con el nombre de host, una dirección IP en formato de cadena o un objeto IPAddress.

También se puede especificar alguno de los tipos siguientes de información:

  • Datos que acompañan a la solicitud. Si se especifica buffer es posible comprobar cuánto tiempo necesita un paquete de un tamaño determinado para llegar al host remoto y volver de él, y la unidad de transmisión máxima de la ruta de acceso a la red. (Vea las sobrecargas de Send o SendAsync que toman un parámetro buffer).

  • Si el paquete de eco ICMP se puede fragmentar durante la transmisión. (Vea la propiedad DontFragment y las sobrecargas de Send o SendAsync que toman un parámetro options).

  • Número de veces que los nodos de enrutamiento, como enrutadores o puertas de enlace, pueden reenviar el paquete antes de que alcance el equipo de destino o sea descartado. (Vea Ttl y las sobrecargas de Send o SendAsync que toman un parámetro options).

  • El límite de tiempo para recibir la respuesta. (Vea las sobrecargas de Send o SendAsync que toman un parámetro timeout).

La clase Ping proporciona los métodos sincrónicos y asincrónicos para enviar la solicitud. Si la aplicación debe bloquearse mientras espera una respuesta, utilice los métodos Send; estos métodos son sincrónicos. Si la aplicación no debe bloquearse, utilice los métodos SendAsync asincrónicos. Una llamada a SendAsync se ejecuta en su propio subproceso que se asigna automáticamente del grupo de subprocesos. Cuando la operación asincrónica finaliza, provoca el evento PingCompleted. Las aplicaciones utilizan un delegado de PingCompletedEventHandler para especificar el método al que se llama para eventos PingCompleted. Debe agregar un delegado de PingCompletedEventHandler al evento antes de llamar a SendAsync. El método del delegado recibe un objeto PingCompletedEventArgs que contiene un objeto PingReply que describe el resultado de la llamada a SendAsync.

No puede utilizar la misma instancia de la clase Ping para generar varios mensajes de solicitud de eco ICMP simultáneos. Si se llama a Send mientras está en curso una llamada a SendAsync o si se llama varias veces a SendAsync antes de que todas las llamadas anteriores finalicen, se produce una excepción InvalidOperationException.

En el siguiente ejemplo de código se muestra cómo se utiliza sincrónicamente la clase Ping.

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);
            }
        }
    }
}

En el siguiente ejemplo de código se muestra cómo se utiliza asincrónicamente la clase Ping.

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

Los miembros estáticos públicos (Shared en Visual Basic) de este tipo son seguros para la ejecución de subprocesos. No se garantiza que los miembros de instancias sean seguros para la ejecución de subprocesos.

Windows 98, Windows 2000 SP4, Windows Millennium, Windows Server 2003, Windows XP Media Center, Windows XP Professional x64, Windows XP SP2, Windows XP Starter Edition

.NET Framework no admite todas las versiones de cada plataforma. Para obtener una lista de las versiones admitidas, vea Requisitos del sistema.

.NET Framework

Compatible con: 2.0
Mostrar: