DatagramSocket sample

This sample shows you how to a use datagram (UDP) socket to send and receive data using the DatagramSocket and related classes in the Windows.Networking.Sockets namespace in your Windows Runtime app.

Note This sample was created using one of the universal app templates available in Visual Studio. It shows how its solution is structured so it can run on both Windows 8.1 and Windows Phone 8.1. For more info about how to build apps that target Windows and Windows Phone with Visual Studio, see Build apps that target Windows and Windows Phone 8.1 by using Visual Studio.

The client component of the sample creates a UDP socket, uses the socket to send and receive data, and closes the socket. The server component of the sample creates a UDP socket to listen for incoming network packets, receives incoming UDP packets from the client, sends data to the client, and closes the socket. This sample is provided in the JavaScript, C#, and C++ programming languages.

The client component of the sample demonstrates the following features:

Use the DatagramSocket class to create a UDP socket for the client to send and receive data.
Add a handler for a DatagramSocket.MessageReceived event that indicates that a UDP datagram was received on the DatagramSocket object.
Set the remote endpoint for a UDP network server where packets should be sent using one of the DatagramSocket.ConnectAsync methods.
Send data to the server using the Streams.DataWriter object which allows a programmer to write common types (integers and strings, for example) on any stream.
Close the socket.

The server component of the sample demonstrates the following features:

Use the DatagramSocket class to create a UDP socket to listen for and receive incoming datagram packets and for sending packets.
Add a handler for a DatagramSocket.MessageReceived event that indicates that a UDP datagram was received on the DatagramSocket object.
Bind the socket to a local service name to listen for incoming UDP packets using the DatagramSocket.BindServiceNameAsync method.
Receive a DatagramSocket.MessageReceived event that indicates that a UDP datagram was received on the DatagramSocket object.
Receive data from the client using the DatagramSocket.MessageReceived handler. The DatagramSocketMessageReceivedEventArgs object passed to the DatagramSocket.MessageReceived handler allows an app to receive data from the client and also determine the remote address and port that sent the data.
Close the socket.

Note Use of this sample requires network access using the loopback interface.

For a sample that shows how to use a stream (TCP) socket to send and receive data in a Windows Runtime app, download the StreamSocket sample.

Network capabilities

This sample requires that network capabilities be set in the Package.appxmanifest file to allow the app to access the network at runtime. These capabilities can be set in the app manifest using Microsoft Visual Studio.

To build the Windows version of the sample, set the following network capabilities:

Private Networks (Client & Server): The sample has inbound and outbound network access on a home or work network (a local intranet). Even though this sample by default runs on loopback, it needs either the Private Networks (Client & Server) or Internet (Client & Server) capability in order to send and receive UDP packets using a DatagramSocket. The Private Networks (Client & Server) capability is represented by the Capability name = "privateNetworkClientServer" tag in the app manifest. The Internet (Client & Server) capability is represented by the Capability name = "internetClientServer" tag in the app manifest.
If the sample is modified to connect to the server component running on a different device on the Internet (a more typical app), the Internet (Client) capability must be set for the client component. This is represented by the Capability name = "internetClient".
If the sample is modified so the server component is running on a different device on the Internet (a more typical app), the Internet (Client & Server) capability must be set for the server component. This is represented by the Capability name = "internetClientServer" tag in the app manifest.

To build the Windows Phone version of the sample, set the following network capabilities:

Internet (Client & Server): This sample has complete access to the network for both client operations (outbound-initiated access) and server operations (inbound-initiated access). This allows the app to send and receive UDP packets using a DatagramSocket with another device on the Internet or on a local intranet. This is represented by the Capability name = "internetClientServer" tag in the app manifest.

Note On Windows Phone, there is only one network capability which enables all network access for the app.

For more information on network capabilities, see How to set network capabilities.

Note Network communications using an IP loopback address cannot normally be used for interprocess communication between a Windows Runtime app and a different process (a different Windows Runtime app or a desktop app) because this is restricted by network isolation. Network communication using an IP loopback address is allowed within the same process for communication purposes in a Windows Runtime app. For more information, see How to set network capabilities.

To obtain an evaluation copy of Windows 8.1, go to Windows 8.1.

To obtain an evaluation copy of Microsoft Visual Studio 2013 Update 2, go to Microsoft Visual Studio 2013.

Note For Windows 8 app samples, download the Windows 8 app samples pack. The samples in the Windows 8 app samples pack will build and run only on Microsoft Visual Studio 2012.

Operating system requirements

Client	Windows 8.1
Server	Windows Server 2012 R2
Phone	Windows Phone 8.1

Build the sample

Start Visual Studio 2013 Update 2 and select File > Open > Project/Solution.
Go to the directory to which you unzipped the sample. Go to the directory named for the sample, and double-click the Visual Studio 2013 Update 2 Solution (.sln) file.
Follow the steps for the version of the sample you want:
- To build the Windows version of the sample:
  1. Select DatagramSocket.Windows in Solution Explorer.
  2. Press Ctrl+Shift+B, or use Build > Build Solution, or use Build > Build DatagramSocket.Windows.
- To build the Windows Phone version of the sample:
  1. Select DatagramSocket.WindowsPhone in Solution Explorer.
  2. Press Ctrl+Shift+B or use Build > Build Solution or use Build > Build DatagramSocket.WindowsPhone.

Run the sample

The next steps depend on whether you just want to deploy the sample or you want to both deploy and run it.

Deploying the sample

To deploy the built Windows version of the sample:
1. Select DatagramSocket.Windows in Solution Explorer.
2. Use Build > Deploy Solution or Build > Deploy DatagramSocket.Windows.
To deploy the built Windows Phone version of the sample:
1. Select DatagramSocket.WindowsPhone in Solution Explorer.
2. Use Build > Deploy Solution or Build > Deploy DatagramSocket.WindowsPhone.

Deploying and running the sample

To deploy and run the Windows version of the sample:
1. Right-click DatagramSocket.Windows in Solution Explorer and select Set as StartUp Project.
2. To debug the sample and then run it, press F5 or use Debug > Start Debugging. To run the sample without debugging, press Ctrl+F5 or use Debug > Start Without Debugging.
To deploy and run the Windows Phone version of the sample:
1. Right-click DatagramSocket.WindowsPhone in Solution Explorer and select Set as StartUp Project.
2. To debug the sample and then run it, press F5 or use Debug > Start Debugging. To run the sample without debugging, press Ctrl+F5 or use Debug > Start Without Debugging.

Related topics

Operating system requirements

Build the sample

Run the sample