服务主机

  • 项目

服务主机是用于在进程中承载服务的运行时环境。

服务可以在服务主机内配置一个或多个终结点。

显示包含服务终结点的服务主机结构的关系图。

创建服务主机

在创建服务主机之前，服务需要定义其终结点。 服务主机中的终结点在 WS_SERVICE_ENDPOINT 结构中指定，由以下信息定义：

WS_SERVICE_ENDPOINT serviceEndpoint = {0};
const WS_SERVICE_ENDPOINT* serviceEndpoints[1];
serviceEndpoints[0] = &serviceEndpoint;
WS_STRING url = WS_STRING_VALUE(L"net.tcp://+/Example");

// Method based service contract for the service
static WS_SERVICE_CONTRACT calculatorContract = 
{
    &calculatorContractDescription, // comes from a generated header.
    NULL,
    &calculatorFunctions, // specified by the application
};

serviceEndpoint.address.url = &url;
serviceEndpoint.binding.channelBinding =  WS_TCP_CHANNEL_BINDING; 
serviceEndpoint.contract = &calculatorContract;  
serviceEndpoint.channelType = WS_CHANNEL_TYPE_DUPLEX_SESSION; 
serviceEndpoint.authorizationCallback = AuthorizationCallback; // Authorization callback.

SOAP over UDP 仅支持单向协定，由 WS_CHANNEL_BINDING 枚举中的 WS_UDP_CHANNEL_BINDING 表示。

定义终结点后，可以将其传递给 WsCreateServiceHost 函数，该函数采用指向 WS_SERVICE_ENDPOINT 结构的指针数组。

HRESULT hr = WsCreateServiceHost (serviceEndpoints, 1, NULL, 0, &host, error);

应用程序可以选择向 WsCreateServiceHost 提供服务属性数组，以在服务主机上配置自定义设置。

应用程序打开服务主机以开始接受客户端请求。

WsOpenServiceHost(serviceHost, NULL, NULL);

打开服务主机后，如果没有其他需要它的操作，应用程序可以将其关闭。 请注意，这不会释放其资源，并且可以通过对 WsResetServiceHost 的后续调用重新打开它。

WsCloseServiceHost(serviceHost, NULL, NULL);

关闭服务主机后，应用程序可能会重置服务主机以供重复使用。

WsResetServiceHost(serviceHost, NULL);

应用程序使用服务主机后，可以通过调用 WsFreeServiceHost 函数来释放与服务主机关联的资源。 请注意，在调用此函数之前，必须调用 WsCloseServiceHost 。

WsFreeServiceHost(serviceHost, NULL);

有关将自定义状态附加到服务主机的信息，请参阅 用户主机状态

有关给定终结点的服务主机中的授权的信息，请参阅 服务授权。

有关为服务实现服务操作和服务协定的 iination，请参阅服务操作和服务协定主题。

安全

应用程序可以使用以下属性来控制服务主机代表应用程序分配的资源量：

为每个属性选择安全默认值，如果应用程序要修改这些属性，则必须小心谨慎。 除了上述属性之外，应用程序还可以修改 通道、 侦听器 和 消息 特定的属性。 在修改这些设置之前，请参阅这些组件的安全注意事项。

此外，在使用 WWSAPI 服务主机 API 时，应仔细评估以下应用程序设计注意事项：

  • 使用 MEX 时，应用程序应注意不要泄露任何敏感数据。 作为缓解措施，如果通过 MEX 公开的数据的性质是敏感的，应用程序可以选择使用至少需要身份验证的安全绑定来配置 MEX 终结点，并使用 WS_SERVICE_SECURITY_CALLBACK实现授权作为终结点的一部分。
  • 默认情况下，通过 WS_SERVICE_PROPERTY_FAULT_DISCLOSURE 属性在 服务主机上禁用错误丰富的错误信息。 应用程序可以自行决定发送丰富的错误信息作为故障的一部分。 但是，这可能会导致信息泄露，因此建议仅针对调试方案更改此设置。
  • 除了对基本配置文件 2.0 和 XML 序列化执行的验证外，服务主机不会对作为服务操作参数的一部分接收的数据内容执行验证。 应用程序负责自行执行所有参数验证。
  • 授权不是作为服务主机的一部分实现的。 但是，应用程序可以使用 WS_SECURITY_DESCRIPTION 和 WS_SERVICE_SECURITY_CALLBACK实现自己的授权方案。
  • 应用程序负责在其终结点上使用安全绑定。 除了在终结点上配置的安全性之外，服务主机不提供任何安全性。

以下 API 元素用于服务主机。

回调 说明
WS_SERVICE_ACCEPT_CHANNEL_CALLBACK 当服务主机在终结点侦听器上接受通道时调用。
WS_SERVICE_CLOSE_CHANNEL_CALLBACK 在终结点上关闭或中止通道时调用。

 

枚举 描述
WS_SERVICE_ENDPOINT_PROPERTY_ID 用于配置 WS_SERVICE_ENDPOINT的可选参数。
WS_SERVICE_HOST_STATE 服务主机可以处于的状态。
WS_SERVICE_PROPERTY_ID 用于配置服务主机的可选参数。

 

函数 说明
WsAbortServiceHost 中断并停止服务主机上的当前操作。
WsCloseServiceHost 关闭所有侦听器，以便客户端不接受任何新通道。
WsCreateServiceHost 创建服务主机。
WsFreeServiceHost 释放与服务主机对象关联的内存。
WsGetServiceHostProperty 检索指定的服务主机属性。
WsOpenServiceHost 打开用于通信的服务主机，并在所有终结点上启动侦听器。
WsResetServiceHost 重置服务主机以供重用，并重置基础通道和侦听器以供重用。

 

Handle 说明
WS_SERVICE_HOST 用于引用服务主机的不透明类型。

 

结构 说明
WS_SERVICE_ENDPOINT 表示服务主机上的单个终结点。
WS_SERVICE_ENDPOINT_PROPERTY 指定特定于服务的设置。
WS_SERVICE_PROPERTY 指定特定于服务的设置。
WS_SERVICE_PROPERTY_ACCEPT_CALLBACK 指定成功接受通道时调用的回调。
WS_SERVICE_PROPERTY_CLOSE_CALLBACK 指定在通道即将关闭时调用的回调。