Scénarios courants
S’applique à : Windows Server 2022, Windows Server 2019
Scénario : HCN
Créer un HCN
Cet exemple montre comment utiliser l’API de service de réseau de calcul hôte pour créer un réseau de calcul hôte sur l’hôte qui peut être utilisé pour connecter des cartes réseau virtuelles à des Machines Virtuelles ou des conteneurs.
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);
}
}
Supprimer un HCN
Cet exemple montre comment utiliser l’API de service de réseau de calcul hôte pour ouvrir & Supprimer un réseau de calcul hôte
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);
}
Énumérer tous les réseaux
Cet exemple montre comment utiliser l’API Du service de réseau de calcul hôte pour énumérer tous les réseaux de calcul hôtes.
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);
}
Interroger les propriétés du réseau
Cet exemple montre comment utiliser l’API de service réseau de calcul hôte pour interroger les propriétés du réseau.
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);
}
Scénario : point de terminaison HCN
Créer un point de terminaison HCN
Cet exemple montre comment utiliser l’API de service de réseau de calcul hôte pour créer un point de terminaison de réseau de calcul hôte, puis l’ajouter à chaud à la machine virtuelle ou à un conteneur.
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);
}
}
Supprimer un point de terminaison
Cet exemple montre comment utiliser l’API de service de réseau de calcul hôte pour supprimer un point de terminaison de réseau de calcul hôte.
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);
}
Modifier un point de terminaison
Cet exemple montre comment utiliser l’API de service de réseau de calcul hôte pour modifier un point de terminaison de réseau de calcul hôte.
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);
}
Énumérer tous les points de terminaison
Cet exemple montre comment utiliser l’API Du service de réseau de calcul hôte pour énumérer tous les points de terminaison de réseau de calcul hôte.
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);
}
Propriétés du point de terminaison de requête
Cet exemple montre comment utiliser l’API de service de réseau de calcul hôte pour interroger toutes les propriétés d’un point de terminaison de réseau de calcul hôte.
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);
}
Scénario : espace de noms HCN
Créer un espace de noms HCN
Cet exemple montre comment utiliser l’API de service de réseau de calcul hôte pour créer un espace de noms de réseau de calcul hôte sur l’hôte qui peut être utilisé pour connecter des points de terminaison et des conteneurs.
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);
}
}
Supprimer un espace de noms HCN
Cet exemple montre comment utiliser l’API de service de réseau de calcul hôte pour supprimer un espace de noms de réseau de calcul hôte.
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);
}
Supprimer un espace de noms HCN
Cet exemple montre comment utiliser l’API Du service de réseau de calcul hôte pour modifier un espace de noms de réseau de calcul hôte.
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);
}
Énumérer tous les espaces de noms
Cet exemple montre comment utiliser l’API de service de réseau de calcul hôte pour énumérer tous les espaces de noms de réseau de calcul hôte.
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);
}
Propriétés de l’espace de noms de requête
Cet exemple montre comment utiliser l’API de service de réseau de calcul hôte pour interroger les propriétés de l’espace de noms du réseau de calcul hôte
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);
}
Scénario : équilibreur de charge HCN
Créer un équilibreur de charge HCN
Cet exemple montre comment utiliser l’API de service de réseau de calcul hôte pour créer un réseau de calcul hôte Équilibreur de charge sur l’hôte qui peut être utilisé pour équilibrer la charge du point de terminaison entre le calcul.
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);
}
}
Supprimer un équilibreur de charge HCN
Cet exemple montre comment utiliser l’API de service de réseau de calcul hôte pour supprimer un équilibreur de charge de réseau de calcul hôte.
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);
}
Modifier un équilibreur de charge HCN
Cet exemple montre comment utiliser l’API de service de réseau de calcul hôte pour modifier un équilibreur de charge de réseau de calcul hôte.
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);
}
Énumérer tous les équilibreurs de charge
Cet exemple montre comment utiliser l’API de service de réseau de calcul hôte pour énumérer toutes les équilibreurs de charge du réseau de calcul hôte.
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);
}
Requête propriétés de l’équilibreur de charge
Cet exemple montre comment utiliser l’API de service de réseau de calcul hôte pour interroger les propriétés équilibreur de charge du réseau de calcul hôte.
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);
}
Scénario : notifications HCN
Inscrire et annuler l’inscription des notifications à l’échelle du service
Cet exemple montre comment utiliser l’API de service réseau de calcul hôte pour inscrire et annuler l’inscription aux notifications à l’échelle du service. Cela permet à l’appelant de recevoir une notification (via la fonction de rappel qu’il a spécifiée lors de l’inscription) chaque fois qu’une opération à l’échelle du service telle qu’un événement de création de réseau s’est produite.
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();
}
Étapes suivantes
- En savoir plus sur les handles de contexte RPC pour HCN.
- En savoir plus sur les schémas de document JSON HCN.