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.

Diagrama mostrando a estrutura de um host de serviço que contém um ponto de extremidade de serviço.

Criando 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:

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.

Segurança

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:

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.