Host de Serviço
O host de serviço é o ambiente de runtime para hospedar um serviço dentro de um processo.
Um serviço pode configurar um ou mais pontos de extremidade dentro de um host de serviço.
Antes de criar um host de serviço, um serviço precisa definir seus pontos de extremidade. Um ponto de extremidade no host de serviço é especificado na estrutura WS_SERVICE_ENDPOINT e é definido pelas seguintes informações:
- Um endereço, que é o URI físico no qual o serviço será hospedado.
- Uma estrutura WS_CHANNEL_TYPE que especifica o tipo do canal subjacente para o ponto de extremidade.
- Uma estrutura WS_CHANNEL_BINDING que especifica a associação do canal.
- Uma estrutura WS_SECURITY_DESCRIPTION que contém a descrição de segurança do ponto de extremidade.
- Uma estrutura WS_SERVICE_CONTRACT que representa o contrato de serviço para o ponto de extremidade.
- Uma estrutura WS_SERVICE_SECURITY_CALLBACK que especifica uma função de retorno de chamada de autorização para o ponto de extremidade.
- Uma estrutura WS_SERVICE_ENDPOINT_PROPERTY que contém uma matriz de propriedades de ponto de extremidade de serviço.
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.
Somente contratos unidirecionais têm suporte para SOAP sobre UDP, representado por WS_UDP_CHANNEL_BINDING na enumeração WS_CHANNEL_BINDING .
Depois que um ponto de extremidade é definido, ele pode ser passado para a função WsCreateServiceHost , que usa uma matriz de ponteiros para WS_SERVICE_ENDPOINT estruturas.
HRESULT hr = WsCreateServiceHost (serviceEndpoints, 1, NULL, 0, &host, error);
Opcionalmente, um aplicativo pode fornecer uma matriz de propriedades de serviço para WsCreateServiceHost para definir configurações personalizadas no host do serviço.
Um aplicativo abre o host de serviço para começar a aceitar solicitações de cliente.
WsOpenServiceHost(serviceHost, NULL, NULL);
Depois de abrir o host de serviço, o aplicativo poderá fechá-lo se não houver mais operações que o exijam. Observe que isso não libera seus recursos e pode ser reaberto com uma chamada subsequente para WsResetServiceHost.
WsCloseServiceHost(serviceHost, NULL, NULL);
Depois de fechar o host de serviço, um aplicativo pode redefinir o host de serviço para reutilização.
WsResetServiceHost(serviceHost, NULL);
Quando o aplicativo terminar com o host de serviço, ele poderá liberar os recursos associados ao host de serviço chamando a função WsFreeServiceHost . Observe que WsCloseServiceHost deve ser chamado antes de chamar essa função.
WsFreeServiceHost(serviceHost, NULL);
Para obter informações sobre como anexar um estado personalizado ao host de serviço, consulte Estado do Host do Usuário
Para obter informações sobre autorização em um host de serviço para um determinado ponto de extremidade, consulte Autorização de serviço.
Para obter informações sobre como implementar operações de serviço e contratos de serviço para um serviço, consulte os tópicos operações de serviço e contrato de serviço.
Um aplicativo pode usar as propriedades a seguir para controlar a quantidade de recursos que o host de serviço aloca em nome do aplicativo:
- 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.
Os padrões seguros são escolhidos para cada uma dessas propriedades, um aplicativo deve ter cuidado se quiser modificar essas propriedades. Além das propriedades mencionadas acima, as propriedades específicas de canal, ouvinte e mensagem também podem ser modificadas pelo aplicativo. Consulte as considerações de segurança desses componentes antes de modificar qualquer uma dessas configurações.
Além disso, as seguintes considerações de design de aplicativo devem ser cuidadosamente avaliadas ao usar a API de host do serviço WWSAPI:
- Ao usar o MEX, os aplicativos devem ter cuidado para não divulgar dados confidenciais. Como mitigação, se a natureza dos dados que estão sendo expostos por meio do MEX for confidencial, os aplicativos poderão optar por configurar o ponto de extremidade MEX com uma associação segura que exige autenticação no mínimo e implementar a autorização como parte do ponto de extremidade usando o WS_SERVICE_SECURITY_CALLBACK.
- Por padrão, as informações de erro avançadas por meio de falhas são desabilitadas no host de serviço por WS_SERVICE_PROPERTY_FAULT_DISCLOSURE propriedade. Fica a critério do aplicativo enviar informações de erro avançadas como parte da falha. No entanto, isso pode resultar na divulgação de informações e, portanto, é recomendável que essa configuração seja alterada apenas para cenários de depuração.
- Além da validação executada para serialização de Perfil Básico 2.0 e XML, o host de serviço não executa nenhuma validação no conteúdo de dados recebido como parte dos parâmetros de operação de serviço. É responsabilidade do aplicativo executar todas as validações de parâmetro por conta própria.
- A autorização não é implementada como parte do host de serviço. No entanto, os aplicativos podem implementar seu próprio esquema de autorização usando WS_SECURITY_DESCRIPTION e o WS_SERVICE_SECURITY_CALLBACK.
- É responsabilidade do aplicativo usar associações seguras em seu ponto de extremidade. O host de serviço não fornece nenhuma segurança além do que está configurado no ponto de extremidade.
Os elementos de API a seguir são usados com o host de serviço.
Callback | Descrição |
---|---|
WS_SERVICE_ACCEPT_CHANNEL_CALLBACK | Invocado quando um canal é aceito em um ouvinte de ponto de extremidade pelo host de serviço. |
WS_SERVICE_CLOSE_CHANNEL_CALLBACK | Invocado quando um canal é fechado ou anulado em um ponto de extremidade. |
Enumeração | Descrição |
---|---|
WS_SERVICE_ENDPOINT_PROPERTY_ID | Parâmetros opcionais para configurar um WS_SERVICE_ENDPOINT. |
WS_SERVICE_HOST_STATE | Os estados em que um host de serviço pode estar. |
WS_SERVICE_PROPERTY_ID | Parâmetros opcionais para configurar o host de serviço. |
Função | Descrição |
---|---|
WsAbortServiceHost | Interrompe e descontinua as operações atuais no host de serviço. |
WsCloseServiceHost | Fecha todos os ouvintes para que nenhum novo canal seja aceito do cliente. |
WsCreateServiceHost | Cria um host de serviço. |
WsFreeServiceHost | Libera a memória associada a um objeto de host de serviço. |
WsGetServiceHostProperty | Recupera uma propriedade de Host de Serviço especificada. |
WsOpenServiceHost | Abre um host de serviço para comunicação e inicia os ouvintes em todos os pontos de extremidade. |
WsResetServiceHost | Redefine o host de serviço para reutilização e redefine o canal subjacente e os ouvintes para reutilização. |
Handle | Descrição |
---|---|
WS_SERVICE_HOST | Um tipo opaco usado para referenciar um host de serviço. |
Estrutura | Descrição |
---|---|
WS_SERVICE_ENDPOINT | Representa um ponto de extremidade individual em um host de serviço. |
WS_SERVICE_ENDPOINT_PROPERTY | Especifica uma configuração específica do serviço. |
WS_SERVICE_PROPERTY | Especifica uma configuração específica do serviço. |
WS_SERVICE_PROPERTY_ACCEPT_CALLBACK | Especifica o retorno de chamada que é chamado quando um canal é aceito com êxito. |
WS_SERVICE_PROPERTY_CLOSE_CALLBACK | Especifica o retorno de chamada que é chamado quando um canal está prestes a ser fechado. |