SOE開發概覽

孫群發表於2013-01-02
關於SOE
一個SOE就是一個元件物件模型（COM），其由.Net或Java實現了IServerObjectExtension 介面和一些其他必須實現的介面。服務例項（也可稱作“伺服器物件”）建立了SOE並呼叫了Init方法，通過server object helper引數可以將SOE作為一個伺服器物件引用來處理。SOE可以在伺服器物件上呼叫方法。
所有SOE使用的介面（IServerObjectExtension和IObjectConstruct）

必需的IServerObjectExtension介面包括如下的方法。這個介面被伺服器物件用來管理SOE的生命週期。


Init—當伺服器物件啟動的時候呼叫
Shutdown—通知SOE伺服器物件將要關閉。作為相應，SOE釋放它對server object helper的引用。
如果你的SOE包括配置屬性或者需要初始胡邏輯，那麼就需要實現可選的介面IObjectConstruct。這個介面僅包含一個方法Construct，該方法在IServerObjectExtension.Init之後呼叫。Construct將以屬性集的形式返回SOE的配置屬性。

不要把初始化的邏輯放在SOE類的建構函式或Init函式中，應該將其放到IObjectConstruct.Construct()方法中，該方法在SOE的生命週期中稍後呼叫。這確保了你已經完全建立了SOE，並可以用你的初始化邏輯記錄任何的錯誤。


SOE Web服務介面（IRESTRequestHandler和IRequestHandler2）
因為SOE是Web服務，它使用請求處理介面(request handler interface)來完成工作，使用ESRI.ArcGIS.SOESupport.ServerLogger物件進行日誌記錄。
基於REST的SOE Web服務實現了IRESTRequestHandler介面。
基於SOAP的SOE Web服務實現了IRequestHandler2介面。
有可能建立一個同時實現了IRESTRequestHanler和IRequestHandler2介面的SOE以便能同時支援REST和SOAP兩種方式。

當使用SOE的時候，客戶端對Web服務傳送HTTP請求，該Web服務會返回響應結果。請求處理介面（request handler interface）有助於完成這個通訊過程。


將SOE作為Web服務進行開發
當你開發一個SOE的時候，其實你就是在開發一個能夠接收請求並能返回結果的Web服務。SOE被ArcGIS Server暴露成Web服務，這種方式與其他原生服務（比如map或geocode服務）被暴露的方式是相同的。SOE在GIS伺服器中有效執行，通過呼叫ArcObjects以實現必要的地理空間分析功能。SOE可以影響ArcGIS Server的管理和安全框架，比如通過使用ArcGIS Server 令牌（token）服務模型來確保獲取SOE Web服務的安全性。

你可以用C#或Java開發SOE，其可以支援REST或SOAP或二者均支援。本節餘下的內容描述瞭如何用.Net構建REST和SOAP的Web服務。


REST和SOAP SOE模板
在Visual Studio中，ArcGIS提供了REST和SOAP模板。這些模板為你提供了建立SOE所必需的程式碼。你用這些模板建立SOE，然後修改已經存在的程式碼，並加入SOE必須得邏輯。
REST SOE模板應用程式是由一個類組成的，該類實現了REST SOE所必需的所有的介面，包括IServerObjectExtension、IObjectConstruct以及IRESTRequestHandler。更多REST SOE類的實現請參見 Developing REST server object extensions.

SOAP SOE模板應用程式是由一個類組成的，該類實現了SOAP SOE所必需的所有的介面，包括IServerObjectExtension、IObjectConstruct以及IRequestHandler2。在這個結構中另外一個元件就是一個模板Web服務描述語言（WSDL）檔案，你可以通過它將Esri的SOAP型別整合進你自己的SOAP實現。更多SOAP SOE類的實現請參見Developing SOAP server object extensions。


一個SOE Web服務基本的實現
ArcGIS Server服務代表了託管在GIS伺服器容器程式中的“伺服器物件”（server objects）。伺服器物件包含了與其相關聯的預先打包的功能；因此，地圖伺服器物件（map server objects）託管了地圖資料、產生地圖圖片、處理查詢；地理編碼伺服器物件（geocode server objects）託管了一個能夠將位置轉換為地址的定位器，諸如此類。
在自定義的工作流中，通過使用已經存在的伺服器物件（server objects）擴充套件了這種功能。SOEs中一個或多個公共的方法（public method）提供了訪問該工作流的許可權。
客戶端知道如何通過標準的協議使用SOE，比如用WSDL使用SOAP服務，用JSON使用REST服務。客戶端通過HTTP協議對ArcGIS Server Web服務例項傳送請求。這個Web服務例項包含了SOAP和REST請求處理函式以便將這個請求轉接到託管在伺服器物件（server object）中的SOE上，伺服器物件是放在GIS伺服器上的。然後SOE對請求進行反序列化，執行業務邏輯（通常要獲取伺服器物件）並對返回結果進行序列化。返回結果通過同一個HTTP通道進行傳送到客戶端，並進行反序列化。
ArcGIS for Server是建立在ArcObjects COM架構上的。基於.Net的SOE類必須可以讓ArcGIS Server通過COM可見和訪問。這是通過ComVisible和GUID這兩個attributes來實現的。ClassInterfaceType.None這個attribute告知型別類庫產生工具一個預設的類介面不需要被建立。SOE模板也告訴你如何使用其他的attributes定義能力（capabilities）、屬性、描述以及支援的Web服務的架構（SOAP和REST）。

下面的示例程式碼顯示了一個簡單SOE的宣告：

[C#]

[ComVisible(true)][Guid("b210df6d-83af-4e02-bf34-db72387a8257")][ClassInterface
    (ClassInterfaceType.None)][ServerObjectExtension("MapServer", AllCapabilities = 
    "", DefaultCapabilities = "", Description = "A simple REST SOE", DisplayName = 
    "RestSOE", Properties = "", SupportsREST = true, SupportsSOAP = false)]
public class RestSOE: IServerObjectExtension, IObjectConstruct, IRESTRequestHandler
{

    . . . 

}

[VB.NET]

<ComVisible(True), Guid("2ea26d5b-d1de-4d9e-a1ca-25e3a3cd3d4e"), ClassInterface(ClassInterfaceType.None)> _
            <ServerObjectExtension("MapServer", AllCapabilities
    = "", DefaultCapabilities
    = "", _
      Description
    = "A simple REST SOE", DisplayName
    = "RestSOE", _
      Properties
    = "", SupportsREST
    = True, SupportsSOAP
    = False)>

    Public Class RestSOE
        
        . . .
        
    End Class

SOE 能力（capabilities）
SOE方法可以按照“能力”（capabilities）進行分組。每個capabilities通過一個對應的配置原則進行授權。對SOE的每個呼叫都包括了capabilities配置資訊以及被呼叫的操作方法。SOE應該檢查capabilities以便於判斷某個方法是否該執行。比如，假設一個SOE有三個方法：M1、M2、M3和兩個capabilities：C1（包含方法M1，M2）和C2（包含M1，M2，M3）。當在一個伺服器物件上啟用了SOE之後，配置資訊僅僅啟用了C1的capabilities。這樣，就不能呼叫SOE上的M3方法。
將方法按照capabilities進行分組不是必須的。


ESRI.ArcGIS.SOESupport 庫
ArcGIS for Server包括了一個.Net庫ESRI.ArcGIS.SOESupport，以便開發者在SOE的開發過程中定義SOAP和REST內容。這個庫包含了固定的程式碼，這些程式碼用於對訊息進行序列化與反序列化、對業務邏輯程式碼的呼叫、錯誤處理以及日誌記錄。總之，模板程式碼從實現類（對於REST是SoeRestImpl類，對於SOAP是SoeSoapImpl類）開始，該類用於組織管理SOE的功能，以及對SOE中的方法進行呼叫。這個庫的使用的討論可分別參見SOAP和REST章節。


日誌記錄
你可以在SOE中通過SOESupport.ServerLogger類將資訊寫入到ArcGIS Server日誌中。在你的SOE建構函式中，你可以建立這個日誌管理器。示例程式碼如下所示：
[C#]

logger = new ServerLogger();

[VB.NET]

logger = New ServerLogger()

你可以用SOE寫入各種等級的資訊。如下所示，8000是一個開發者用SOE自定義的日誌碼。

[C#]

logger.LogMessage(ServerLogger.msgType.infoStandard, "Shutdown", 8000, 
    "Custom message: Shutting down the SOE");

[VB.NET]

logger.LogMessage(ServerLogger.msgType.infoStandard, "Shutdown", 8000, "Custom message: Shutting down the SOE")

訊息的等級可以通過ServerLogger.msgType獲取，其與ArcGIS Server日誌資訊的等級對應如下：

ServerLogger.msgType ArcGIS Server log level
error Severe
warning Warning
infoSimple Info
infoStandard Fine
infoDetailed Verbose
debug Debug

支援REST和SOAP介面
如果你想將你的SOE功能通過SOAP和REST的方式暴露出來，你有如下兩個選擇：
a. 分別用SOAP和REST的模板建立SOEs。儘管這種方式更直接，但是這需要你將兩個SOE設定為不同的名字。
b. 在同一個SOE中實現IRestHandler2和IRESTRequestHandler介面。實現這種方法的一個辦法是使用SOAP模板，然後把REST模板中IRESTRequestHandler的實現程式碼拷貝到SOAP模板中，為了減少程式碼冗餘，應該將你的業務邏輯程式碼封裝到一個單獨的類中，然後通過REST和SOAP的請求處理函式對其進行呼叫。


執行緒
SOE應該能在SOE的主執行緒中建立和獲取ArcObjects。不與ArcObjects進行互動的第三方庫應該執行在其他的執行緒上。只有當他們在同一個執行緒中建立和銷燬的時候，才能在新衍生的執行緒中使用ArcObjects。


相關文章