Share via

HostName Class

Definition

Namespace:
Windows.Networking
Edit

Represents a host name or IP address (domain, IPv4, IPv6, or Bluetooth) used by Windows networking APIs.

public ref class HostName sealed : IStringable
/// [Windows.Foundation.Metadata.Activatable(Windows.Networking.IHostNameFactory, 65536, Windows.Foundation.UniversalApiContract)]
/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class HostName final : IStringable
/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
/// [Windows.Foundation.Metadata.Activatable(Windows.Networking.IHostNameFactory, 65536, "Windows.Foundation.UniversalApiContract")]
class HostName final : IStringable
[Windows.Foundation.Metadata.Activatable(typeof(Windows.Networking.IHostNameFactory), 65536, typeof(Windows.Foundation.UniversalApiContract))]
[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public sealed class HostName : IStringable
[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
[Windows.Foundation.Metadata.Activatable(typeof(Windows.Networking.IHostNameFactory), 65536, "Windows.Foundation.UniversalApiContract")]
public sealed class HostName : IStringable
function HostName(hostName)
Public NotInheritable Class HostName
Implements IStringable
Inheritance
Object Platform::Object IInspectable HostName
Attributes
ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute
Implements
IStringable

Windows requirements

Device family
Windows 10 (introduced in 10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced in v1.0)
App capabilities
internetClient privateNetworkClientServer

Examples

The following example creates a HostName and then tries to connect to the HostName using a StreamSocket.

using Windows.Networking;
using Windows.Networking.Sockets;

HostName serverHost = new HostName("www.contoso.com");
StreamSocket clientSocket = new Windows.Networking.Sockets.StreamSocket();

// Try to connect to the remote host
await clientSocket.ConnectAsync(serverHost, "http");

#include <winrt/Windows.Networking.Sockets.h>
using namespace winrt;

int main()
{
    winrt::init_apartment();

    Windows::Networking::HostName hostName{ L"www.contoso.com" };
    Windows::Networking::Sockets::StreamSocket streamSocket;
    // Try to connect.
    streamSocket.ConnectAsync(hostName, L"http").get();
}

using namespace Windows::Networking;
using namespace Windows::Networking::Sockets;

HostName^ serverHost= ref new HostName("www.contoso.com");
StreamSocket^ clientSocket = ref new StreamSocket();

// Try to connect to the remote host
clientSocket->ConnectAsync(serverHost, "http");

Remarks

Purpose

Encapsulates a network host identifier (domain, literal IP, or Bluetooth address) for use by higher-level APIs (sockets, connectivity queries, Wi‑Fi Direct).

Types

<xref href="Windows.Networking.HostName.Type?text=Type" /> distinguishes: | Type | Example | | -- | -- | | DomainName | www.contoso.com | | Ipv4 | 192.168.1.1 | | Ipv6 | 2001:db8::1 | | Bluetooth | 12:34:56:78:9A:BC |

Key properties

Property Meaning
RawName Original input string
DisplayName Friendly / formatted representation
CanonicalName Normalized form (useful for comparisons / logging)
IPInformation Interface/IP metadata when bound to a local address

Usage patterns

Scenario Guidance
Socket connect Pass a HostName plus service name to StreamSocket.ConnectAsync / DatagramSocket.ConnectAsync
Endpoint pairing Combine in an EndpointPair for local/remote mapping
Local enumeration Use NetworkInformation.GetHostNames

Creation

var domain  = new HostName("www.contoso.com");
var ipv4    = new HostName("192.168.1.1");
var ipv6    = new HostName("2001:db8::1");

Comparison

Use IsEqual instead of string comparison (canonicalization & type awareness).

Best practices

  • Validate expected Type before use (e.g., require literal IP vs domain if policy demands).
  • Prefer domain names over hard-coded IPs to benefit from DNS / load balancing.
  • Cache resolution results only briefly; allow the platform to re-resolve for failover.

Security considerations

  • Never assume a domain resolves to the same IP indefinitely; re-resolve for long-lived sessions as appropriate.
  • Log canonical + raw forms for diagnostics, excluding user-entered sensitive hostnames if privacy policy restricts.

Note

A HostName does not perform DNS resolution until used by an API that needs an address.

Constructors

HostName(String)

Creates a new HostName object from a string that contains a hostname or an IP address.

Properties

CanonicalName

Gets the canonical name for the HostName object.
DisplayName

Gets the display name for the HostName object.
IPInformation

Gets the IPInformation object for a local IP address assigned to a HostName object.
RawName

Gets the original string used to construct the HostName object.
Type

Gets the HostNameType of the HostName object.

Methods

Compare(String, String)

Compares two strings to determine if they represent the same hostname.
IsEqual(HostName)

Determines whether the specified HostName object has an equivalent value to the current HostName object.
ToString()

Returns a string that represents the HostName object.

Applies to

See also