服務 Proxy

服務 Proxy 是服務的用戶端 Proxy。 服務 Proxy 可讓應用程式透過 通道 做為方法呼叫，透過 傳送和接收 訊息。

服務 Proxy 會視需要建立、開啟、用來呼叫服務，並在不再需要時關閉。 或者，應用程式可能會重複使用服務 Proxy 重複連線到相同的服務，而不需要花費一次以上的時間和資源來初始化服務 Proxy。 下圖說明服務 Proxy 可能狀態的流程，以及函式呼叫或從某個狀態導向到另一個狀態的事件。

這些服務 Proxy 狀態會在 WS_SERVICE_PROXY_STATE 列舉中列舉。

如上圖和下列程式代碼所示，服務 Proxy 是由呼叫 WsCreateServiceProxy 函式所建立。 作為此呼叫的參數，WWSAPI 提供下列列舉：

• WS_CHANNEL_TYPE
• WS_CHANNEL_BINDING

它也接受使用下列資料類型的選擇性參數：

• WS_PROXY_PROPERTY_ID
• WS_SECURITY_DESCRIPTION

建立服務 Proxy 之後，WsCreateServiceProxy 函式會透過 out 參數傳回服務 Proxy WS_SERVICE_PROXY的參考。

WS_SERVICE_PROXY* serviceProxy = NULL;
hr = WsCreateServiceProxy (
    WS_TCP_CHANNEL_BINDING, 
    WS_CHANNEL_TYPE_DUPLEX_SESSION, 
    NULL, 
    NULL, 
    0, 
    NULL,
    0,
    &serviceProxy, 
    error);

建立服務 Proxy 之後，應用程式可以呼叫 WsOpenServiceProxy函式，傳遞包含服務端點網路位址的 結構，以開啟服務 Proxy 以與服務通訊。

WS_ENDPOINT_ADDRESS address = {0};
address.uri.chars = "net.tcp://localhost/example";
address.uri.length = wcslen("net.tcp://localhost/example";);
hr = WsOpenServiceProxy(serviceProxy, &address, NULL, error);

開啟服務 Proxy 時，應用程式可以使用它來呼叫服務。

hr = Add(
    serviceProxy, 
    1, 
    2, 
    &result, 
    NULL, 
    0, 
    NULL, 
    error);

當應用程式不再需要服務 Proxy 時，它會呼叫 WsCloseServiceProxy 函式來關閉服務 Proxy。 它也會呼叫 WsFreeServiceProxy來釋放相關聯的記憶體。

hr = WsCloseServiceProxy(
    serviceProxy, 
    NULL, 
    error);

hr = WsFreeServiceProxy(
    serviceProxy, 
    error);

重複使用服務 Proxy

或者，呼叫 WsCloseServiceProxy 之後， 應用程式可以藉由呼叫 WsResetServiceProxy 函式來重複使用服務 Proxy。

hr = WsResetServiceProxy(
    serviceProxy, 
    error);

如需如何在不同內容中使用服務 Proxy 的詳細資訊，請參閱下列主題：

• 服務 Proxy 和會話
• 服務作業
• 客戶端服務作業
• HttpCalculatorClientExample

安全

當您使用 WWSAPI 服務 Proxy API 時，應仔細注意下列應用程式設計考慮：

• 服務 Proxy 不會執行基本配置檔 2.0 驗證和 XML 串行化以外的任何數據驗證。 應用程式有責任在呼叫中驗證其接收回的參數中包含的數據。
• 使用 WS_PROXY_PROPERTY_ID 列舉 WS_PROXY_PROPERTY_MAX_PENDING_CALLS值來設定服務 Proxy 上擱置的呼叫數目上限，可保護執行緩慢的伺服器。 預設最大值為 100。 修改預設值時，應用程式必須小心。
• 服務 Proxy 不提供與伺服器通訊之 WS_SECURITY_DESCRIPTION 結構中指定的安全性保證。
• 在服務 Proxy 上修改 訊息 和 通道 預設值時，請小心。 在您修改任何相關屬性之前，請先閱讀與訊息和通道相關聯的安全性考慮。
• 服務 Proxy 會加密它保留在記憶體中的所有認證。

下列 API 元素與服務 Proxy 相關。