일반적인 시나리오
적용 대상: Windows Server 2022, Windows Server 2019
시나리오: HCN
HCN 만들기
호스트 컴퓨팅 네트워크 서비스 API로 Virtual NICS를 Virtual Machines 또는 컨테이너에 연결하는 데 사용할 수 있는 호스트에서 호스트 컴퓨팅 네트워크를 만드는 방법을 보여 주는 샘플입니다.
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);
}
}
HCN 삭제
이 샘플에서는 호스트 컴퓨팅 네트워크 서비스 API를 사용하여 호스트 컴퓨팅 네트워크를 열고 & 삭제하는 방법을 보여줍니다.
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);
}
모든 네트워크 열거하기
이 샘플에서는 호스트 컴퓨팅 네트워크 서비스 API를 사용하여 모든 호스트 컴퓨팅 네트워크를 열고 삭제하는 방법을 보여줍니다.
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);
}
쿼리 네트워크 속성
이 샘플에서는 호스트 컴퓨팅 네트워크 서비스 API를 사용하여 네트워크 속성을 쿼리하는 방법을 보여줍니다.
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);
}
시나리오: HCN 엔드포인트
HCN 엔드포인트 생성하기
이 샘플에서는 호스트 컴퓨팅 네트워크 서비스 API를 사용하여 호스트 컴퓨팅 네트워크 엔드포인트를 만든 다음 가상 머신 또는 컨테이너에 핫 추가하는 방법을 보여 줍니다.
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);
}
}
엔드포인트 삭제
이 샘플에서는 호스트 컴퓨팅 네트워크 서비스 API를 사용하여 호스트 컴퓨팅 네트워크 엔드포인트를 삭제하는 방법을 보여줍니다.
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);
}
엔드포인트 수정하기
이 샘플에서는 호스트 컴퓨팅 네트워크 서비스 API를 사용하여 호스트 컴퓨팅 네트워크 엔드포인트를 수정하는 방법을 보여줍니다.
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);
}
모든 엔드포인트 열거하기
이 샘플에서는 호스트 컴퓨팅 네트워크 서비스 API를 사용하여 모든 호스트 컴퓨팅 네트워크 엔드포인트를 열거하는 방법을 보여줍니다.
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);
}
쿼리 엔드포인트 속성
이 샘플에서는 호스트 컴퓨팅 네트워크 서비스 API를 사용하여 호스트 컴퓨팅 네트워크 엔드포인트의 모든 속성을 쿼리하는 방법을 보여줍니다.
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);
}
시나리오: HCN 네임스페이스
HCN 네임스페이스 생성하기
이 샘플에서는 호스트 컴퓨팅 네트워크 서비스 API를 사용하여 호스트에서 엔드포인트 및 컨테이너를 연결하는 데 사용할 수 있는 호스트 컴퓨팅 네트워크 네임스페이스를 만드는 방법을 보여 줍니다.
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);
}
}
HCN 네임스페이스 삭제
이 샘플에서는 호스트 컴퓨팅 네트워크 서비스 API를 사용하여 호스트 컴퓨팅 네트워크 네임스페이스를 삭제하는 방법을 보여줍니다.
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);
}
HCN 네임스페이스 수정하기
이 샘플에서는 호스트 컴퓨팅 네트워크 서비스 API를 사용하여 호스트 컴퓨팅 네트워크 네임스페이스를 수정하는 방법을 보여줍니다.
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);
}
모든 네임스페이스 열거하기
이 샘플에서는 호스트 컴퓨팅 네트워크 서비스 API를 사용하여 모든 호스트 컴퓨팅 네트워크 네임스페이스를 열거하는 방법을 보여줍니다.
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);
}
쿼리 네임스페이스 속성
이 샘플에서는 호스트 컴퓨팅 네트워크 서비스 API를 사용하여 호스트 컴퓨팅 네트워크 네임스페이스 속성을 쿼리하는 방법을 보여줍니다.
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);
}
시나리오: HCN 부하 분산 장치
HCN 부하 분산 장치 생성하기
이 샘플에서는 호스트 컴퓨팅 네트워크 서비스 API를 사용하여 호스트에서 엔드포인트의 부하를 분산하는 데 사용할 수 있는 호스트 컴퓨팅 네트워크 부하 분산 장치를 만드는 방법을 보여줍니다.
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);
}
}
HCN 부하 분산 장치 삭제하기
이 샘플에서는 호스트 컴퓨팅 네트워크 서비스 API를 사용하여 호스트 컴퓨팅 네트워크 부하 분산 장치를 삭제하는 방법을 보여줍니다.
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);
}
HCN 부하 분산 장치 수정하기
이 샘플에서는 호스트 컴퓨팅 네트워크 서비스 API를 사용하여 호스트 컴퓨팅 네트워크 부하 분산 장치를 수정하는 방법을 보여줍니다.
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);
}
모든 부하 분산 장치 열거하기
이 샘플에서는 호스트 컴퓨팅 네트워크 서비스 API를 사용하여 호스트 컴퓨팅 네트워크 부하 분산 장치를 열거하는 방법을 보여줍니다.
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);
}
부하 분산 장치 속성 쿼리하기
이 샘플에서는 호스트 컴퓨팅 네트워크 서비스 API를 사용하여 호스트 컴퓨팅 네트워크 부하 분산 장치 속성을 쿼리하는 방법을 보여줍니다.
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);
}
시나리오: HCN 알림
서비스 전체 알림 등록 및 등록 취소
이 샘플에서는 Host Compute Network Service API를 사용하여 서비스 전체 알림을 등록 및 등록 취소하는 방법을 보여 줍니다. 이렇게 하면 새 네트워크 만들기 이벤트와 같은 서비스 차원의 작업이 발생할 때마다 호출자가 등록 중에 지정한 콜백 함수를 통해 알림을 받을 수 있습니다.
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();
}
다음 단계
- HCN에 대한 RPC 컨텍스트 핸들에 대해 자세히 알아보세요.
- HCN JSON 문서 스키마에 대해 자세히 알아보세요.