服務主機

  • 發行項

服務主機是用於在進程內裝載服務的執行時間環境。

服務可以在服務主機內設定一或多個端點。

此圖顯示包含服務端點的服務主機結構。

建立服務主機

建立服務主機之前，服務必須定義其端點。 服務主機中的端點是在 WS_SERVICE_ENDPOINT 結構中指定，並由下列資訊定義：

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.

WS_CHANNEL_BINDING列舉中WS_UDP_CHANNEL_BINDING表示的 SOAP over UDP 僅支援單向合約。

定義端點之後，即可將它傳遞至 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);

如需將自訂狀態附加至服務主機的資訊，請參閱 使用者主機狀態

如需指定端點之服務主機中授權的資訊，請參閱 服務授權。

如需實作服務服務作業和服務合約的 iinformation，請參閱 服務作業 和服務 合約主題。

安全性

應用程式可以使用下列屬性來控制服務主機代表應用程式佈建的資源數量：

系統會為每個屬性選擇安全預設值，如果應用程式想要修改這些屬性，則必須小心。 除了上述屬性之外，通道、接聽程式和訊息特定屬性也可以由應用程式修改。 在修改這些設定之前，請參閱這些元件的安全性考慮。

此外，使用 WWSAPI 服務主機 API 時，應該仔細評估下列應用程式設計考慮：

  • 使用 MEX 時，應用程式應該小心不要揭露任何敏感性資料。 作為緩和措施，如果透過 MEX 公開的資料本質很敏感，應用程式可以選擇使用至少需要驗證的安全系結來設定 MEX 端點，並使用 WS_SERVICE_SECURITY_CALLBACK作為端點的一部分實作授權。
  • 根據預設，透過錯誤的豐富錯誤資訊會停用服務主機上 的 WS_SERVICE_PROPERTY_FAULT_DISCLOSURE 屬性。 應用程式會自行決定將豐富的錯誤資訊傳送為錯誤的一部分。 不過，這可能會導致資訊洩漏，因此建議只針對偵錯案例變更此設定。
  • 除了針對基本設定檔 2.0 和 XML 序列化所執行的驗證之外，服務主機不會對服務作業參數所接收的資料內容執行驗證。 應用程式必須自行執行所有參數驗證。
  • 授權未實作為服務主機的一部分。 不過，應用程式可以使用 WS_SECURITY_DESCRIPTION 和 WS_SERVICE_SECURITY_CALLBACK來實作自己的授權配置。
  • 應用程式必須負責在其端點上使用安全系結。 服務主機不會提供端點上所設定以外的任何安全性。

下列 API 元素會與服務主機搭配使用。

回呼 Description
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 Description
WS_SERVICE_HOST 用來參考服務主機的不透明類型。

 

結構 Description
WS_SERVICE_ENDPOINT 表示服務主機上的個別端點。
WS_SERVICE_ENDPOINT_PROPERTY 指定服務特定的設定。
WS_SERVICE_PROPERTY 指定服務特定的設定。
WS_SERVICE_PROPERTY_ACCEPT_CALLBACK 指定成功接受通道時所呼叫的回呼。
WS_SERVICE_PROPERTY_CLOSE_CALLBACK 指定當通道即將關閉時所呼叫的回呼。