服务主机
服务主机是用于在进程中承载服务的运行时环境。
服务可以在服务主机内配置一个或多个终结点。
在创建服务主机之前,服务需要定义其终结点。 服务主机中的终结点在 WS_SERVICE_ENDPOINT 结构中指定,由以下信息定义:
- 地址,即承载服务的物理 URI。
- 一个WS_CHANNEL_TYPE结构,指定终结点的基础通道的类型。
- 指定通道绑定的 WS_CHANNEL_BINDING 结构。
- 包含终结点的安全说明 的WS_SECURITY_DESCRIPTION 结构。
- 表示终结点的服务协定的WS_SERVICE_CONTRACT结构。
- 指定终结点的授权回调函数的 WS_SERVICE_SECURITY_CALLBACK 结构。
- 包含服务终结点属性数组 的WS_SERVICE_ENDPOINT_PROPERTY 结构。
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,请参阅服务操作和服务协定主题。
应用程序可以使用以下属性来控制服务主机代表应用程序分配的资源量:
- WS_SERVICE_ENDPOINT_PROPERTY_MAX_ACCEPTING_CHANNELS,
- WS_SERVICE_ENDPOINT_PROPERTY_MAX_CONCURRENCY,
- WS_SERVICE_ENDPOINT_PROPERTY_MAX_CHANNELS,
- WS_SERVICE_ENDPOINT_PROPERTY_BODY_HEAP_MAX_SIZE,
- WS_SERVICE_ENDPOINT_PROPERTY_MAX_CALL_POOL_SIZE,
- WS_SERVICE_ENDPOINT_PROPERTY_MAX_CHANNEL_POOL_SIZE。
为每个属性选择安全默认值,如果应用程序要修改这些属性,则必须小心谨慎。 除了上述属性之外,应用程序还可以修改 通道、 侦听器 和 消息 特定的属性。 在修改这些设置之前,请参阅这些组件的安全注意事项。
此外,在使用 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 | 指定在通道即将关闭时调用的回调。 |