Common scenarios
Applies to: Windows Server 2022, Windows Server 2019
Scenario: HCN
Create a HCN
This sample shows how to use Host Compute Network Service API to create a Host Compute Network on the host that can be used to connect Virtual NICS to Virtual Machines or Containers.
using unique_hcn_network = wil::unique_any<
HCN_NETWORK,
decltype(&HcnCloseNetwork),
HcnCloseNetwork>;
/// Creates a simple HCN Network, waiting synchronously to finish the task
void CreateHcnNetwork()
{
unique_hcn_network hcnnetwork;
wil::unique_cotaskmem_string result;
std::wstring settings = LR"(
{
"SchemaVersion": {
"Major": 2,
"Minor": 0
},
"Owner" : "WDAGNetwork",
"Flags" : 0,
"Type" : 0,
"Ipams" : [
{
"Type" : 0,
"Subnets" : [
{
"IpAddressPrefix" : "192.168.1.0/24",
"Policies" : [
{
"Type" : "VLAN",
"IsolationId" : 100,
}
],
"Routes" : [
{
"NextHop" : "192.168.1.1",
"DestinationPrefix" : "0.0.0.0/0",
}
]
}
],
},
],
"MacPool": {
"Ranges" : [
{
"EndMacAddress": "00-15-5D-52-CF-FF",
"StartMacAddress": "00-15-5D-52-C0-00"
}
],
},
"Dns" : {
"Suffix" : "net.home",
"ServerList" : ["10.0.0.10"],
}
}
})";
GUID networkGuid;
HRESULT result = CoCreateGuid(&networkGuid);
result = HcnCreateNetwork(
networkGuid, // Unique ID
settings.c_str(), // Compute system settings document
&hcnnetwork,
&result
);
if (FAILED(result))
{
// UnMarshal the result Json
// ErrorSchema
// {
// "ErrorCode" : <uint32>,
// "Error" : <string>,
// "Success" : <bool>,
// }
// Failed to create network
THROW_HR(result);
}
// Close the Handle
result = HcnCloseNetwork(hcnnetwork.get());
if (FAILED(result))
{
// UnMarshal the result Json
THROW_HR(result);
}
}
Delete a HCN
This sample shows how to use Host Compute Network Service API to Open & Delete a Host Compute Network
wil::unique_cotaskmem_string errorRecord;
GUID networkGuid; // Initialize it to appropriate network guid value
HRESULT hr = HcnDeleteNetwork(networkGuid, &errorRecord);
if (FAILED(hr))
{
// UnMarshal the result Json
THROW_HR(hr);
}
Enumerate all networks
This sample shows how to use Host Compute Network Service API to enumerate all host compute networks.
wil::unique_cotaskmem_string resultNetworks;
wil::unique_cotaskmem_string errorRecord;
// Filter to select Networks based on properties
std::wstring filter [] = LR"(
{
"Name" : "WDAG",
})";
HRESULT result = HcnEnumerateNetworks(filter.c_str(), &resultNetworks, &errorRecord);
if (FAILED(result))
{
// UnMarshal the result Json
THROW_HR(result);
}
Query network properties
This sample shows how to use Host Compute Network Service API to query network properties.
unique_hcn_network hcnnetwork;
wil::unique_cotaskmem_string errorRecord;
wil::unique_cotaskmem_string properties;
std:wstring query = LR"(
{
// Future
})";
GUID networkGuid; // Initialize it to appropriate network guid value
HRESULT hr = HcnOpenNetwork(networkGuid, &hcnnetwork, &errorRecord);
if (FAILED(hr))
{
// UnMarshal the result Json
THROW_HR(hr);
}
hr = HcnQueryNetworkProperties(hcnnetwork.get(), query.c_str(), &properties, &errorRecord);
if (FAILED(hr))
{
// UnMarshal the result Json
THROW_HR(hr);
}
Scenario: HCN endpoint
Create a HCN endpoint
This sample shows how to use Host Compute Network Service API to create a Host Compute Network Endpoint and then hot add it to the Virtual Machine or a Container.
using unique_hcn_endpoint = wil::unique_any<
HCN_ENDPOINT,
decltype(&HcnCloseEndpoint),
HcnCloseEndpoint>;
void CreateAndHotAddEndpoint()
{
unique_hcn_endpoint hcnendpoint;
unique_hcn_network hcnnetwork;
wil::unique_cotaskmem_string errorRecord;
std::wstring settings[] = LR"(
{
"SchemaVersion": {
"Major": 2,
"Minor": 0
},
"Owner" : "Sample",
"Flags" : 0,
"HostComputeNetwork" : "87fdcf16-d210-426e-959d-2a1d4f41d6d3",
"DNS" : {
"Suffix" : "net.home",
"ServerList" : "10.0.0.10",
}
})";
GUID endpointGuid;
HRESULT result = CoCreateGuid(&endpointGuid);
result = HcnOpenNetwork(
networkGuid, // Unique ID
&hcnnetwork,
&errorRecord
);
if (FAILED(result))
{
// Failed to find network
THROW_HR(result);
}
result = HcnCreateEndpoint(
hcnnetwork.get(),
endpointGuid, // Unique ID
settings.c_str(), // Compute system settings document
&hcnendpoint,
&errorRecord
);
if (FAILED(result))
{
// Failed to create endpoint
THROW_HR(result);
}
// Can use the sample from HCS API Spec on how to attach this endpoint
// to the VM using AddNetworkAdapterToVm
result = HcnCloseEndpoint(hcnendpoint.get());
if (FAILED(result))
{
// UnMarshal the result Json
THROW_HR(result);
}
}
Delete an endpoint
This sample shows how to use Host Compute Network Service API to delete a Host Compute Network Endpoint.
wil::unique_cotaskmem_string errorRecord;
GUID endpointGuid; // Initialize it to appropriate endpoint guid value
HRESULT hr = HcnDeleteEndpoint(endpointGuid, &errorRecord);
if (FAILED(hr))
{
// UnMarshal the result Json
THROW_HR(hr);
}
Modify an endpoint
This sample shows how to use Host Compute Network Service API to modify a Host Compute Network Endpoint.
unique_hcn_endpoint hcnendpoint;
GUID endpointGuid; // Initialize it to appropriate endpoint guid value
HRESULT hr = HcnOpenEndpoint(endpointGuid, &hcnendpoint, &errorRecord);
if (FAILED(hr))
{
// UnMarshal the result Json
THROW_HR(hr);
}
std::wstring ModifySettingAddPortJson = LR"(
{
"ResourceType" : 0,
"RequestType" : 0,
"Settings" : {
"PortName" : "acbd341a-ec08-44c0-9d5e-61af0ee86902"
"VirtualNicName" : "641313e1-7ae8-4ddb-94e5-3215f3a0b218--87fdcf16-d210-426e-959d-2a1d4f41d6d1"
"VirtualMachineId" : "641313e1-7ae8-4ddb-94e5-3215f3a0b218"
}
}
)";
hr = HcnModifyEndpoint(hcnendpoint.get(), ModifySettingAddPortJson.c_str(), &errorRecord);
if (FAILED(hr))
{
// UnMarshal the result Json
THROW_HR(hr);
}
Enumerate all endpoints
This sample shows how to use Host Compute Network Service API to enumerate all Host Compute Network Endpoints.
wil::unique_cotaskmem_string errorRecord;
wil::unique_cotaskmem_string resultEndpoints;
wil::unique_cotaskmem_string errorRecord;
// Filter to select Endpoint based on properties
std::wstring filter [] = LR"(
{
"Name" : "sampleNetwork",
})";
result = HcnEnumerateEndpoints(filter.c_str(), &resultEndpoints, &errorRecord);
if (FAILED(result))
{
THROW_HR(result);
}
Query endpoint properties
This sample shows how to use Host Compute Network Service API to query all properties of a Host Compute Network Endpoint.
unique_hcn_endpoint hcnendpoint;
wil::unique_cotaskmem_string errorRecord;
GUID endpointGuid; // Initialize it to appropriate endpoint guid value
HRESULT hr = HcnOpenEndpoint(endpointGuid, &hcnendpoint, &errorRecord);
if (FAILED(hr))
{
// UnMarshal the result Json
THROW_HR(hr);
}
wil::unique_cotaskmem_string properties;
std:wstring query = LR"(
{
// Future
})";
hr = HcnQueryEndpointProperties(hcnendpoint.get(), query.c_str(), &properties, &errorRecord);
if (FAILED(hr))
{
// UnMarshal the errorRecord Json
THROW_HR(hr);
}
Scenario: HCN namespace
Create a HCN namespace
This sample shows how to use Host Compute Network Service API to create a Host Compute Network Namespace on the host that can be used to connect Endpoint and Containers.
using unique_hcn_namespace = wil::unique_any<
HCN_NAMESPACE,
decltype(&HcnCloseNamespace),
HcnCloseNamespace>;
/// Creates a simple HCN Network, waiting synchronously to finish the task
void CreateHcnNamespace()
{
unique_hcn_namespace handle;
wil::unique_cotaskmem_string errorRecord;
std::wstring settings = LR"(
{
"SchemaVersion": {
"Major": 2,
"Minor": 0
},
"Owner" : "Sample",
"Flags" : 0,
"Type" : 0,
})";
GUID namespaceGuid;
HRESULT result = CoCreateGuid(&namespaceGuid);
result = HcnCreateNamespace(
namespaceGuid, // Unique ID
settings.c_str(), // Compute system settings document
&handle,
&errorRecord
);
if (FAILED(result))
{
// UnMarshal the result Json
// ErrorSchema
// {
// "ErrorCode" : <uint32>,
// "Error" : <string>,
// "Success" : <bool>,
// }
// Failed to create network
THROW_HR(result);
}
result = HcnCloseNamespace(handle.get());
if (FAILED(result))
{
// UnMarshal the result Json
THROW_HR(result);
}
}
Delete a HCN namespace
This sample shows how to use Host Compute Network Service API to delete a Host Compute Network Namespace.
wil::unique_cotaskmem_string errorRecord;
GUID namespaceGuid; // Initialize it to appropriate namespace guid value
HRESULT hr = HcnDeleteNamespace(namespaceGuid, &errorRecord);
if (FAILED(hr))
{
// UnMarshal the result Json
THROW_HR(hr);
}
Modify a HCN namespace
This sample shows how to use Host Compute Network Service API to modify a Host Compute Network Namespace.
unique_hcn_namespace handle;
GUID namespaceGuid; // Initialize it to appropriate namespace guid value
HRESULT hr = HcnOpenNamespace(namespaceGuid, &handle, &errorRecord);
if (FAILED(hr))
{
// UnMarshal the result Json
THROW_HR(hr);
}
wil::unique_cotaskmem_string errorRecord;
static std::wstring ModifySettingAddEndpointJson = LR"(
{
"ResourceType" : 1,
"RequestType" : 0,
"Settings" : {
"EndpointId" : "87fdcf16-d210-426e-959d-2a1d4f41d6d1"
}
}
)";
hr = HcnModifyNamespace(handle.get(), ModifySettingAddEndpointJson.c_str(), &errorRecord);
if (FAILED(hr))
{
// UnMarshal the result Json
THROW_HR(hr);
}
hr = HcnCloseNamespace(handle.get());
if (FAILED(hr))
{
// UnMarshal the result Json
THROW_HR(hr);
}
Enumerate all namespaces
This sample shows how to use Host Compute Network Service API to enumerate all Host Compute Network Namespaces.
wil::unique_cotaskmem_string resultNamespaces;
wil::unique_cotaskmem_string errorRecord;
std::wstring filter [] = LR"(
{
// Future
})";
HRESULT hr = HcnEnumerateNamespace(filter.c_str(), &resultNamespaces, &errorRecord);
if (FAILED(hr))
{
// UnMarshal the result Json
THROW_HR(hr);
}
Query namespace properties
This sample shows how to use Host Compute Network Service API to query Host Compute Network Namespace properties
unique_hcn_namespace handle;
GUID namespaceGuid; // Initialize it to appropriate namespace guid value
HRESULT hr = HcnOpenNamespace(namespaceGuid, &handle, &errorRecord);
if (FAILED(hr))
{
// UnMarshal the result Json
THROW_HR(hr);
}
wil::unique_cotaskmem_string errorRecord;
wil::unique_cotaskmem_string properties;
std:wstring query = LR"(
{
// Future
})";
HRESULT hr = HcnQueryNamespaceProperties(handle.get(), query.c_str(), &properties, &errorRecord);
if (FAILED(hr))
{
// UnMarshal the result Json
THROW_HR(hr);
}
Scenario: HCN load balancer
Create a HCN load balancer
This sample shows how to use Host Compute Network Service API to create a Host Compute Network Load Balancer on the host that can be used to load balance Endpoint across compute.
using unique_hcn_loadbalancer = wil::unique_any<
HCN_LOADBALANCER,
decltype(&HcnCloseLoadBalancer),
HcnCloseLoadBalancer>;
/// Creates a simple HCN LoadBalancer, waiting synchronously to finish the task
void CreateHcnLoadBalancer()
{
unique_hcn_loadbalancer handle;
wil::unique_cotaskmem_string errorRecord;
std::wstring settings = LR"(
{
"SchemaVersion": {
"Major": 2,
"Minor": 0
},
"Owner" : "Sample",
"HostComputeEndpoints" : [
"87fdcf16-d210-426e-959d-2a1d4f41d6d1"
],
"VirtualIPs" : [ "10.0.0.10" ],
"PortMappings" : [
{
"Protocol" : 0,
"InternalPort" : 8080,
"ExternalPort" : 80,
}
],
"EnableDirectServerReturn" : true,
"InternalLoadBalancer" : false,
}
)";
GUID lbGuid;
HRESULT result = CoCreateGuid(&lbGuid);
HRESULT hr = HcnCreateLoadBalancer(
lbGuid, // Unique ID
settings.c_str(), // LoadBalancer settings document
&handle,
&errorRecord
);
if (FAILED(hr))
{
// UnMarshal the result Json
// ErrorSchema
// {
// "ErrorCode" : <uint32>,
// "Error" : <string>,
// "Success" : <bool>,
// }
// Failed to create network
THROW_HR(hr);
}
hr = HcnCloseLoadBalancer(handle.get());
if (FAILED(hr))
{
// UnMarshal the result Json
THROW_HR(hr);
}
}
Delete a HCN load balancer
This sample shows how to use Host Compute Network Service API to delete a Host Compute Network Load Balancer.
wil::unique_cotaskmem_string errorRecord;
GUID lbGuid; // Initialize it to appropriate loadbalancer guid value
HRESULT hr = HcnDeleteLoadBalancer(lbGuid , &errorRecord);
if (FAILED(hr))
{
// UnMarshal the result Json
THROW_HR(hr);
}
Modify a HCN load balancer
This sample shows how to use Host Compute Network Service API to modify a Host Compute Network Load Balancer.
unique_hcn_loadbalancer handle;
GUID lbGuid; // Initialize it to appropriate loadbalancer guid value
HRESULT hr = HcnOpenLoadBalancer(lbGuid, &handle, &errorRecord);
if (FAILED(hr))
{
// UnMarshal the result Json
THROW_HR(hr);
}
wil::unique_cotaskmem_string errorRecord;
static std::wstring ModifySettingAddEndpointJson = LR"(
{
"ResourceType" : 1,
"RequestType" : 0,
"Settings" : {
"EndpointId" : "87fdcf16-d210-426e-959d-2a1d4f41d6d1"
}
}
)";
hr = HcnModifyLoadBalancer(handle.get(), ModifySettingAddEndpointJson.c_str(), &errorRecord);
if (FAILED(hr))
{
// UnMarshal the result Json
THROW_HR(hr);
}
hr = HcnCloseLoadBalancer(handle.get());
if (FAILED(hr))
{
// UnMarshal the result Json
THROW_HR(hr);
}
Enumerate all load balancers
This sample shows how to use Host Compute Network Service API to enumerate all Host Compute Network Load Balancer.
wil::unique_cotaskmem_string resultLoadBalancers;
wil::unique_cotaskmem_string errorRecord;
std::wstring filter [] = LR"(
{
// Future
})";
HRESULT result = HcnEnumerateLoadBalancers(filter.c_str(), & resultLoadbalancers, &errorRecord);
if (FAILED(result))
{
// UnMarshal the result Json
THROW_HR(result);
}
Query load balancer properties
This sample shows how to use Host Compute Network Service API to query Host Compute Network Load Balancer properties.
unique_hcn_loadbalancer handle;
GUID lbGuid; // Initialize it to appropriate loadbalancer guid value
HRESULT hr = HcnOpenLoadBalancer(lbGuid, &handle, &errorRecord);
if (FAILED(hr))
{
// UnMarshal the result Json
THROW_HR(hr);
}
wil::unique_cotaskmem_string errorRecord;
wil::unique_cotaskmem_string properties;
std:wstring query = LR"(
{
"ID" : "",
"Type" : 0,
})";
hr = HcnQueryNProperties(handle.get(), query.c_str(), &properties, &errorRecord);
if (FAILED(hr))
{
// UnMarshal the result Json
THROW_HR(hr);
}
Scenario: HCN notifications
Register and unregister service-wide notifications
This sample demonstrates how to use the Host Compute Network Service API to register and unregister for service-wide notifications. This enables the caller to receive a notification (via the callback function they specified during registration) whenever a service-wide operation such as a new network creation event has occurred.
using unique_hcn_callback = wil::unique_any<
HCN_CALLBACK,
decltype(&HcnUnregisterServiceCallback),
HcnUnregisterServiceCallback>;
// Callback handle returned by registration api. Kept at
// global or module scope as it will automatically be
// unregistered when it goes out of scope.
unique_hcn_callback g_Callback;
// Event notification callback function.
void
CALLBACK
ServiceCallback(
DWORD NotificationType,
void* Context,
HRESULT NotificationStatus,
PCWSTR NotificationData)
{
// Optional client context
UNREFERENCED_PARAMETER(context);
// Reserved for future use
UNREFERENCED_PARAMETER(NotificationStatus);
switch (NotificationType)
{
case HcnNotificationNetworkCreate:
// TODO: UnMarshal the NotificationData
//
// // Notification
// {
// "ID" : Guid,
// "Flags" : <uint32>,
// };
break;
case HcnNotificationNetworkDelete:
// TODO: UnMarshal the NotificationData
break;
Default:
// TODO: handle other events.
break;
}
}
/// Register for service-wide notifications
void RegisterForServiceNotifications()
{
THROW_IF_FAILED(HcnRegisterServiceCallback(
ServiceCallback,
nullptr,
&g_Callback));
}
/// Unregister from service-wide notifications
void UnregisterForServiceNotifications()
{
// As this is a unique_hcn_callback, this will cause HcnUnregisterServiceCallback to be invoked
g_Callback.reset();
}
Next steps
- Learn more about the RPC context handles for HCN.
- Learn more about the HCN JSON document schemas.
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for