Hôte de service

  • Article

L’hôte de service est l’environnement d’exécution pour héberger un service dans un processus.

Un service peut configurer un ou plusieurs points de terminaison à l’intérieur d’un hôte de service.

Diagramme montrant la structure d’un hôte de service contenant un point de terminaison de service.

Création d’un hôte de service

Avant de créer un hôte de service, un service doit définir ses points de terminaison. Un point de terminaison dans l’hôte de service est spécifié dans la structure WS_SERVICE_ENDPOINT et il est défini par les informations suivantes :

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.

Seuls les contrats unidirectionnels sont pris en charge pour SOAP sur UDP, représentés par WS_UDP_CHANNEL_BINDING dans l’énumération WS_CHANNEL_BINDING .

Une fois qu’un point de terminaison est défini, il peut être passé à la fonction WsCreateServiceHost , qui accepte un tableau de pointeurs vers WS_SERVICE_ENDPOINT structures.

HRESULT hr = WsCreateServiceHost (serviceEndpoints, 1, NULL, 0, &host, error);

Une application peut éventuellement fournir un tableau de propriétés de service à WsCreateServiceHost pour configurer des paramètres personnalisés sur l’hôte de service.

Une application ouvre l’hôte de service pour commencer à accepter les demandes des clients.

WsOpenServiceHost(serviceHost, NULL, NULL);

Après avoir ouvert l’hôte de service, l’application peut le fermer s’il n’y a plus d’opérations qui le nécessitent. Notez que cela ne libère pas ses ressources et qu’il peut être rouvert avec un appel ultérieur à WsResetServiceHost.

WsCloseServiceHost(serviceHost, NULL, NULL);

Après avoir fermé l’hôte de service, une application peut réinitialiser l’hôte de service pour le réutiliser.

WsResetServiceHost(serviceHost, NULL);

Lorsque l’application a terminé avec l’hôte de service, elle peut libérer les ressources associées à l’hôte de service en appelant la fonction WsFreeServiceHost . Notez que WsCloseServiceHost doit être appelé avant d’appeler cette fonction.

WsFreeServiceHost(serviceHost, NULL);

Pour plus d’informations sur l’attachement d’un état personnalisé à l’hôte de service, consultez État de l’hôte utilisateur

Pour plus d’informations sur l’autorisation dans un hôte de service pour un point de terminaison donné, consultez Autorisation de service.

Pour plus d’informations sur l’implémentation des opérations de service et des contrats de service pour un service, consultez les rubriques opérations de service et contrat de service.

Sécurité

Une application peut utiliser les propriétés followin pour contrôler la quantité de ressources allouées par l’hôte de service pour le compte de l’application :

Les valeurs par défaut sécurisées sont choisies pour chacune de ces propriétés. Une application doit être prudente si elle souhaite modifier ces propriétés. Au-delà des propriétés mentionnées ci-dessus, les propriétés spécifiques au canal, à l’écouteur et au message peuvent également être modifiées par l’application. Reportez-vous aux considérations relatives à la sécurité de ces composants avant de modifier l’un de ces paramètres.

En outre, les considérations suivantes en matière de conception d’application doivent être soigneusement évaluées lors de l’utilisation de l’API hôte du service WWSAPI :

  • Lors de l’utilisation de MEX, les applications doivent veiller à ne pas divulguer de données sensibles. En guise d’atténuation, si la nature des données exposées via MEX est sensible, les applications peuvent choisir de configurer le point de terminaison MEX avec une liaison sécurisée nécessitant une authentification au minimum et d’implémenter l’autorisation dans le cadre du point de terminaison à l’aide de la WS_SERVICE_SECURITY_CALLBACK.
  • Par défaut, les informations d’erreur enrichies via les erreurs sont désactivées sur l’hôte de service par WS_SERVICE_PROPERTY_FAULT_DISCLOSURE propriété. Il est à la discrétion de l’application d’envoyer des informations d’erreur enrichies dans le cadre de l’erreur. Toutefois, cela peut entraîner la divulgation d’informations et, par conséquent, il est recommandé de modifier ce paramètre uniquement pour les scénarios de débogage.
  • Au-delà de la validation effectuée pour la sérialisation BASIC Profile 2.0 et XML, l’hôte de service n’effectue aucune validation sur le contenu de données reçu dans le cadre des paramètres d’opération de service. Il incombe à l’application d’effectuer toutes les validations de paramètres par elle-même.
  • L’autorisation n’est pas implémentée dans le cadre de l’hôte de service. Toutefois, les applications peuvent implémenter leur propre schéma d’autorisation à l’aide de WS_SECURITY_DESCRIPTION et du WS_SERVICE_SECURITY_CALLBACK.
  • Il incombe à l’application d’utiliser des liaisons sécurisées sur son point de terminaison. L’hôte de service ne fournit aucune sécurité au-delà de ce qui est configuré sur le point de terminaison.

Les éléments d’API suivants sont utilisés avec l’hôte de service.

Rappel Description
WS_SERVICE_ACCEPT_CHANNEL_CALLBACK Appelé lorsqu’un canal est accepté sur un écouteur de point de terminaison par l’hôte de service.
WS_SERVICE_CLOSE_CHANNEL_CALLBACK Appelé lorsqu’un canal est fermé ou abandonné sur un point de terminaison.

 

Énumération Description
WS_SERVICE_ENDPOINT_PROPERTY_ID Paramètres facultatifs pour la configuration d’un WS_SERVICE_ENDPOINT.
WS_SERVICE_HOST_STATE États où un hôte de service peut se trouver.
WS_SERVICE_PROPERTY_ID Paramètres facultatifs pour la configuration de l’hôte de service.

 

Fonction Description
WsAbortServiceHost Interrompt et interrompt les opérations en cours sur l’hôte de service.
WsCloseServiceHost Ferme tous les écouteurs afin qu’aucun nouveau canal ne soit accepté par le client.
WsCreateServiceHost Crée un hôte de service.
WsFreeServiceHost Libère la mémoire associée à un objet hôte de service.
WsGetServiceHostProperty Récupère une propriété hôte de service spécifiée.
WsOpenServiceHost Ouvre un hôte de service pour la communication et démarre les écouteurs sur tous les points de terminaison.
WsResetServiceHost Réinitialise l’hôte de service pour réutilisation et réinitialise le canal sous-jacent et les écouteurs à réutiliser.

 

Handle Description
WS_SERVICE_HOST Type opaque utilisé pour référencer un hôte de service.

 

Structure Description
WS_SERVICE_ENDPOINT Représente un point de terminaison individuel sur un hôte de service.
WS_SERVICE_ENDPOINT_PROPERTY Spécifie un paramètre spécifique au service.
WS_SERVICE_PROPERTY Spécifie un paramètre spécifique au service.
WS_SERVICE_PROPERTY_ACCEPT_CALLBACK Spécifie le rappel appelé lorsqu’un canal est accepté avec succès.
WS_SERVICE_PROPERTY_CLOSE_CALLBACK Spécifie le rappel appelé lorsqu’un canal est sur le point d’être fermé.