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