Host del servizio

  • Articolo

L'host del servizio è l'ambiente di runtime per ospitare un servizio all'interno di un processo.

Un servizio può configurare uno o più endpoint all'interno di un host del servizio.

Diagramma che mostra la struttura di un host del servizio contenente un endpoint di servizio.

Creazione di un host del servizio

Prima di creare un host del servizio, un servizio deve definire i relativi endpoint. Un endpoint nell'host del servizio viene specificato nella struttura WS_SERVICE_ENDPOINT e viene definito dalle informazioni seguenti:

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.

Sono supportati solo contratti unidirezionali per SOAP su UDP, rappresentati da WS_UDP_CHANNEL_BINDING nell'enumerazione WS_CHANNEL_BINDING .

Dopo aver definito un endpoint, può essere passato alla funzione WsCreateServiceHost , che accetta una matrice di puntatori alle strutture di WS_SERVICE_ENDPOINT .

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

Un'applicazione può facoltativamente fornire una matrice di proprietà del servizio a WsCreateServiceHost per configurare impostazioni personalizzate nell'host del servizio.

Un'applicazione apre l'host del servizio per avviare l'accettazione delle richieste client.

WsOpenServiceHost(serviceHost, NULL, NULL);

Dopo aver aperto l'host del servizio, l'applicazione può chiuderla se non sono necessarie altre operazioni. Si noti che questa operazione non rilascia le risorse e che può essere riaperta con una chiamata successiva a WsResetServiceHost.

WsCloseServiceHost(serviceHost, NULL, NULL);

Dopo aver chiuso l'host del servizio, un'applicazione può reimpostare l'host del servizio per il riutilizzo.

WsResetServiceHost(serviceHost, NULL);

Quando l'applicazione viene eseguita con l'host del servizio, può liberare le risorse associate all'host del servizio chiamando la funzione WsFreeServiceHost . Si noti che WsCloseServiceHost deve essere chiamato prima di chiamare questa funzione.

WsFreeServiceHost(serviceHost, NULL);

Per informazioni sul collegamento di uno stato personalizzato all'host del servizio, vedere Stato host utente

Per informazioni sull'autorizzazione in un host del servizio per un determinato endpoint, vedere Autorizzazione del servizio.

Per informazioni sull'implementazione di operazioni di servizio e contratti di servizio per un servizio, vedere gli argomenti relativi alle operazioni del servizio e al contratto di servizio.

Sicurezza

Un'applicazione può usare le proprietà seguenti per controllare la quantità di risorse allocata dall'host del servizio per conto dell'applicazione:

Le impostazioni predefinite sicure vengono scelte per ognuna di queste proprietà, un'applicazione deve essere attenta se desidera modificare queste proprietà. Oltre alle proprietà indicate in precedenza, il canale, il listener e le proprietà specifiche dei messaggi possono essere modificate anche dall'applicazione. Fare riferimento alle considerazioni sulla sicurezza di questi componenti prima di modificare una di queste impostazioni.

Inoltre, le seguenti considerazioni sulla progettazione dell'applicazione devono essere valutate attentamente quando si usa l'API host del servizio WWSAPI:

  • Quando si usa MEX, le applicazioni devono prestare attenzione a non divulgare dati sensibili. Come mitigazione, se la natura dei dati esposti tramite MEX è sensibile, le applicazioni possono scegliere di configurare l'endpoint MEX con un'associazione sicura che richiede l'autenticazione almeno e implementare l'autorizzazione come parte dell'endpoint usando il WS_SERVICE_SECURITY_CALLBACK.
  • Per impostazione predefinita, le informazioni di errore avanzate tramite errori sono disabilitate nell'host del servizio tramite WS_SERVICE_PROPERTY_FAULT_DISCLOSURE proprietà. È in base alla discrezione dell'applicazione inviare informazioni di errore avanzate come parte dell'errore. Tuttavia, ciò può comportare la divulgazione di informazioni e pertanto è consigliabile che questa impostazione venga modificata solo per gli scenari di debug.
  • Oltre alla convalida eseguita per la serializzazione del profilo di base 2.0 e XML, l'host del servizio non esegue alcuna convalida sul contenuto dei dati ricevuti come parte dei parametri dell'operazione di servizio. È responsabilità dell'applicazione eseguire tutte le convalida dei parametri autonomamente.
  • L'autorizzazione non viene implementata come parte dell'host del servizio. Tuttavia, le applicazioni possono implementare uno schema di autorizzazione personalizzato usando WS_SECURITY_DESCRIPTION e l'WS_SERVICE_SECURITY_CALLBACK.
  • È responsabilità dell'applicazione usare associazioni sicure nel relativo endpoint. L'host del servizio non fornisce alcuna sicurezza oltre a ciò che è configurato nell'endpoint.

Gli elementi API seguenti vengono usati con l'host del servizio.

Callback Descrizione
WS_SERVICE_ACCEPT_CHANNEL_CALLBACK Richiamato quando un canale viene accettato in un listener endpoint dall'host del servizio.
WS_SERVICE_CLOSE_CHANNEL_CALLBACK Richiamato quando un canale viene chiuso o interrotto in un endpoint.

 

Enumerazione Descrizione
WS_SERVICE_ENDPOINT_PROPERTY_ID Parametri facoltativi per la configurazione di un WS_SERVICE_ENDPOINT.
WS_SERVICE_HOST_STATE Gli stati in cui è possibile inserire un host del servizio.
WS_SERVICE_PROPERTY_ID Parametri facoltativi per la configurazione dell'host del servizio.

 

Funzione Descrizione
WsAbortServiceHost Interrompe e interrompe le operazioni correnti nell'host del servizio.
WsCloseServiceHost Chiude tutti i listener in modo che non vengano accettati nuovi canali dal client.
WsCreateServiceHost Crea un host del servizio.
WsFreeServiceHost Rilascia la memoria associata a un oggetto host del servizio.
WsGetServiceHostProperty Recupera una proprietà Host del servizio specificata.
WsOpenServiceHost Apre un host del servizio per la comunicazione e avvia i listener in tutti gli endpoint.
WsResetServiceHost Reimposta l'host del servizio per il riutilizzo e reimposta il canale sottostante e i listener per il riutilizzo.

 

Handle Descrizione
WS_SERVICE_HOST Tipo opaco usato per fare riferimento a un host del servizio.

 

Struttura Descrizione
WS_SERVICE_ENDPOINT Rappresenta un singolo endpoint in un host del servizio.
WS_SERVICE_ENDPOINT_PROPERTY Specifica un'impostazione specifica del servizio.
WS_SERVICE_PROPERTY Specifica un'impostazione specifica del servizio.
WS_SERVICE_PROPERTY_ACCEPT_CALLBACK Specifica il callback chiamato quando viene accettato correttamente un canale.
WS_SERVICE_PROPERTY_CLOSE_CALLBACK Specifica il callback che viene chiamato quando un canale sta per essere chiuso.