Server

Supported with:
Library dependencies: System, SystemUI, Geometry, Display

Additional library information: Contents, Object Model Diagram

The Server library contains objects that allow you to connect to and work with ArcGIS servers. You gain access to an ArcGIS server using the GISServerConnection object. The GISServerConnection object gives access to the ServerObjectManager. Using this object, you can work with ServerContext objects to manipulate ArcObjects running on the server.
 
The Server library is not extended by developers. Developers can also use the GISClient library when interacting with ArcGIS server.

The objects that implement this functionality are grouped into a number of library subsystems. These library subsystems are:

Server Connection Objects
To have your application use the geographic information system (GIS) server to host ArcObjects, you must connect the application to the GIS server—that is, connect to the server object manager (SOM). Connections to the GIS server are made through the GISServerConnection object. The GISServerConnection object supports a single interface (in addition to IUnknown): IGISServerConnection. IGISServerConnection has a Connect method that connects the application to the GIS server. You call the Connect method and provide the name or Internet protocol (IP) address of the machine on which the server object manager is running.
 
Once connected to the GIS server, IGISServerConnection has properties that hand out references to ServerObjectManager and ServerObjectAdmin for making use of server objects and administering server objects, respectively.
 
To successfully connect to the GIS server using GISServerConnection, the user account running the application must be a member of the agsusers group on the GIS server. If the account running the application is not a member of this group, the Connect method on IGISServerConnection will return an error. If the user account running the application is a member of the agsadmin user group on the GIS server, the ServerObjectAdmin property on IGISServerConnection can be used to get a reference on ServerObjectAdmin. If the user account running the application is not in the agsadmin user group, the ServerObjectAdmin property will return an error. The following illustration shows this connection.
 
 
The following code is an example of how to use GISServerConnection to connect to a GIS server running on a machine called melange and print out the names and types of the server object configurations on the server.

[VB.NET] 
Dim pGISServerConnection As IGISServerConnection = New GISServerConnection()
pGISServerConnection.Connect("melange")

Dim pServerObjectManager As IServerObjectManager = pGISServerConnection.ServerObjectManager
Dim pEnumConfigInfo As IEnumServerObjectConfigurationInfo = pServerObjectManager.GetConfigurationInfos

Dim pConfigInfo As IServerObjectConfigurationInfo = pEnumConfigInfo.Next
Do Until pConfigInfo Is Nothing
  Debug.Print (pConfigInfo.Name & ": " & pConfigInfo.TypeName)
  Set pConfigInfo = pEnumConfigInfo.Next()
Loop

Server Consumer Objects
When developing applications that connect to a GIS server, you need to be able to access objects running in the server and create objects in the server for your application’s use. If the user your application runs as is a member of the agsusers user group on the GIS server, then that application will be able to connect to the GIS server using the GISServerConnection object and can get a reference to the set of objects that provide the application the ability to make use of ArcObjects running in the server.
 
The Server Consumer Objects object model diagram is shown here:
 
 
 
ServerObjectManager
The ServerObjectManager class provides access to information about the GIS server to nonadministrators and creates ServerContexts for use by applications. Any application that runs as a user account in the agsusers user group on the GIS server can use the IGISServerConnection interface to connect to the GIS server and to get a reference to the ServerObjectManager.
 
Use the IServerObjectManager interface to create and use server objects when your application connects to the GIS server. The IServerObjectManager interface has the necessary methods for an application to get the collection of server object configurations, server object types, and server directories configured in the server as ServerObjectConfigurationInfo, ServerObjectTypeInfo, and ServerDirectoryInfo objects, respectively.
 
IServerObjectManager2 extends IServerObjectManager with a method to get the collection of server object extension types registered with the GIS server for a particular server object type, such as ServerObjectExtensionTypeInfo objects and the SystemInfo property. The SystemInfo property returns a PropertySet containing properties indicating the operating system name and message version of the GIS server.
 
The following C# code shows how you can connect to a GIS server and get its system info.

[C#] 
IGISServerConnection connection = new GISServerConnectionClass();
connection.Connect("server_name");

IServerObjectManager2 som = connection.ServerObjectManager as IServerObjectManager2;
IPropertySet props = som.SystemInfo;

object objkeys;
object objvalues;
string[] keys;
object[] vals;
props.GetAllProperties(out objkeys, out objvalues);
keys = (string[])objkeys;
vals = (object[])objvalues;

for (int i = 0; i < props.Count; i++)
{
    Console.WriteLine(keys[i] + ": " + vals[i]);
}
The CreateServerContext method on IServerObjectManager is used to get a reference to a context on the server. A context is a process managed by the server within which a server object runs. You can use CreateServerContext to create a context based on a server object configuration, or you can create empty contexts solely for the purpose of creating ArcObjects on the fly within the server.
 
When using CreateServerContext to create a context based on a server object configuration, if the server object configuration is pooled, you may get a reference to a context that already exists and is running in the server. When you have completed that context, it is important to release it explicitly by calling the ReleaseContext method on IServerContext to return it to the pool. When using CreateServerContext to create a context based on a non-pooled server object configuration, or when creating an empty context, a new context is created on the server. You still need to call ReleaseContext when you are finished using it, and the context is destroyed on the server.
 
The following code is an example of how to connect to the GIS server called melange, create a server context based on the RedlandsMap server object configuration, get a reference to the RedlandsMap MapServer object running in the context, and print its DefaultMapName property. Note the call to ReleaseContext when the use of the context is complete.

[VB.NET] 
Dim pGISServerConnection As IGISServerConnection = New GISServerConnection()
pGISServerConnection.Connect("melange")

Dim pServerObjectManager As IServerObjectManager = pGISServerConnection.ServerObjectManager
Dim pServerContext As IServerContext = pServerObjectManager.CreateServerContext("RedlandsMap", "MapServer")

Dim pServerObject As IServerObject = pServerContext.ServerObject
Dim pMapServer As IMapServer = pServerObject

Debug.Print pMapServer.DefaultMapName

pServerContext.ReleaseContext()
The following code is an example of how to create an empty server context and, within that context, create a new polygon and print its area. Note the call to ReleaseContext when the use of the context is complete.
[VB.NET] 
Dim pGISServerConnection As IGISServerConnection = New GISServerConnection()
pGISServerConnection.Connect("melange")

Dim pServerObjectManager As IServerObjectManager
Set pServerObjectManager = pGISServerConnection.ServerObjectManager

Dim pServerContext As IServerContext = pServerObjectManager.CreateServerContext(String.Empty, String.Empty)

' Create a new polygon in the server context.
Dim pGonColl As IPointCollection = pServerContext.CreateObject("esriGeometry.Polygon")

' Create the points in the server context.
Dim pPoint(4) As IPoint
Dim i As Long
For i = 0 To 3
Set pPoint(i) = pServerContext.CreateObject("esriGeometry.Point")
Next

pPoint(0).PutCoords (0, 0)
pPoint(1).PutCoords (10, 0)
pPoint(2).PutCoords (10, 10)
pPoint(3).PutCoords (0, 10)
'Add the points to the polygon.
pGonColl.AddPoints (4, pPoint(0))

Dim pArea As IArea = pGonColl

Debug.Print (pArea.Area)

pServerContext.ReleaseContext()
Server contexts
A server context is a reserved space within the server dedicated to a set of running objects. GIS server objects also reside in a server context. When developing applications with ArcGIS Server, all ArcObjects that your application creates and uses reside within a server context. To obtain a server object, you get a reference to its context, then get the server object from the context.
 
You get a server context by calling the CreateServerContext method on IServerObjectManager.
 
IServerContext contains methods for creating and managing objects running within ServerContext. You can get at the server object running within a server context using the ServerObject property on IServerContext.
 
The following code is an example of creating a server context and getting a reference to the MapServer server object running in the server context.

[VB.NET] 
Dim IServerContext as IServerContext = pServerObjectManager.CreateServerContext("RedlandsMap","MapServer")
Dim pMapServer as IMapServer = pServerContext.ServerObject
You can also create empty server contexts. You can use an empty context to create ArcObjects on the fly within the server to perform add hoc GIS processing. The following code is an example of creating an empty server context.

[VB.NET] 
Dim IServerContext as IServerContext = pServerObjectManager.CreateServerContext(String.Empty, String.Empty)
Dim pWorkspaceFactory as IWorkspaceFactory = pServerContext.CreateObject("esriDataSourcesGDB.SdeWorkspaceFactory")
All ArcObjects that your application uses should be created within a server context using the CreateObject method on IServerContext. Also, objects that are used together should be in the same context. For example, if you create a Point object to use in a spatial selection to query features in a feature class, the point should be in the same context as the feature class.
 
ArcGIS Server applications should not use New to create ArcObjects but should always create objects by calling CreateObject on IServerContext.
 
The following sample code is incorrect:

[VB.NET] 
Dim pPoint as IPoint = New Point()
The following sample code is correct:
[VB.NET] 
Dim pPoint as IPoint = pServerContext.CreateObject("esriGeometry.Point")
When your application is finished working with a server context, it must release it back to the server by calling the ReleaseContext method. If you allow the context to go out of scope without explicitly releasing it, it will remain in use and be unavailable to other applications until it is garbage collected. Once a context is released, the application can no longer make use of any objects in that context. This includes both objects that you may have obtained from the context or objects that you created in the context. The following code shows this.

[VB.NET] 
Dim IServerContext as IServerContext = pServerObjectManager.CreateServerContext("RedlandsMap","MapServer")
Dim pMapServer as IMapServer = pServerContext.ServerObject
' Do something with the object.
pContext.ReleaseContext()
The IServerContext interface has a number of methods for helping you manage the objects you create within server contexts. The following is a description of how and when you would use these methods. Use the CreateObject method when you need to create an object for use in your application.
[VB.NET] 
Dim pPointCollection as IPointCollection = pServerContext.CreateObject("esriGeometry.Polygon")
CreateObject will return a proxy to the object that's in the server context. Your application can make use of the proxy as if the object was created locally within its process. If you call a method on the proxy that hands back another object, that object will be in the server context, and your application will be handed back a proxy to that object. In the above example, if you get a point from the point collection using IPointCollection.Point(), the point returned will be in the same context as the point collection.
 
If you add a point to the point collection using IPointCollection.AddPoint(), the point should be in the same context as the point collection as shown in the following code.

[VB.NET] 
Dim pPointCollection as IPointCollection = pServerContext.CreateObject("esriGeometry.Polygon")

Dim pPoint as IPoint = pServerContext.CreateObject("esriGeometry.Point")
pPoint.X = 1
pPoint.Y = 1

pPointCollection.AddPoint (pPoint)
You should not directly use objects in a server context with local objects in your application and vice versa. You can indirectly use objects or make copies of them. For example, if you have a Point object in a server context, you can get its X,Y properties and use them with local objects or use them to create a new local point. Don’t directly use the point in the server context as, for example, the geometry of a local graphic element object.
 
Consider the following code examples. In each example, assume that objects with Remote in their names are objects in a server context as in:

[VB.NET] 
Dim pRemotePoint as IPoint = pServerContext.CreateObject("esriGeometry.Point")
while objects with Local in their name are objects created locally as in:
[VB.NET] 
Dim pLocalPoint as IPoint = New Point()
You can’t set a local object to a remote object:
[VB.NET] 
' This is incorrect:
Set pLocalPoint = pRemotePoint

' This is also incorrect:
Set pLocalElement.Geometry = pRemotePoint
Do not set a local object, or a property of a local object, to be an object obtained from a remote object:
[VB.NET] 
' This is incorrect:
Set pLocalPoint = pRemotePointCollection.Point(0)
When calling a method on a remote object, don’t pass in local objects as parameters:
[VB.NET] 
' This is incorrect:
Set pRemoteWorkspace = pRemoteWorkspaceFactory.Open(pLocalPropertySet,0)
You can get simple data types—double, long, string, and so on—that are passed by value from a remote object and use them as properties of a local object as in:
[VB.NET] 
' This is acceptable:
pLocalPoint.X = pRemotePoint.X
pLocalPoint.Y = pRemotePoint.Y
SetObject and GetObject allow you to store references to objects in the server context. A context contains a dictionary that you can use to store objects that you create within the context. This dictionary is valid only as long as you hold on to the server context, and it is emptied when you release the context. You can use this dictionary to share objects created within a context between different parts of your application that have access to the context. This dictionary is illustrated here:
 
 
SetObject adds objects to the dictionary, and GetObject retrieves them. An object that is set in the context will be available until it is removed (by calling Remove or RemoveAll) or until the context is released as shown in the following code.

[VB.NET] 
Dim pPointCollection as IPointCollection = pServerContext.CreateObject("esriGeometry.Polygon")

pServerContext.SetObject ("myPoly", pPointCollection)
Dim pPoly as IPolygon = pServerContext.GetObject("myPoly")
Use the Remove and RemoveAll methods to remove objects from a context that has been set using SetObject. Once an object is removed, a reference can no longer be made to it using GetObject. If you do not explicitly call Remove or RemoveAll, you cannot get references to objects set in the context after the context has been released as shown in the following code.
[VB.NET] 
pServerContext.Remove ("myPoly")
The SaveObject and LoadObject methods allow you to serialize objects in the server context to strings, then deserialize them back into objects. Any object that supports IPersistStream can be saved and loaded using these methods. These methods allow you to copy objects between contexts. For example, if you use a GeocodeServer object to locate an address, and you want to draw the point that GeocodeAddress returns on your map, you need to copy the point into your MapServer's context as shown in the following code.
[VB.NET] 
Dim pServerContext As IServerContext = pSOM.CreateServerContext("RedlandsMap", "MapServer")
Dim pServerContext2 As IServerContext = pSOM.CreateServerContext("RedlandsGeocode", "GeocodeServer")

Dim pGCServer As IGeocodeServer = pServerContext2.ServerObject
Dim pPropertySet As IPropertySet = pServerContext2.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")

' Copy the point to the MapServer's context.
Dim sPoint As String = pServerContext2.SaveObject(pPoint)
Dim pPointCopy As IPoint = pServerContext.LoadObject(sPoint)
The process of copying objects between server contexts using SaveObject and LoadObject is as follows:
  1. The client application gets or creates an object within a server context.
  2. The application uses the SaveObject method on the object’s context to serialize the object as a string that is held in the application’s session state.
  3. The client application gets a reference to another server context and calls the LoadObject method, passing in the string created by SaveObject. LoadObject creates a new instance of the object in the new server context.
This process is shown in the following illustration:
 
 
Another use of these methods is managing state in your application while making stateless use of a pooled server object. An example of this is in a mapping application. The initial session state for all users is the same and is equal to the map description for the map server object. Each user can then change map description properties, such as the extent and layer visibility, which need to be maintained in the user’s session state. The application does this by saving a serialized map description as part of each user’s session state. Using the serialized string representation allows the application to take advantage of the standard session state management facilities of the Web server. The application uses the LoadObject and SaveObject methods to reconstitute the session’s map description whenever it needs to make edits to it in response to user changes or whenever it needs to pass the map descriptor to the map server object for drawing the map according to the user’s specifications. This process is shown in the following illustration:
 
 
 
Server objects
ServerObject is a coarse-grained ArcObjects component and a high-level object that simplifies the programming model for certain operations and hides the fine-grained ArcObjects that do the work. Server objects support coarse-grained interfaces that support methods that do large units of work, such as draw a map or geocode a set of addresses. ServerObjects also have Simple Object Access Protocol (SOAP) interfaces, which makes it possible to expose server objects as Web services that can be consumed by clients across the Internet.
 
ArcGIS Server has five ServerObjects: MapServer, GeocodeServer, GeoDataServer, GlobeServer, and GPServer.
 
Server objects and their extensions can be used in ArcGIS Server applications, in which case the server object manager creates and manages instances of the server object and its extensions in process running within the server. You get a reference to a server object running in the GIS server from its ServerContext.
 
Because server objects are Component Object Model (COM) objects, they and their extensions can be used in ArcGIS Engine or ArcGIS Desktop applications. ServerObjectFactory allows you to create an instance of a server object and any enabled extensions for use in such applications.
 
Use the CreateServerObject method on IServerObjectFactory to create an instance of a server object.
 
The following C# code illustrates the use of IServerObjectFactory to create a MapServer object and an associated server object extension called MySOE outside the server environment.

[C#] 
ServerObjectFactory sof = new ServerObjectFactory();
IServerObject so = sof.CreateServerObject("43E4F6B6-7B17-4536-B7CF-C0454EBB0F5A", "SomeMap", "MapServer");
IServerObjectExtensionManager extMgr = (IServerObjectExtensionManager) so;
IServerObjectExtension soe = extMgr.FindExtensionByName("MySOE");

// Set a property called PropName to the Value for your server object extension called MySOE.
IMySOE mySOE = (IMySOE) soe;
IPropertySet pSet = new PropertySet();
pSet.SetProperty("PropName", "Value");
IObjectConstruct objConstruct = (IObjectConstruct) mySOE;
objConstruct.Construct(pSet);
IServerObject is an interface supported by all server objects. The IServerObject interface is returned as the ServerObject property on IServerContext. The IServerObject interface has properties to indicate the name and type of the server object configuration that created the server object. You can query this interface for interfaces supported by the server object type, such as IMapServer for a MapServer object or IGeocodeServer for a GeocodeServer object.
 
The following code shows how to connect to a GIS server, create a server context based on a server object configuration, and use the ServerObject property to get the IServerObject interface on the server context's server object.

[VB.NET] 
Dim pGISServerConnection As IGISServerConnection = New GISServerConnection()
pGISServerConnection.Connect ("padisha")

Dim pSOM As IServerObjectManager = pGISServerConnection.ServerObjectManager
Dim pContext As IServerContext = pSOM.CreateServerContext("MyMapServer", "MapServer")

Dim pServerObject As IServerObject = pContext.ServerObject
Dim pMapServer As IMapServer = pServerObject

' Do something with the MapServer.

pContext.ReleaseContext()

Server object extensions

Some server objects have extensions that extend their base functionality for more specialized uses. Each type of server object may have a set of extensions that can be enabled or disabled based on its configuration. For example, the MapServer server object includes a network analysis server object extension that can be enabled for map servers that include network analysis layers and are intended for use in applications that include routing, service area, or some other network analysis type of functionality. ArcGIS Server includes a number of server object extensions out of the box, and you can extend ArcGIS Server by writing your own server object extensions.
 
Server object extensions also have SOAP interfaces for handling SOAP requests to execute methods and returning results as SOAP responses. This support for SOAP request handling makes it possible to expose server object extensions as Web services that can be consumed by clients across the Internet.
 
ArcGIS Server 9.2 includes the following server object extensions to the MapServer:
 
IServerObjectExtensionManager is an interface supported by all server objects. Once you have a reference to a server object, you can use the methods on IServerObjectExtensionManager to find enabled extensions either by type name (FindExtensionByTypeName) or by class identifier (CLSID) (FindExtensionByCLSID). Once you have a reference to the server object extension, you can query interface (QI) for any of its interfaces.
 
The following VB.NET code shows how to get the NAServer extension to a MapServer and find the network analysis layers in the map.

[VB.NET] 
Dim pServerContext As IServerContext = pSOM.CreateServerContext("usa", "MapServer")

Dim pMapServer As IMapServer = pServerContext.ServerObject
Dim pSOExtManager As IServerObjectExtensionManager = pMapServer
Dim pSOExt As IServerObjectExtension = pSOExtManager.FindExtensionByTypeName("NAServer")

Dim pNAServer As INAServer = pSOExt
Dim layers As String() = pNAServer.GetNALayerNames(esriNAServerLayerType.esriNAServerRouteLayer)

pServerContext.ReleaseContext()
The Info classes
The Server object library’s Info classes provide read-only access to the properties of server directories, server types, and server object configurations to users and developers who are not administrators. These properties are necessary for developing applications using the GIS server.
 
Each Info class has a corresponding class that is only accessible to administrators (users in the agsadmin user group), which exposes the properties of the Info object with read/write access as well as additional properties.
 
The GIS server manages a set of server directories. A server directory is a location on a file system that the GIS server is configured to clean up files it writes. The ServerDirectoryInfo class gives users and developers who are not administrators access to the list of server directories and the set of their properties that are necessary for programming applications that use them as locations to write output. You can get information about server directories using the GetServerDirectoryInfos method on IServerObjectManager to get the IServerDirectoryInfo interface.
 
Files in a server directory can be cleaned up based on file age or when the file was last accessed. The maximum file age or time since last accessed is a property of a server directory. If the CleaningMode is esriSDCAbsolute, then all files created by the GIS server that are older than the maximum age are automatically cleaned up by the GIS server. If the CleaningMode is esriSDCSliding, then all files created by the GIS server that have not been accessed for a duration defined by maximum age are automatically cleaned up by the GIS server.
 
When creating files in a server directory, they must be prefixed with "_ags_" to be cleaned up by the GIS server. Any files in a server directory not prefixed with _ags_ will not be cleaned up. IServerDirectoryInfo provides read–only access to a subset of the server directory's properties. These properties include the following:
 
The properties listed above are those necessary for developers of server applications to make use of the various GIS servers’ server directories.
 
The following code shows how to list the server directories of a GIS server using the ServerDirectoryInfo class.

[VB.NET] 
Dim pSC As IGISServerConnection = New GISServerConnection()
pSC.Connect ("padisha")

Dim pSOM As IServerObjectManager = pSC.ServerObjectManager
Dim pEnumSDirInfo As IEnumServerDirectoryInfo = pSOM.GetServerDirectoryInfos

Dim pSDirInfo As IServerDirectoryInfo = pEnumSDirInfo.Next()
Do Until pSDirInfo Is Nothing
  Debug.Print (pSDirInfo.Path)
  Set pSDirInfo = pEnumSDirInfo.Next()
Loop
A ServerObjectConfigurationInfo object is an Info object that describes the properties of a server object configuration. 
 
The GIS server manages a set of server objects running across one or more host (container) machines. How those server objects are configured and run is defined by a set of server object configurations. The ServerObjectConfigurationInfo class gives users and developers who are not administrators access to the list of server object configurations and the set of their properties that are necessary for programming applications with them. You can get information about server object configurations using the GetConfigurationInfos method on IServerObjectManager to get the IServerObjectConfigurationInfo interface. The GetConfigurationInfos method returns only server object configurations that are started.
 
IServerObjectConfigurationInfo provides read–only access to a subset of the server object configuration's properties. These properties include the following:
The properties listed previously are those necessary for developers of server applications to make use of the various server objects configured on the GIS server.
The following code example shows how to connect to a GIS server and use the IServerObjectConfigurationInfo interface to print out the name and type of all the server object configurations.

[VB.NET] 
Dim pGISServerConnection As IGISServerConnection = New GISServerConnection()
pGISServerConnection.Connect ("melange")

Dim pSOM As IServerObjectManager = pGISServerConnection.ServerObjectManager
Dim pEnumSOCInfo As IEnumServerObjectConfigurationInfo = pSOM.GetConfigurationInfos

Dim pSOCInfo As IServerObjectConfigurationInfo = pEnumSOCInfo.Next()
Do Until pSOCInfo Is Nothing
  Debug.Print (pSOCInfo.Name & ": " & pSOCInfo.TypeName)
  Set pSOCInfo = (pEnumSOCInfo.Next)
Loop
IServerObjectConfigurationInfo2 extends this interface to provide the names of all enabled server object extensions for a particular configuration. Only those server object extensions that are enabled for this configuration are returned by the Extensions property. To get a complete list of all server object extensions that are supported for a particular type of server object, use the GetExtensionTypeInfos method on IServerObjectManager2.
 
A ServerObjectTypeInfo object is an Info object that describes the properties of a server object type.
 
The ServerObjectTypeInfo class gives users and developers who are not administrators access to the list of server object types and the set of their properties that are necessary for programming applications. You can get information about server object types using the GetTypeInfos method on IServerObjectManager to get the IServerObjectTypeInfo interface.
 
IServerObjectTypeInfo provides read–only access to a subset of the server object type's properties. These properties include the following:
 
A ServerObjectExtensionTypeInfo object is an Info object that describes the properties of a server object extension type.
 
The ServerObjectExtensionTypeInfo class gives users and developers who are not administrators access to the list of server object extension types and the set of their properties that are necessary for programming applications. You can get information about server object extension types using the GetExtensionTypeInfos method on IServerObjectManager2 to get the IServerObjectExtensionTypeInfo interface.
 
IServerObjectExtensionTypeInfo provides read–only access to a subset of the server object extension type's properties. These properties include the following:

Server Administration Objects
When developing applications that connect to a GIS server for the purposes of administering the GIS server and its server objects, you need to have access to the objects for administering these aspects of the GIS server. If your application runs as a user account in the agsadmin user group on the GIS server, then that application will be able to connect to the GIS server using the GISServerConnection object and can get a reference to the set of objects that provides the ability for the application to administrate the GIS server and its server objects.
 
The Server Administration Objects object model diagram is shown here:
 
 
Applications that make use of ArcObjects running in the server do not require access to the administration objects.
 
The ServerObjectAdmin class administrates a GIS server. Any application that runs as a user account in the agsadmin user group on the GIS server can use the IGISServerConnection interface to connect to the GIS server and to get a reference to ServerObjectAdmin. If the user account is not part of the agsadmin user group, the ServerObjectAdmin property on IGISServerConnection will return an error. Applications that are running as accounts that can connect to the server but are not part of the agsadmin user group can use the ServerObjectManager property on IGISServerConnection to get a reference on ServerObjectManager.
 
Use ServerObjectAdmin to administrate the set of server object configurations and types associated with the server as well as to administer aspects of the server itself. The following administration functionality of the GIS Server is provided by ServerObjectAdmin.
 
Administer server object configurations:
 
Administer aspects of the server itself:
 
You can use IServerObjectAdmin to administrate either the server’s set of server object configurations and server object types or the aspects of the server itself, such as the list of machines that may host server objects. If your application is connecting to the server to make use of objects in the server, use the IServerObjectManager interface.
 
Administer server object configurations
The AddConfiguration method will add a ServerObjectConfiguration to your GIS server. A new ServerObjectConfiguration can be created using the CreateConfiguration method. Use the IServerObjectConfiguration interface to set the various properties of the configuration, then use the AddConfiguration method on IServerObjectAdmin to add the new configuration to the GIS server. Once a configuration is added to the server, you can use StartConfiguration to make it available for applications to use.
 
The following code shows how to connect to the GIS server melange and use the CreateConfiguration, AddConfiguration, and StartConfiguration methods to create a new geocode server object configuration, add it to the server, and make it available for use.

[VB.NET] 
Dim pGISServerConnection As IGISServerConnection = New GISServerConnection()
pGISServerConnection.Connect ("melange")

Dim pServerObjectAdmin As IServerObjectAdmin = pGISServerConnection.ServerObjectAdmin

' Create the new configuration.
Dim pConfiguration As IServerObjectConfiguration = pServerObjectAdmin.CreateConfiguration()

pConfiguration.Name = "California"
pConfiguration.TypeName = "GeocodeServer"

Dim pProps As IPropertySet = pConfiguration.Properties
pProps.SetProperty ("LocatorWorkspacePath", "\\melange\Geocoding\California")
pProps.SetProperty ("Locator", "California")
pProps.SetProperty ("SuggestedBatchSize", "500")

pConfiguration.IsPooled = True
pConfiguration.MinInstances = 1
pConfiguration.MaxInstances = 1

pConfiguration.WaitTimeout = 10
pConfiguration.UsageTimeout = 120

' Add the configuration to the server.
pServerObjectAdmin.AddConfiguration (pConfiguration)
The UpdateConfiguration method will update the ServerObjectConfiguration that is specified when the method is called. You can use the GetConfiguration or GetConfigurations methods on IServerObjectAdmin to get a reference to the ServerObjectConfiguration you want to update.
 
The server object configuration must be stopped before you call UpdateConfiguration. You can use StopConfiguration to stop the server object configuration.
 
The following code shows how to connect to the GIS server melange and use GetConfiguration to get ServerObjectConfiguration, change its MinInstances property, then update the configuration using the UpdateConfiguration method.

[VB.NET] 
Dim pGISServerConnection As IGISServerConnection = New GISServerConnection()
pGISServerConnection.Connect ("melange")

Dim pServerObjectAdmin As IServerObjectAdmin = pGISServerConnection.ServerObjectAdmin
Dim pConfig as IServerObjectConfiguration = pServerObjectAdmin.GetConfiguration ("RedlandsMap", "MapServer")

pConfig.MinInstances = 3
pServerObjectAdmin.UpdateConfiguration (pConfig)
Use DeleteConfiguration to delete a server object configuration from your GIS server. To call DeleteConfiguration, the server object configuration must be stopped. If it is not stopped, DeleteConfiguration will return an error.
 
The following code shows how to stop, then delete, a server object configuration called RedlandsMap.

[VB.NET] 
Dim pGISServerConnection As IGISServerConnection = New GISServerConnection()
pGISServerConnection.Connect ("melange")

Dim pServerObjectAdmin As IServerObjectAdmin = pGISServerConnection.ServerObjectAdmin

pServerObjectAdmin.StopConfiguration ("RedlandsMap", "MapServer")
pServerObjectAdmin.DeleteConfiguration ("RedlandsMap", "MapServer")
The GetConfigurations method returns an enumeration of all the server object configurations that are configured in the GIS server. The following code shows how to connect to the GIS server melange and print the name and type of all its server object configurations.
[VB.NET] 
Dim pGISServerConnection As IGISServerConnection = New GISServerConnection()
pGISServerConnection.Connect ("melange")

Dim pServerObjectAdmin As IServerObjectAdmin = pGISServerConnection.ServerObjectAdmin
Dim pEnumSOC As IEnumServerObjectConfiguration = pServerObjectAdmin.GetConfigurations()

Dim pSOC As IServerObjectConfiguration
Set pSOC = pEnumSOC.Next()
Do Until pSOC Is Nothing
  Debug.Print (pSOC.Name & ": " & pSOC.TypeName)
  Set pSOC = pEnumSOC.Next()
Loop
IServerObjectAdmin2 extends IServerObjectAdmin with additional server administration capabilities. Use the Enable and Disable methods to suspend and resume access to the server from client applications. Disabling the server does not affect pooled server objects.
 
GetExtensionTypes returns a collection of the installed server object extensions for a particular server object type, while CreateExtensionType and AddExtensionType allow you to add your own custom server object extensions to the server.
 
The IServerStatus interface provides methods and properties that return the status of server object configurations and server machines. The GetConfigurationStatus method returns a ConfigurationStatus object that reports the number of instances running and in use for the configuration.
 
The GetMachineStatus method returns a ServerMachineStatus object that supports the IServerMachineStatus interface with properties to get the number of server object instances running on the machine (InstanceCount) and the number currently in use (InstanceInUseCount).
 
The SOMController class allows you to start and stop the GIS server. Use the methods on ISOMController to check if the server is running and to stop and start the server.
 
The ServerObjectConfiguration class describes the configuration for a server object that is managed by the GIS server. ServerObjectConfigurations can be added, removed, and modified by users or developers who are members of the agsadmin users group and, therefore, have administrator privileges on the GIS server.
 
The administrator-level properties of ServerObjectConfiguration are as follows:
 
A read-only subset of properties of a ServerObjectConfiguration is available to nonadministrators via the GISServerConnectionInfo object. These nonadministrator level properties are as follows:
 
The IServerObjectConfiguration interface is a read/write interface on a server object configuration that allows administrators to configure new server object configurations to add to the server, update existing server object configurations, and view the configuration properties of a server object configuration.
 
If you use IServerObjectConfiguration to modify any of a configuration’s properties, you must call UpdateConfiguration on IServerObjectAdmin for those changes to be reflected in the server.
 
The following code shows how to connect to the GIS server melange and use the IServerObjectConfiguration interface to set the properties of a new server object configuration created and added to the server with the CreateConfiguration and AddConfiguration methods on IServerObjectAdmin to create a new geocode server object configuration and add it to the server.

[VB.NET] 
Dim pGISServerConnection As IGISServerConnection = New GISServerConnection()
pGISServerConnection.Connect ("melange")

Dim pServerObjectAdmin As IServerObjectAdmin = pGISServerConnection.ServerObjectAdmin

' Create the new configuration.
Dim pConfiguration As IServerObjectConfiguration = pServerObjectAdmin.CreateConfiguration()
pConfiguration.Name = "California"
pConfiguration.TypeName = "GeocodeServer"

Dim pProps As IPropertySet = pConfiguration.Properties
pProps.SetProperty "LocatorWorkspacePath", "\\melange\Geocoding\California"
pProps.SetProperty "Locator", "California"
pProps.SetProperty "SuggestedBatchSize", "500"

pConfiguration.IsPooled = True
pConfiguration.MinInstances = 1
pConfiguration.MaxInstances = 1
pConfiguration.WaitTimeout = 10
pConfiguration.UsageTimeout = 120

' Add the configuration to the server.
pServerObjectAdmin.AddConfiguration (pConfiguration)
Use the IsolationLevel property to get the server object isolation, or set it for a new configuration or to update an existing configuration.
 
Server objects can have either high isolation (esriServerIsolationLevelHigh) or low isolation (esriIsolationLevelLow). Each instance of a server object with high isolation runs in a dedicated process on the server that it does not share with other server objects. Instances of server objects with low isolation may share the same process with other server object instances of the same configuration. Use the IsPooled property to indicate if the server objects created by this server object configuration are pooled or non-pooled.
 
Pooled server objects can be shared across multiple sessions and applications and are held by an application for the duration of a single request. Pooled server objects are meant for applications that make stateless use of those objects.
 
Non-pooled server objects are dedicated to a single application session and are held for the duration of an application session. Non-pooled server objects are not shared between application sessions and are meant for applications that make stateful use of those objects.
 
When StartConfiguration is called on a server object configuration whose IsPooled property is true, a set of server objects will be preloaded based on the MinInstances property of the server object configuration. When StartConfiguration is called on a server object configuration whose IsPooled property is false, no server objects are pre-loaded. Server objects are loaded and initialized when an application gets one from the server using CreateServerContext.
 
The MaxInstances property indicates the maximum number of server objects that can be running and handle requests at any one time. If the maximum number of server objects are running and busy, additional requests will be queued until a server object becomes free.
 
For a pooled server object, MaxInstances represents the maximum simultaneous requests that can be processed by the server object configuration. For a non-pooled server object, MaxInstances represents the maximum number of simultaneous application users of that particular server object configuration. The MaxInstances property must be greater than 0 and must be greater than the MinInstances property. The MinInstances property applies to only pooled server object configurations. It represents the number of server object instances that are preloaded when the server object configuration is started. The GIS server will ensure that the minimum number of instances are always running within the server for a given configuration. When there are more simultaneous requests than server object instances running, additional server object instances will be started until MaxInstances is reached.
 
Non-pooled server object configurations always have a MinInstances property of 0. The MinInstances property must be less than the MaxInstances property. The Name property in combination with the TypeName property is used to identify a server object configuration in methods such as GetConfiguration, UpdateConfiguration, StartConfiguration, and so on.
 
Name is case sensitive and can have a maximum of 120 characters. Names can contain only the following characters:
A–Z
a–z
0–9
_ (underscore)
- (minus)
 
The TypeName property indicates the type of server object that this configuration creates and runs. Examples are MapServer and GeocodeServer.
 
Server objects that are defined by server object configurations have a collection of initialization parameters and properties associated with them. An example of an initialization parameter is the map document associated with a MapServer object. An example of a property is the batch geocode size for a GeocodeServer object. You can get these properties and change them using the Properties property on the server object configuration. The Properties property returns IPropertySet. Use GetProperties and SetProperties on IPropertySet to get and set these properties. If you change these properties, you must call UpdateConfiguration to change them in the server object configuration.
 
You can also use the Properties property to get a reference on the PropertySet for a new server object configuration to set its properties before adding it to the server by calling AddConfiguration.
 
The following code shows how to connect to the GIS server melange and use the CreateConfiguration, AddConfiguration, and StartConfiguration methods to create a new geocode server object configuration, add it to the server, and make it available for use. Note how the Properties property is called to get a reference to the server object configuration's properties.

[VB.NET] 
Dim pGISServerConnection As IGISServerConnection = New GISServerConnection()
pGISServerConnection.Connect ("melange")

Dim pServerObjectAdmin As IServerObjectAdmin = pGISServerConnection.ServerObjectAdmin

' Create the new configuration.
Dim pConfiguration As IServerObjectConfiguration = pServerObjectAdmin.CreateConfiguration()
pConfiguration.Name = "California"
pConfiguration.TypeName = "GeocodeServer"

Dim pProps As IPropertySet = pConfiguration.Properties
pProps.SetProperty "LocatorWorkspacePath", "\\melange\Geocoding\California"
pProps.SetProperty "Locator", "California"
pProps.SetProperty "SuggestedBatchSize", "500"

pConfiguration.IsPooled = True
pConfiguration.MinInstances = 1
pConfiguration.MaxInstances = 1

Dim pRecProps As IPropertySet = pConfiguration.RecycleProperties
pRecProps.SetProperty "StartTime", "00:00"
pRecProps.SetProperty "Interval", "3600"

' Add the configuration to the server.
pServerObjectAdmin.AddConfiguration (pConfiguration)

' Start the configuration.
pServerObjectAdmin.StartConfiguration (pConfiguration.Name, pConfiguration.TypeName)
Recycling allows server objects that have become unusable to be destroyed and replaced with fresh server objects and to reclaim resources taken up by stale server objects.
 
Pooled server objects are typically shared between multiple applications and users of those applications. Through reuse, a number of things can happen to a server object to make them unavailable for use by applications. For example, an application can incorrectly modify a server object’s state, or an application can incorrectly hold a reference to a server object, making it unavailable to other applications or sessions. In some cases, a server object can become corrupted and unusable.
 
Recycling allows you to keep the pool of server objects fresh and cycle out stale or unusable server objects. You can get the recycling properties and change them using the RecycleProperties property on the server object configuration. The RecycleProperties property returns IPropertySet. Use GetProperty and SetProperty on IPropertySet to get and set these properties. If you change these properties, you must call UpdateConfiguration to change them in the server object configuration.
 
The properties associated with recycling are as follows:
 
The StartupType indicates if the configuration is automatically started (esriSTAutomatic) when the server object manager windows service is started. Server object configurations that are not configured to start up automatically (esriSTManual) must be started manually using ArcCatalog or by calling the StartConfiguration method on IServerObjectAdmin.
 
The amount of time it takes between a client requesting a server object (using the CreateServerContext method on IServerObjectManager) and getting a server object is called the wait time. A server object can be configured to have a maximum wait time by specifying the WaitTimeout property on IServerObjectConfiguration. If a client’s wait time exceeds the maximum wait time for a server object, the request will time out. The WaitTimeout property is in seconds.
 
Once a client gets a reference to a server object, it can hold on to that server object as long as desired before releasing it. The amount of time between when a client gets a reference to a server object and when it is released is the usage time. To ensure that clients don’t hold references to server object’s for too long (e.g., they don’t correctly release server objects), a server object can be configured to have a maximum usage time by specifying the UsageTimeout property on IServerObjectConfiguration. If a client holds on to a server object longer than the maximum usage time, the server object is automatically released, and the client will lose the reference to the server object. The UsageTimeout property is in seconds.
 
IServerObjectConfiguration2 extends IServerObjectConfiguration with properties for managing the server object configuration's extensions. Set the ExtensionEnabled property to true for the server object extensions you want to enable for this configuration. A list of the server object extensions installed on the GIS server for each server object type is available via IServerObjectManager2.GetExtensionTypeInfos.
 
Use the ExtensionProperties property to specify the collection of properties for a server object extension.
 
The Serialize and Deserialize methods allow you to save the server object configuration as a string and restore it from a string. This can be useful when copying server object configurations between two GIS servers.
 
IServerObjectConfiguration2 allows you to set two additional time out properties for a server object:
Administer server machines
ArcGIS Server is a distributed system. Server objects managed by the GIS server can run on one or more host machines. A machine that can host server objects must have the Server Object Container installed, and the machine must be added to the list of host machines managed by the Server Object Manager.
 
Use the AddMachine method to add new host machines to your GIS server. Once a machine has been added to the GIS server, as new server object instances are created, the server object manager will make use of the new machine. Use the CreateMachine method to create a new server machine that you can pass as an argument to the AddMachine method to add new host machines to your GIS server.
 
The following code shows how to use the CreateMachine and AddMachine methods to add a machine to your GIS server.

[VB.NET] 
Dim pGISServerConnection As IGISServerConnection = New GISServerConnection()
pGISServerConnection.Connect ("melange")

Dim pServerObjectAdmin As IServerObjectAdmin = pGISServerConnection.ServerObjectAdmin
Dim pServerMachine As IServerMachine = pServerObjectAdmin.CreateMachine()
pServerMachine.Name = "callum"

Dim pServerMachine2 as IServerMachine2 = pServerMachine
pServerMachine2.Capacity = 20

pServerObjectAdmin.AddMachine (pServerMachine)
Use the GetMachines method to get the names of the machines that have been added to the server to host server objects.
 
The DeleteMachine method removes a machine from the machines that can host server objects for the GIS server. When you delete a machine, any instances of server objects that are running on that machine will be shut down and replaced with instances running on the GIS server’s other host machines.
 
The ServerMachine class is used to define a machine that can host server objects managed by the GIS server.
 
IServerMachine allows you to configure the properties of a machine to add it to the GIS server. You must set the Name property for the machine, which will be the name of the machine on the network. The description is optional.
 
Use the AddMachine method to add new machines to your GIS server. All server objects configured in the GIS server can run on any of the host machines, so all host machines must have access to the necessary data and output directories used by all the server objects.
 
IServerMachine2 extends IServerMachine to include a Capacity property. The Capacity property defines the number of configuration instances on a server object container (SOC) machine that are allowed to run concurrently before the pool-shrinking algorithm engages. The pool-shrinking algorithm removes the least recently used configuration instances and replaces them with new instances. Capacity is dependent on system memory and CPU resources and should be tuned for each machine in the GIS server.
 
The following code shows how to use the IServerMachine interface and AddMachine method to add a machine to your GIS server.

[VB.NET] 
Dim pGISServerConnection As IGISServerConnection = New GISServerConnection()
pGISServerConnection.Connect ("melange")

Dim pServerObjectAdmin As IServerObjectAdmin = pGISServerConnection.ServerObjectAdmin
Dim pServerMachine As IServerMachine = pServerObjectAdmin.CreateMachine()
pServerMachine.Name = "callum"

Dim pServerMachine2 as IServerMachine2 = pServerMachine
pServerMachine2.Capacity = 20

pServerObjectAdmin.AddMachine (pServerMachine)
Administer server directories
You can use IServerObjectAdmin to add and remove server directories from the GIS server. Server objects and server applications typically need to write either temporary data or result data to some location for it to be delivered or presented to the end user. For example, a map server object’s ExportMapImage method can create an image file that is then displayed on a Web application. These files are typically transient and temporary by nature. For example, when a map server writes an image to satisfy a request from a Web application, that image is needed only for the time it takes to display on the Web application. An application that creates check-out personal geodatabases for download would provide a finite amount of time during which that geodatabase is created and when it can be downloaded.
 
Because server applications support many user sessions, these output files can accumulate and need to be periodically cleaned up. The server provides the capability to automatically cleanup these output files if they are written to one of the server's output directories.
 
Use the CreateServerDirectory method to create a new server directory that you can pass as an argument to the AddServerDirectory method to add new server directories to your GIS server. Once you have added the server directory, you can configure your server objects and server applications to make use of the server directory.
 
Server directories must be accessible by all host machines configured in the GIS server.
 
The following code shows how to use the CreateServerDirectory and AddServerDirectory methods to add a directory to your GIS server.

[VB.NET] 
Dim pGISServerConnection As IGISServerConnection = New GISServerConnection()
pGISServerConnection.Connect ("melange")

Dim pServerObjectAdmin As IServerObjectAdmin = pGISServerConnection.ServerObjectAdmin
Dim pSDir As IServerDirectory = pServerObjectAdmin.CreateServerDirectory()

pSDir.CleaningMode = esriServerDirectoryCleaningMode.esriSDCAbsolute
pSDir.Description = "Default output directory"
pSDir.Path = "\\melange\serveroutput"

pSDir.URL = "http://melange/serveroutput"
pSDir.MaxFileAge = 100

pServerObjectAdmin.AddServerDirectory (pSDir)
The UpdateServerDirectory method will update the ServerDirectory that is specified when the method is called. You can use the GetServerDirectory or GetServerDirectories methods on IServerObjectAdmin to get a reference to the ServerDirectory you want to update.
 
UpdateServerDirectory is useful for modifying the cleanup mode (CleaningMode) and cleanup schedule.
 
The following code shows how to connect to the GIS server melange and use the GetServerDirectory method to get a ServerDirectory, change its MaxFileAge property, then update the directory using the UpdateServerDirectory method.

[VB.NET] 
Dim pGISServerConnection As IGISServerConnection = New GISServerConnection()
pGISServerConnection.Connect ("padisha")

Dim pServerObjectAdmin As IServerObjectAdmin = pGISServerConnection.ServerObjectAdmin

Dim pSDir As IServerDirectory = pServerObjectAdmin.GetServerDirectory("\\melange\serveroutput")
pSDir.MaxFileAge = 200
pServerObjectAdmin.UpdateServerDirectory (pSDir)
The DeleteServerDirectory method removes a directory from the set of directories managed by the GIS server. The DeleteServerDirectory method will not affect the physical directory. When a server directory is removed with this method, the GIS server will no longer manage the cleanup of output files written to that directory. Applications or server objects that are configured to write their output to the physical directory that is referenced by the server directory will continue to work, but the files they write will not be cleaned up by the server.
 
The ServerDirectory class defines the properties of a server directory. A server directory is a location on a file system that the GIS server is configured to clean up files that it writes. By definition, a server directory can be written to by all container machines.
 
The GIS server hosts and manages server objects and other ArcObjects for use in applications. In many cases, the use of those objects requires writing output to files. For example, when a map server object draws a map, it writes images to disk on the server machine. Other applications may write their own data; for example, an application that checks out data from a geodatabase may write the check-out personal geodatabase to disk on the server.
 
Typically, these files are transient and need only be available to the application for a short time, for example, the time for the application to draw the map or the time required to download the check-out database. As applications do their work and write out data, these files can accumulate quickly. The GIS server will automatically clean up its output if that output is written to a server directory.
 
Files in a server directory can be cleaned up based on file age or when the file was last accessed. The maximum file age or time since last accessed is a property of a server directory. If CleaningMode is esriDCAbsolute, then all files created by the GIS server that are older than the maximum age are automatically cleaned up by the GIS server. If CleaningMode is esriDCSliding, then all files created by the GIS server that have not been accessed for a duration defined by maximum age are automatically cleaned up by the GIS server.
 
When creating files in a server directory, they must be prefixed with "_ags_" to be cleaned up by the GIS server. Any files in a server directory not prefixed with _ags_ will not be cleaned up.
 
The IServerDirectory interface allows you to configure the properties of a server directory to add it to the GIS server. You must set the Path, CleaningMode, and MaxFileAge (if cleaning mode is absolute or sliding) properties for the server directory, which will be the directories’ path on disk. The Description and URL properties are optional.
 
The URL property is the virtual directory that corresponds to the physical directory specified by the Name property. Server objects, such as a map server object, can use the Name property to write their output files to a directory where they will be cleaned up and can pass back to clients the URL for the location of the files they write. Clients (for example, Web applications) will then not require direct access to the physical directory.
 
Use the AddServerDirectory method on IServerObjectAdmin to add the new server directory to your GIS server.
Administer server logging and time-out properties
The Properties property on IServerObjectAdmin returns the properties for the GIS server. The properties are for the GIS server’s logging and for server object creation timeout.
 
The GIS server logs its activity, including server object configuration startup, shutdown, server context creation and shutdown, and errors generated through any failed operation or request in the GIS server.
 
You can control the logging properties through PropertySet returned by Properties. The following is a description of the logging properties:
 
All aspects of logging can be changed when the GIS server is running. When they are changed, the server will immediately use the new logging settings.
 
The following code shows how to use the Properties property on IServerObjectAdmin to modify the logging properties of the GIS server.

[VB.NET] 
Dim pGISServerConnection As IGISServerConnection = New GISServerConnection()
pGISServerConnection.Connect ("melange")

Dim pServerObjectAdmin As IServerObjectAdmin = pGISServerConnection.ServerObjectAdmin
Dim pLogProps As IPropertySet = pServerObjectAdmin.Properties

pLogProps.SetProperty ("LogPath", "c:\ServerLogs")
pLogProps.SetProperty ("LogLevel", 5)

pServerObjectAdmin.Properties = pLogProps
Server object creation can hang for a variety of reasons. To prevent this from adversely affecting the GIS server, it has a ConfigurationStartTimeout property that defines the maximum time in seconds a server object instance has to initialize itself before its creation is cancelled.
 
Get statistics about events in the server
As the GIS server creates and deletes server objects, handles client requests, and so on, statistics about these events are logged in the GIS server’s logs. In addition to the log, statistics are also kept in memory and can be queried using the IServerStatistcs interface. The Statistics tab of the ArcGIS Server Properties dialog box is shown here:
 
 
 
You can query the GIS server for statistics on the following events described by esriServerStatEvent:
 
Value
Description
esriSSEContextCreated A client made a call to CreateServerContext on IServerObjectManager and got a reference to a server context.
esriSSEContextCreationFailed CreateServerContext failed due to an error. Errors will be logged in the GIS server's log files.
esriSSEContextCreationTimeout CreateServerContext timed out because there was no available server objects for the requested configuration for a duration longer than the server object configuration's WaitTimeout.
esriSSEContextReleased A client released the server context by calling ReleaseServerContext. The time measured is the time the client held onto the context (the time between when they called CreateServerContext and received a reference to the server context, and the time they released the server context).
esriSSEContextUsageTimeout A client did not release the server context by calling ReleaseServerContext before the context's server object configuration's UsageTimeout was reached.
esriSSEServerObjectCreated A new server object was created. This can happen when a pooled configuration is started and the object pool is populated, when a server object is recycled, or in response to a call to CreateServerContext. The time measured is the time to create the server object.
esriSSEServerObjectCreationFailed The creation of a new server object instance failed due to an error. Errors will be logged in the GIS server's log files.
 
You can query these events using the statistical functions described by esriServerStatFunction:
 
For esriSSEContextCreationFailed, esriSSEContextCreationTimeout, esriSSEContextUsageTimeout, and esriSSEServerObjectCreationFailed, the only relevant statistical function is esriSSFCount, as these events do not have time associated with them. The other functions reflect the statistics of the elapsed time associated with the event.
 
While the GIS server’s logs maintain a record of all events in the server, the set of statistics that are in memory and can be queried are accumulated summaries of time slices since the GIS server was started. The granularity of these time slices is more coarse the further back in time you go. These statistics can be queried for the following time intervals:
 
Each time period is an accumulated total of the statistics for that time period. For example, if you query the total number of requests to create server contexts for the last 30 days, you would get statistics from now to the beginning of the day 30 days ago (not to the current time on that day). This is because the in-memory statistics have been combined for that entire day.
 
This means that you can get statistics for a longer period that you specified in your query. When you query the GIS server for statistics, you can use the IServerTimeRange interface to get a report of the actual time period that your queries results reflect.
 
The IServerStatistics interface has methods for querying a specific statistical function for an event or for querying all statistical functions for an event.
 
Use the GetSpecificStatisticForTimeIntervals method to query the GIS server for a specific statistic for an event at discrete time intervals. For example, you can use this method to get the count of all server contexts that were created for each minute of the last hour. Use the GetAllStatisticsForTimeInterval to query the GIS server for all statistics for an event. For example, you can use this method to get the sum, mean, and so forth, of server contexts usage time for the last two days.
 
These methods can be used to query based on the events occurring in the server as a whole (i.e., across all machines) or for those occurring on a specific machine. In addition, these methods can be used to query based on the events using all server objects or for events on a particular server object.
 
You specify the time interval for which you want to query using an index of time periods relative to the current time based on the time period described by esriServerTimePeriod. The index argument to the GetSpecificStatisticForTimeIntervals and GetAllStatisticsForTimeInterval methods describe the index of the time period from which to start, and the length argument describes the number of time periods to query. For example, to query for all statistics in the last two hours, specify a time period of esriSTPHour, an index of 0, and a length of 2. To query for all statistics since the server started, specify a time period of esriSTPNone, an index of 0, and a length of 1.
 
If you are unsure of the actual time period that the results of your query reflect, use the IServerTimeRange interface to get a report of the actual time period that your query results reflect.
 
Use the Reset method to clear the statistics in memory.
 
The following code shows how to query the GIS server for statistics on the create context event for all host machines and all configurations since the GIS server was started. It also demonstrates usage of the IServerTimeRange interface to report the actual time the statistics represent.

[VB.NET] 
Dim pGISServerConnection As IGISServerConnection = New GISServerConnection()
pGISServerConnection.Connect ("melange")

Dim pServerStats As IServerStatistics = pGISServerConnection.ServerObjectAdmin
Dim pStatsRes As IStatisticsResults= pServerStats.GetAllStatisticsForTimeInterval(esriServerStatEvent.esriSSEContextCreated, esriServerTimePeriod.esriSTPNone, 0, 1, String.Empty, String.Empty, String.Empty)
Dim pSTR As IServerTimeRange = pStatsRes

Debug.Print (pStatsRes.Count & ": " & pSTR.StartTime & " to " & pSTR.EndTime)
The following code shows the same query but for statistics for only the last two hours.
[VB.NET] 
Dim pGISServerConnection As IGISServerConnection = New GISServerConnection()
pGISServerConnection.Connect ("melange")

Dim pServerStats As IServerStatistics = pGISServerConnection.ServerObjectAdmin

Dim pStatsRes As IStatisticsResults = pServerStats.GetAllStatisticsForTimeInterval(esriServerStatEvent.esriSSEContextCreated, esriServerTimePeriod.esriSTPHour, 0, 2, String.Empty, String.Empty, String.Empty)
Dim pSTR As IServerTimeRange = pStatsRes

Debug.Print (pStatsRes.Count & ": " & pSTR.StartTime & " to " & pSTR.EndTime)
The following code shows the query for statistics since the server started for only the Yellowstone map server object.
[VB.NET] 
D