Узел службы
Узел службы — это среда выполнения для размещения службы в процессе.
Служба может настроить одну или несколько конечных точек внутри узла службы.
Создание узла службы
Перед созданием узла службы необходимо определить конечные точки службы. Конечная точка в узле службы указывается в структуре 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 через UDP, представленные WS_UDP_CHANNEL_BINDING в перечислении WS_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);
Сведения о присоединении настраиваемого состояния к узлу службы см. в состоянии узла пользователя
Сведения об авторизации в узле службы для данной конечной точки см. в авторизации службы.
Сведения о реализации операций служб и контрактов служб для службы см. в разделах операций службы и контракта службы .
Безопасность
Приложение может использовать следующие свойства для управления объемом ресурсов, выделяемых узлом службы от имени приложения:
- 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.
Безопасные значения по умолчанию выбираются для каждого из этих свойств, приложение должно быть осторожным, если он хочет изменить эти свойства. Помимо указанных выше свойств канала, прослушивателя и сообщения определенные свойства также могут быть изменены приложением. Прежде чем изменять любой из этих параметров, обратитесь к рекомендациям по безопасности этих компонентов.
Кроме того, при использовании API узла службы WWSAPI следует тщательно оценивать следующие рекомендации по проектированию приложений:
- При использовании 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 | Сбрасывает узел службы для повторного использования и сбрасывает базовый канал и прослушиватели для повторного использования. |
| Ручка | Описание |
|---|---|
| WS_SERVICE_HOST | Непрозрачный тип, используемый для ссылки на узел службы. |
| Структура | Описание |
|---|---|
| WS_SERVICE_ENDPOINT | Представляет отдельную конечную точку на узле службы. |
| WS_SERVICE_ENDPOINT_PROPERTY | Указывает параметр для конкретной службы. |
| WS_SERVICE_PROPERTY | Указывает параметр для конкретной службы. |
| WS_SERVICE_PROPERTY_ACCEPT_CALLBACK | Указывает обратный вызов, который вызывается при успешном принятии канала. |
| WS_SERVICE_PROPERTY_CLOSE_CALLBACK | Указывает обратный вызов, который вызывается при закрытии канала. |