Ping Class

Reference

Definition

Namespace:: System.Net.NetworkInformation

Assembly:: System.Net.Ping.dll

Assembly:: System.dll

Assembly:: netstandard.dll

Source:: Ping.cs

Source:: Ping.cs

Source:: Ping.cs

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Allows an application to determine whether a remote computer is accessible over the network.

public ref class Ping : System::ComponentModel::Component

public ref class Ping : IDisposable

public ref class Ping : System::ComponentModel::Component, IDisposable

public class Ping : System.ComponentModel.Component

public class Ping : IDisposable

public class Ping : System.ComponentModel.Component, IDisposable

type Ping = class
    inherit Component

type Ping = class
    interface IDisposable

type Ping = class
    inherit Component
    interface IDisposable

Public Class Ping
Inherits Component

Public Class Ping
Implements IDisposable

Public Class Ping
Inherits Component
Implements IDisposable

Inheritance: Object

MarshalByRefObject

Component
Ping

Inheritance: Object
Ping

Implements: IDisposable

Examples

The following code example demonstrates using the Ping class synchronously.

#using <System.dll>

using namespace System;
using namespace System::Net;
using namespace System::Net::NetworkInformation;
using namespace System::Text;

// args[1] can be an IPaddress or host name.
int main()
{
   array<String^>^args = Environment::GetCommandLineArgs();
   
   Ping ^ pingSender = gcnew Ping;
   PingOptions ^ options = gcnew 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";
   array<Byte>^buffer = Encoding::ASCII->GetBytes( data );
   int timeout = 120;
   PingReply ^ reply = pingSender->Send( args[ 1 ], 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 );
   }

   
}

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

open System.Net.NetworkInformation
open System.Text

// args[0] can be an IPaddress or host name.
[<EntryPoint>]
let main args =
    let pingSender = new Ping()

    // Use the default Ttl value which is 128,
    // but change the fragmentation behavior.
    let options = PingOptions()
    options.DontFragment <- true

    // Create a buffer of 32 bytes of data to be transmitted.
    let data = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    let buffer = Encoding.ASCII.GetBytes data
    let timeout = 120
    let reply: PingReply = pingSender.Send(args.[0], timeout, buffer, options)

    match reply.Status with
    | IPStatus.Success ->
        printfn "Address: %O" reply.Address
        printfn "RoundTrip time: %d" reply.RoundtripTime
        printfn "Time to live: %d" reply.Options.Ttl
        printfn "Don't fragment: %b" reply.Options.DontFragment
        printfn "Buffer size: %d" reply.Buffer.Length
        0
    | _ ->
        eprintfn "Error sending ping: %O" reply
        eprintfn "Error was: %O" reply.Status
        1

The following code example demonstrates using the Ping class asynchronously.

#using <System.dll>

using namespace System;
using namespace System::Text;
using namespace System::Net;
using namespace System::Net::NetworkInformation;
using namespace System::ComponentModel;
using namespace System::Threading;
void PingCompletedCallback( Object^ sender, PingCompletedEventArgs^ e );
void DisplayReply( PingReply^ reply );
int main()
{
   array<String^>^args = Environment::GetCommandLineArgs();
   if ( args->Length == 1 )
      throw gcnew ArgumentException( "Ping needs a host or IP Address." );

   String^ who = args[ 1 ];
   AutoResetEvent^ waiter = gcnew AutoResetEvent( false );
   
   Ping ^ pingSender = gcnew Ping;
   
   // When the PingCompleted event is raised,
   // the PingCompletedCallback method is called.
   pingSender->PingCompleted += gcnew PingCompletedEventHandler( PingCompletedCallback );
   
   // Create a buffer of 32 bytes of data to be transmitted.
   String^ data = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
   array<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 = gcnew 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." );
}


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.
      (dynamic_cast<AutoResetEvent^>(e->UserState))->Set();
   }

   
   // If an error occurred, display the exception to the user.
   if ( e->Error != nullptr )
   {
      Console::WriteLine( "Ping failed:" );
      Console::WriteLine( e->Error->ToString() );
      
      // Let the main thread resume. 
      (dynamic_cast<AutoResetEvent^>(e->UserState))->Set();
   }

   PingReply ^ reply = e->Reply;
   DisplayReply( reply );
   
   // Let the main thread resume.
   (dynamic_cast<AutoResetEvent^>(e->UserState))->Set();
}


void DisplayReply( PingReply ^ reply )
{
   if ( reply == nullptr )
      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 );
   }
}

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

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

Remarks

Applications use the Ping class to detect whether a remote computer is reachable.

Network topology can determine whether Ping can successfully contact a remote host. The presence and configuration of proxies, network address translation (NAT) equipment, or firewalls can prevent Ping from succeeding. A successful Ping indicates only that the remote host can be reached on the network; the presence of higher level services (such as a Web server) on the remote host is not guaranteed.

This class provides functionality similar to the Ping.exe command line tool. The Send and SendAsync methods send an Internet Control Message Protocol (ICMP) echo request message to a remote computer and wait for an ICMP echo reply message from that computer. For a detailed description of ICMP messages, see RFC 792, available at https://www.ietf.org.

The following types are used with the Ping class and are described in detail below.

Type name	Description
IPStatus	Defines status codes that describe the outcome of an ICMP echo request message.
PingOptions	Allows you to configure or retrieve the settings that control how many times the request packet can be forwarded (Ttl), and whether it can be fragmented (DontFragment ).
PingReply	Contains the results of an ICMP echo request.
PingException	Thrown if an unrecoverable error occurs.
PingCompletedEventArgs	Contains the data associated with PingCompleted events, which are raised when a SendAsync call completes or is canceled.
PingCompletedEventHandler	The delegate that provides the callback method invoked when a SendAsync call completes or is canceled.

The Send and SendAsync methods return the reply in a PingReply object. The PingReply.Status property returns an IPStatus value to indicate the outcome of the request.

When sending the request, you must specify the remote computer. You can do this by providing a host name string, an IP address in string format, or an IPAddress object.

You can also specify any of the following types of information:

Data to accompany the request. Specifying buffer allows you to learn the amount of time required for a packet of a particular size to travel to and from the remote host and the maximum transmission unit of the network path. (See the Send or SendAsync overloads that take a buffer parameter.)
Whether the ICMP Echo packet can be fragmented in transit. (See the DontFragment property and the Send or SendAsync overloads that take an options parameter.)
How many times routing nodes, such as routers or gateways, can forward the packet before it either reaches the destination computer or is discarded. (See Ttl and the Send or SendAsync overloads that take an options parameter.)
The time limit within which the reply must be received. (See the Send or SendAsync overloads that take a timeout parameter.

The Ping class offers both synchronous and asynchronous methods for sending the request. If your application should block while waiting for a reply, use the Send methods; these methods are synchronous. If your application should not block, use the asynchronous SendAsync methods. A call to SendAsync executes in its own thread that is automatically allocated from the thread pool. When the asynchronous operation completes, it raises the PingCompleted event. Applications use a PingCompletedEventHandler delegate to specify the method that is called for PingCompleted events. You must add a PingCompletedEventHandler delegate to the event before calling SendAsync. The delegate's method receives a PingCompletedEventArgs object that contains a PingReply object that describes the result of the SendAsync call.

You cannot use the same instance of the Ping class to generate multiple simultaneous ICMP Echo requests. Calling Send while a SendAsync call is in progress or calling SendAsync multiple times before all previous calls have completed causes an InvalidOperationException.

Constructors

Ping()

Initializes a new instance of the Ping class.

Properties

CanRaiseEvents	Gets a value indicating whether the component can raise an event. (Inherited from Component)
Container	Gets the IContainer that contains the Component. (Inherited from Component)
DesignMode	Gets a value that indicates whether the Component is currently in design mode. (Inherited from Component)
Events	Gets the list of event handlers that are attached to this Component. (Inherited from Component)
Site	Gets or sets the ISite of the Component. (Inherited from Component)

Methods

CreateObjRef(Type)	Creates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object. (Inherited from MarshalByRefObject)
Dispose()	Releases the unmanaged resources and disposes of the managed resources used by the Ping.
Dispose()	Releases all resources used by the Component. (Inherited from Component)
Dispose(Boolean)	Releases the unmanaged resources used by the Ping object, and optionally disposes of the managed resources.
Dispose(Boolean)	Releases the unmanaged resources used by the Component and optionally releases the managed resources. (Inherited from Component)
Equals(Object)	Determines whether the specified object is equal to the current object. (Inherited from Object)
GetHashCode()	Serves as the default hash function. (Inherited from Object)
GetLifetimeService()	Obsolete. Retrieves the current lifetime service object that controls the lifetime policy for this instance. (Inherited from MarshalByRefObject)
GetService(Type)	Returns an object that represents a service provided by the Component or by its Container. (Inherited from Component)
GetType()	Gets the Type of the current instance. (Inherited from Object)
InitializeLifetimeService()	Obsolete. Obtains a lifetime service object to control the lifetime policy for this instance. (Inherited from MarshalByRefObject)
MemberwiseClone()	Creates a shallow copy of the current Object. (Inherited from Object)
MemberwiseClone(Boolean)	Creates a shallow copy of the current MarshalByRefObject object. (Inherited from MarshalByRefObject)
OnPingCompleted(PingCompletedEventArgs)	Raises the PingCompleted event.
Send(IPAddress, Int32, Byte[], PingOptions)	Attempts to send an Internet Control Message Protocol (ICMP) echo message with the specified data buffer to the computer that has the specified IPAddress and receive a corresponding ICMP echo reply message from that computer. This overload allows you to specify a time-out value for the operation and control fragmentation and Time-to-Live values for the ICMP echo message packet.
Send(IPAddress, Int32, Byte[])	Attempts to send an Internet Control Message Protocol (ICMP) echo message with the specified data buffer to the computer that has the specified IPAddress, and receive a corresponding ICMP echo reply message from that computer. This overload allows you to specify a time-out value for the operation.
Send(IPAddress, Int32)	Attempts to send an Internet Control Message Protocol (ICMP) echo message with the specified data buffer to the computer that has the specified IPAddress, and receive a corresponding ICMP echo reply message from that computer. This method allows you to specify a time-out value for the operation.
Send(IPAddress, TimeSpan, Byte[], PingOptions)	Attempts to send an Internet Control Message Protocol (ICMP) echo message to the computer that has the specified IPAddress, and to receive a corresponding ICMP echo reply message from that computer.
Send(IPAddress)	Attempts to send an Internet Control Message Protocol (ICMP) echo message to the computer that has the specified IPAddress, and receive a corresponding ICMP echo reply message from that computer.
Send(String, Int32, Byte[], PingOptions)	Attempts to send an Internet Control Message Protocol (ICMP) echo message with the specified data buffer to the specified computer, and receive a corresponding ICMP echo reply message from that computer. This overload allows you to specify a time-out value for the operation and control fragmentation and Time-to-Live values for the ICMP packet.
Send(String, Int32, Byte[])	Attempts to send an Internet Control Message Protocol (ICMP) echo message with the specified data buffer to the specified computer, and receive a corresponding ICMP echo reply message from that computer. This overload allows you to specify a time-out value for the operation.
Send(String, Int32)	Attempts to send an Internet Control Message Protocol (ICMP) echo message to the specified computer, and receive a corresponding ICMP echo reply message from that computer. This method allows you to specify a time-out value for the operation.
Send(String, TimeSpan, Byte[], PingOptions)	Attempts to send an Internet Control Message Protocol (ICMP) echo message to the specified computer, and to receive a corresponding ICMP echo reply message from that computer.
Send(String)	Attempts to send an Internet Control Message Protocol (ICMP) echo message to the specified computer, and receive a corresponding ICMP echo reply message from that computer.
SendAsync(IPAddress, Int32, Byte[], Object)	Asynchronously attempts to send an Internet Control Message Protocol (ICMP) echo message with the specified data buffer to the computer that has the specified IPAddress, and receive a corresponding ICMP echo reply message from that computer. This overload allows you to specify a time-out value for the operation.
SendAsync(IPAddress, Int32, Byte[], PingOptions, Object)	Asynchronously attempts to send an Internet Control Message Protocol (ICMP) echo message with the specified data buffer to the computer that has the specified IPAddress, and receive a corresponding ICMP echo reply message from that computer. This overload allows you to specify a time-out value for the operation and control fragmentation and Time-to-Live values for the ICMP echo message packet.
SendAsync(IPAddress, Int32, Object)	Asynchronously attempts to send an Internet Control Message Protocol (ICMP) echo message to the computer that has the specified IPAddress, and receive a corresponding ICMP echo reply message from that computer. This overload allows you to specify a time-out value for the operation.
SendAsync(IPAddress, Object)	Asynchronously attempts to send an Internet Control Message Protocol (ICMP) echo message to the computer that has the specified IPAddress, and receive a corresponding ICMP echo reply message from that computer.
SendAsync(String, Int32, Byte[], Object)	Asynchronously attempts to send an Internet Control Message Protocol (ICMP) echo message with the specified data buffer to the specified computer, and receive a corresponding ICMP echo reply message from that computer. This overload allows you to specify a time-out value for the operation.
SendAsync(String, Int32, Byte[], PingOptions, Object)	Asynchronously attempts to send an Internet Control Message Protocol (ICMP) echo message with the specified data buffer to the specified computer, and receive a corresponding ICMP echo reply message from that computer. This overload allows you to specify a time-out value for the operation and control fragmentation and Time-to-Live values for the ICMP packet.
SendAsync(String, Int32, Object)	Asynchronously attempts to send an Internet Control Message Protocol (ICMP) echo message to the specified computer, and receive a corresponding ICMP echo reply message from that computer. This overload allows you to specify a time-out value for the operation.
SendAsync(String, Object)	Asynchronously attempts to send an Internet Control Message Protocol (ICMP) echo message to the specified computer, and receive a corresponding ICMP echo reply message from that computer.
SendAsyncCancel()	Cancels all pending asynchronous requests to send an Internet Control Message Protocol (ICMP) echo message and receives a corresponding ICMP echo reply message.
SendPingAsync(IPAddress, Int32, Byte[], PingOptions)	Sends an Internet Control Message Protocol (ICMP) echo message with the specified data buffer to the computer that has the specified IPAddress, and receives a corresponding ICMP echo reply message from that computer as an asynchronous operation. This overload allows you to specify a time-out value for the operation, a buffer to use for send and receive, and control fragmentation and Time-to-Live values for the ICMP echo message packet.
SendPingAsync(IPAddress, Int32, Byte[])	Send an Internet Control Message Protocol (ICMP) echo message with the specified data buffer to the computer that has the specified IPAddress, and receives a corresponding ICMP echo reply message from that computer as an asynchronous operation. This overload allows you to specify a time-out value for the operation and a buffer to use for send and receive.
SendPingAsync(IPAddress, Int32)	Send an Internet Control Message Protocol (ICMP) echo message with the specified data buffer to the computer that has the specified IPAddress, and receives a corresponding ICMP echo reply message from that computer as an asynchronous operation. This overload allows you to specify a time-out value for the operation.
SendPingAsync(IPAddress, TimeSpan, Byte[], PingOptions, CancellationToken)	Sends an Internet Control Message Protocol (ICMP) echo message with the specified data buffer to the computer that has the specified IPAddress, and receives a corresponding ICMP echo reply message from that computer as an asynchronous operation. This overload allows you to specify a time-out value for the operation, a buffer to use for send and receive, control fragmentation and Time-to-Live values, and a CancellationToken for the ICMP echo message packet.
SendPingAsync(IPAddress)	Send an Internet Control Message Protocol (ICMP) echo message with the specified data buffer to the computer that has the specified IPAddress, and receives a corresponding ICMP echo reply message from that computer as an asynchronous operation.
SendPingAsync(String, Int32, Byte[], PingOptions)	Sends an Internet Control Message Protocol (ICMP) echo message with the specified data buffer to the specified computer, and receive a corresponding ICMP echo reply message from that computer as an asynchronous operation. This overload allows you to specify a time-out value for the operation, a buffer to use for send and receive, and control fragmentation and Time-to-Live values for the ICMP echo message packet.
SendPingAsync(String, Int32, Byte[])	Sends an Internet Control Message Protocol (ICMP) echo message with the specified data buffer to the specified computer, and receive a corresponding ICMP echo reply message from that computer as an asynchronous operation. This overload allows you to specify a time-out value for the operation and a buffer to use for send and receive.
SendPingAsync(String, Int32)	Sends an Internet Control Message Protocol (ICMP) echo message with the specified data buffer to the specified computer, and receive a corresponding ICMP echo reply message from that computer as an asynchronous operation. This overload allows you to specify a time-out value for the operation.
SendPingAsync(String, TimeSpan, Byte[], PingOptions, CancellationToken)	Sends an Internet Control Message Protocol (ICMP) echo message with the specified data buffer to the specified computer, and receives a corresponding ICMP echo reply message from that computer as an asynchronous operation. This overload allows you to specify a time-out value for the operation, a buffer to use for send and receive, control fragmentation and Time-to-Live values, and a CancellationToken for the ICMP echo message packet.
SendPingAsync(String)	Sends an Internet Control Message Protocol (ICMP) echo message with the specified data buffer to the specified computer, and receive a corresponding ICMP echo reply message from that computer as an asynchronous operation.
ToString()	Returns a String containing the name of the Component, if any. This method should not be overridden. (Inherited from Component)
ToString()	Returns a string that represents the current object. (Inherited from Object)

Events

Disposed	Occurs when the component is disposed by a call to the Dispose() method. (Inherited from Component)
PingCompleted	Occurs when an asynchronous operation to send an Internet Control Message Protocol (ICMP) echo message and receive the corresponding ICMP echo reply message completes or is canceled.

Explicit Interface Implementations

IDisposable.Dispose()

Releases all resources used by instances of the Ping class.

Applies to

Share via