Local (DCOM) connections are only supported for ArcGIS Server versions prior to 10.1.
About server objects
A server object is a coarse-grained ArcObjects component that runs in a process on the server object container (SOC) machine. ArcGIS for Server comes with the following server objects:
- esriCarto.MapServer—Provides access to the contents of a map document and methods for querying and drawing the map.
- esriLocation.GeocodeServer—Provides access to an address locator and methods for performing single address and batch geocoding.
- esriGeodatabaseDistributed.GeodataServer—Provides access to a geodatabase and methods for performing data management, such as check out and synchronizing replicas.
- esriGlobeCore.GlobeServer—Provides access to a globe document and methods for displaying the globe.
- esriGeoProcessing.GPServer—Provides access to tools and models within a geoprocessing toolbox.
- esriCarto.ImageServer—Processes access to raster data and ArcGIS Image Server instances.
-
esriGeodatabase.GeometryServer—Provides access to geometric operations.
These coarse-grained objects use the finer-grained ArcObjects on the server to perform their operations. Applications can use the high-level coarse-grained methods on the server object and can also drill down and work with the fine-grained ArcObjects associated with them (for example, feature layers, feature classes, renderers, and so on).
A server object, unlike other ArcObjects components, can be preconfigured by a geographic information system (GIS) server administrator. To preconfigure a server object, the GIS server administrator must set the object's properties using ArcCatalog before client applications can connect and use functionality. When a server object is preconfigured, the administrator must specify a number of configuration properties, including the server object's pooling model. The pooling model dictates the type of usage that an application makes of the server object. This aspect of server object usage is discussed in more detail later when the concept of stateful versus stateless use of the server is discussed.
The MapServer and GeocodeServer objects are shown in the following illustrations:
Obtaining server objects from the server
You get a server object by asking the server for a server context containing the object. Think of a server context as a process, managed by the server, within which a server object runs. Your application keeps a server object alive by holding on to its context. The application releases the server object by releasing its context when it is finished with it. The following code example shows how to obtain a GeocodeServer object from the GIS server and use it to locate an address:
[C#]
IServerContext pServerContext = pSOM.CreateServerContext("RedlandsGeocode",
"GeocodeServer");
IGeocodeServer pGCServer = pServerContext.ServerObject as IGeocodeServer;
IPropertySet pPropertySet = pServerContext.CreateObject("esriSystem.PropertySet")as
IPropertySet;
pPropertySet.SetProperty("Street", "380 New York St");
IPropertySet pResults = pGCServer.GeocodeAddress(pPropertySet, null);
IPoint pPoint = pResults.GetProperty("Shape")as IPoint;
Console.WriteLine(pPoint.X + ", " + pPoint.Y);
pServerContext.ReleaseContext();
[VB.NET]
Dim pServerContext As IServerContext = pSOM.CreateServerContext("RedlandsGeocode", "GeocodeServer")
Dim pGCServer As IGeocodeServer = pServerContext.ServerObject
Dim pPropertySet As IPropertySet = pServerContext.CreateObject("esriSystem.PropertySet")
pPropertySet.SetProperty ("Street", "380 New York St")
Dim pResults As IPropertySet = pGCServer.GeocodeAddress(pPropertySet, Nothing)
Dim pPoint As IPoint = pResults.GetProperty("Shape")
Debug.WriteLine (pPoint.X & ", " & pPoint.Y)
pServerContext.ReleaseContext()
A server object has other associated objects that you can access and use. For example, if you are working with a MapServer object, you can get to the Map and Layer objects associated with that map. These are the same Map and Layer objects that an ArcGIS for Desktop or ArcGIS Engine developer works with, except they reside in the server.
The following code example shows how to use the finer-grained ArcObjects associated with a MapServer object to work with a feature class associated with a particular layer:
[C#]
IServerContext pServerContext = pSOM.CreateServerContext("RedlandsMap", "MapServer");
IMapServer pMapServer = pServerContext.ServerObject as IMapServer;
IMapServerObjects pMapServerObjs = pMapServer as IMapServerObjects;
IMap pMap = pMapServerObjs.get_Map(pMapServer.DefaultMapName);
IFeatureLayer pFLayer = pMap.get_Layer(0)as IFeatureLayer;
IFeatureClass pFeatureClass = pFLayer.FeatureClass;
Console.WriteLine(pFeatureClass.FeatureCount(null).ToString());
pServerContext.ReleaseContext();
[VB.NET]
Dim pServerContext As IServerContext = pSOM.CreateServerContext("RedlandsMap", "MapServer")
Dim pMapServer As IMapServer = pServerContext.ServerObject
Dim pMapServerObjs As IMapServerObjects = pMapServer
Dim pMap As IMap = pMapServerObjs.Map(pMapServer.DefaultMapName)
Dim pFLayer As IFeatureLayer = pMap.Layer(0)
Dim pFeatureClass As IFeatureClass = pFLayer.FeatureClass
Debug.WriteLine (pFeatureClass.FeatureCount(Nothing))
pServerContext.ReleaseContext()
In the previous code examples, pSOM is an IServerObjectManager interface that was retrieved from IGISServerConnection.ServerObjectManager. When the server object's work is done and the application is finished using objects associated with the server object (in the first case, pPoint, in the second case, pFeatureClass), the server context (pServerContext) was explicitly released.
The server context is released so other application sessions and other applications can use that server object. If your code does not explicitly release the context, it will be released once it goes out of scope and garbage collection occurs. However, there might be considerable time between when the server context variable goes out of scope and when garbage collection occurs. If you rely on this mechanism, your server is controlled by .NET garbage collection in terms of when objects are released.
Garbage collection is the process by which .NET reclaims memory from objects that are created by applications. Garbage collection occurs based on memory allocations being made. When garbage collection occurs, objects that are not referenced are cleaned up, which can be some time after they go out of the scope of your application.
Obtaining a server object extension
Once you have a server object, you can get any extensions it supports and make method calls on them. A server object supports the IServerObjectExtensionManager interface, which has methods for getting all the extensions supported by the server object. These extensions can be out-of-the-box extensions installed with ArcGIS for Server, or they can be custom extensions created by developers and registered with the GIS server.
The following code example shows how to get the network analysis extension to a MapServer and print the network analysis layers in the map:
[C#]
IServerObjectManager pSOM;
IServerContext pServerContext = pSOM.CreateServerContext("RedlandsMap", "MapServer");
IMapServer pMapServer = pServerContext.ServerObject as IMapServer;
IServerObjectExtensionManager pSOExtManager = pMapServer as
IServerObjectExtensionManager;
IServerObjectExtension pSOExt = pSOExtManager.FindExtensionByName("NAServer");
INAServer naserver = pSOExt as INAServer;
// Do some network analysis.
pServerContext.ReleaseContext();
[VB.NET]
Dim pServerContext As IServerContext = pSOM.CreateServerContext("RedlandsMap", "MapServer")
Dim pMapServer As IMapServer = pServerContext.ServerObject
Dim pSOExtManager As IServerObjectExtensionManager = pMapServer
Dim pSOExt As IServerObjectExtension = pSOExtManager.FindExtensionByName("NetworkAnalystServerExt")
Dim pNAServer As INAServer = pSOExt
' Do some network analysis.
pServerContext.ReleaseContext()
For more information on writing your own server object extensions, see Server object extensions (SOE).
Managing a server object's lifetime
A key aspect of using a server object is managing the server object’s lifetime. Server objects reside in server contexts, and you obtain a server object by calling CreateServerContext containing a specified server object (see the previous code examples).
The server object—for example, RedlandsGeocode, RedlandsMap—and all its associated objects are alive and can be used as long as you hold on to the context. Once you release the server context (by calling ReleaseContext or allowing the context to go out of scope), you can no longer use the server object or any other objects you obtained from the context. Once a server object’s context is released, what happens to the context depends on whether the server object is pooled or non-pooled.
The following illustration shows the server object lifetime of a pooled server object in these steps:
- The client application makes a connection to the server object manager (SOM) and requests a server object.
- The SOM returns to the client a proxy to one of the server objects available in the pool.
- The client application works with the server object by making calls on its proxy.
- When the client is finished with the server object, it releases it. When the object is released, it is returned to the pool and is available to handle requests from other clients.
In the case of a non-pooled object, when the context is released, it is shut down by the server. The next call to CreateServerContext for that server object creates an instance of the server object in a new server context. If the server object is pooled, ReleaseContext returns the server object and its context to the pool, and the server is free to give the server object to a request from another application session. This aspect of server object and server context behavior is critical when designing your application and how it manages state.
The following illustration shows the server object lifetime of a non-pooled server object in these steps:
- The client application makes a connection to the SOM and requests a server object.
- The SOM creates an instance of the server object and returns to the client a proxy to the server object.
- The client application works with the server object by making calls on its proxy.
- When the client is finished with the server object, it releases it. When the object is released, it is destroyed. The SOM creates an instances of the server object to handle subsequent requests.