EDN: ESRI Developer Network
Supported with: ArcGIS Engine, ArcGIS Desktop, ArcGIS Server
Library dependencies: System, SystemUI, Geometry, Display
The Server library contains objects that allow you to connect and work with ArcGIS Servers. Developers gain access to an ArcGIS Server using the GISServerConnection object. The GISServerConnection object gives access to the ServerObjectManager. Using this object a developer works 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 the ArcGIS Server.
The objects that implement this functionality are grouped into a number of library subsystems. These library subsystems are:
To make use of the GIS server to host ArcObjects by your application, the first thing that application must do is connect to the GIS server, i.e. connect to the 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 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 the ServerObjectManager and the ServerObjectAdmin for making use of server objects and administering server objects, respectively.
In order 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 the ServerObjectAdmin. If the user account running the application is not in the agsadmin user group, the ServerObjectAdmin property will return an error.
[VB.NET]
The following code is an example of how to use the GISServerConnection to connect to a GIS server running on a machine "melange" and print out the names and types of the server object configurations configured on the server:
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
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 applications 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 ability for the application to make use of ArcObjects running in the server.
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 when your application connects to the GIS server to use and create server objects. 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 as as ServerObjectExtensionTypeInfo objects, and the SystemInfo property. The SystemInfo property returns a PropertySet containing properties indicating the operating system name and messaeg version of the GIS server.
[C#]
The following C# code shows how you can connect to a GIS Server and get its system info:
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 is already created and running in the server. When you have completed using 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.
[VB.NET]
The following code is an example of how to connect to the GIS server "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:
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()
[VB.NET]
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:
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()
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 actually 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 the 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 do 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:
[VB.NET]
Incorrect:
Dim pPoint as IPoint = New Point()
Correct:
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.
[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 is in the server context. Your application can make use of the proxy as if the object were created locally within its process. If you call a method on the proxy that hands back another object, that object will actually 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.
[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)
Also, 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. Dont directly use the point in the server context as, for example, the geometry of a local graphic element object.
[VB.NET]
Consider the following examples. In each example, assume that objects with Remote in their names are objects in a server context as in:
Dim pRemotePoint as IPoint = pServerContext.CreateObject("esriGeometry.Point")
while objects with Local in their name are objects created locally as in:
Dim pLocalPoint as IPoint = New Point()
You cant set a local object to a remote object:
' 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:
' this is incorrect Set pLocalPoint = pRemotePointCollection.Point(0)
When calling a method on a remote object, dont pass in local objects as parameters:
' this is incorrect Set pRemoteWorkspace = pRemoteWorkspaceFactory.Open(pLocalPropertySet,0)
You can get simple data types (double, long, string, etc.) that are passed by value from a remote object and use them as properties of a local object as in:
' this is OK 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 as a convenient place to store objects that you create within the context. Note that this dictionary is itself 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.
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.
[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 have been set using SetObject. Once an object is removed, a reference can no longer be made to it using GetObject. Note that if you do not explicitly call Remove or RemoveAll, you can still not get references to objects set in the context after the context has been released.
[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, then you want to draw the point that GeocodeAddress returns on your map, you need to copy the point into your MapServer's context.
[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 Map's server context
Dim sPoint As String = pServerContext2.SaveObject(pPoint)
Dim pPointCopy As IPoint = pServerContext.LoadObject(sPoint)
This diagram illustrates the use of SaveObject and LoadObject to copy objects between server contexts:
Another important use of these methods is to manage state in your application while making stateless use of a pooled server object. A good 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 users session state. The application does this by saving a serialized map description as part of each users 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 sessions 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 users specifications.
A ServerObject is a coarse-grained ArcObjects component, that is a high-level object that simplifies the programming model for doing 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 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 (see above).
Because server objects are COM objects, they and their extensions can be used in ArcGIS Engine or ArcGIS Desktop applications. The 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.
[C#]
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.
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 "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 interface for interfaces supported by the server object type, such as IMapServer for a MapServer object, or IGeocodeServer for a GeocodeServer object.
[VB.NET]
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:
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 objects may also 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 inteded 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 developers can extend ArcGIS Server by writing their own server object extensions. For more information about writing your own server object extensions, see the Server Object Extension Objects section later in this document.
Server objects 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 for 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 name (FindExtensionByName) or by CLSID (FindExtensionByCLSID). Once you have a reference to the server object extension, you can QI for any of its interfaces.
[VB.NET]
The following VB.NET code shows how to get the nework analysis extension to a MapServer and find the network analysis layers in the map:
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 Server object librarys Info classes provide read-only access to users and developers who are not administrators to the properties of server directories, server types, and server object configurations. These properties are those that 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 based on file age, or based on 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 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 the 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.
Note that 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 readonly access to a subset of the server directory's properties. These properties include:
The properties listed above are those necessary for developers of server applications to make use of the various GIS servers server directories.
[VB.NET]
The following code shows how to list the server directories of a GIS server using the ServerDirectoryInfo class:
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. Note that the GetConfigurationInfos method returns only server object configurations that are started.
IServerObjectConfigurationInfo provides readonly access to a subset of the server object configuration's properties. These properties include:
The properties listed above are those necessary for developers of server applications to make use of the various server objects configured on the GIS server.
[VB.NET]
The following 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:
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
ServerObjectConfigurationInfo2 extends this interface to provide the names of all enabled server object extensions for a particular configuration. Note that 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 with them. You can get information about server object types using the GetTypeInfos method on IServerObjectManager to get the IServerObjectTypeInfo interface.
IServerObjectTypeInfo provides readonly access to a subset of the server object type's properties. These properties include:
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 with them. You can get information about server object extension types using the GetExtensionTypeInfos method on IServerObjectManager2 to get the IServerObjectExtensionTypeInfo interface.
IServerObjectExtensionTypeInfo provides readonly access to a subset of the server object extension type's properties. These properties include:
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 the user your application runs as is a member of 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 provide the ability for the application to administrate the GIS server and its server objects.
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 the 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 the ServerObjectManager.
Use ServerObjectAdmin to administrate both 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 servers set of server object configurations and server object types and to administrate 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.
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.
[VB.NET]
The following code shows how to connect to the GIS server called "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:
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.
Note that the server object configuration must be stopped before you call UpdateConfiguration. You can use StopConfiguration to stop the server object configuration.
[VB.NET]
The following code shows how to connect to the GIS server called melange and use GetConfiguration to get a ServerObjectConfiguration, change its MinInstances property, then update the configuration using the UpdateConfiguration method:
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. Note, in order to call DeleteConfiguration, the server object configuration must be stopped. If it is not stopped, then DeleteConfiguration will return an error.
[VB.NET]
The following code shows how to stop, then delete a server object configuration called RedlandsMap:
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 named 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. Disbaling 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 status of server object configurations and server machines. The GetConfigurationStatus method returns a ConfigurationStatus object which 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 runnning on the machine (InstanceCount) and the number currently in use (InstanceInUseCount).
The SOMController class allows you to actually start and stop the GIS server. Use the methods on ISOMController to check to see if the server is running, and 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:
A read-only subset of properties of a ServerObjectConfiguration are available to nonadministrators via the GISServerConnectionInfo object. These nonadministrator level properties are:
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 configurations properties, you must call UpdateConfiguration on IServerObjectAdmin for those changes to be reflected in the server.
[VB.NET]
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:
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.
Server objects can be either pooled or non-pooled. Pooled server objects can be shared across multiple sessions and applications and are held on to 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 on to 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, the MaxInstances represents the maximum simultaneous requests that can be processed by the server object configuration. For a non-pooled server object, the 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, etc.
Name is case sensitive and can have a maximum of 120 characters. Names can contain only the following characters:
AZ
az
09
_ (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 an 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.
You 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.
[VB.NET]
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.
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 for 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 may incorrectly modify a server objects state, or an application may incorrectly hold a reference to a server object, making it unavailable to other applications or sessions. In some cases, a server object may 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 RecyclingProperties property on the server object configuration. The RecyclingProperties property returns an 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:
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 clients wait time exceeds the maximum wait time for a server object, then 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 dont hold references to server objects for too long (e.g., they dont 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 onto a server object longer than the maximum usage time, then the server object is automatically released and the client will lose the reference to the server object.
The UsageTimeout 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 are available via IServerObjectManager2::GetExtensionTypeInfos.
Use the ExtensionProperties property to specify the collection of properties for a server object extension. For more information on server object extension properties, see the Server Object Extension Objects section later in this document.
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 timout properties for a server object:
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 on it, 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.
[VB.NET]
The following code shows how to use the CreateMachine and AddMachine methods to add a machine to your GIS server:
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 servers other host machines.
The ServerMachine class is used to define a machine that can host server objects managed by the GIS server.
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 on it, and the machine must be added to the list of host machines managed by the Server Object Manager.
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 configuration instances on a SOC machine that are allowed to run concurrently before the pool-shrinking algorithm engages. The pool-shrinking algorithm removes 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.
[VB.NET]
The following code shows how to use the IServerMachine interface and AddMachine method to add a machine to your GIS server:
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)
You can use IServerObjectAdmin to add and remove server directories from the GIS server. Both 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 objects 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 it 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.
Note: Server directories must be accessible by all host machines configured in the GIS server.
[VB.NET]
The following code shows how to use the CreateServerDirectory and AddServerDirectory methods to add a directory to your GIS server:
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.
The UpdateServerDirectory is useful for modifying the cleanup mode (CleaningMode) and cleanup schedule.
[VB.NET]
The following code shows how to connect to the GIS server called melange and use the GetServerDirectory method to get a ServerDirectory, change its MaxFileAge property, then update the directory using the UpdateServerDirectory method:
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 based on file age or based on 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 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 the 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.
Note that when creating files in a server directory, they must be prefixed with "_ags_" in order 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.
The Properties property on IServerObjectAdmin returns the properties for the GIS server. The properties are for the GIS servers 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 the PropertySet returned by Properties. The following is a description of the logging properties:
0 (None): No logging
1 (Error): Serious problems that require immediate attention
2 (Warning): Problems that require attention
3 (Normal): Common administrative messages of the server
4 (Detailed): Common messages from user use of the server, including server objects
5 (Debug): verbose messages to aid in troubleshooting
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.
[VB.NET]
The following example shows how to use the Properties property on IServerObjectAdmin to modify the logging properties of the GIS server:
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 may 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.
As the GIS server creates and destroys server objects, handles client requests and so on, statistics about these events are logged in the GIS servers logs. In addition to the log, statistics are also kept in memory and can be queried using the IServerStatistcs interface.
ArcCatalog provides administrators with a user interface for querying the GIS servers statistics.
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 we 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 receives a reference to the server context, and the time they release 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:
Note: 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 servers logs maintain a record of all events in the server, the set of statistics that are in memory and that 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 may actually 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, etc., 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 to start from, 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.
[VB.NET]
The following code shows how to query the GIS server for statistics on the create context event for all host machines all configurations since the GIS server was started. It also demonstrates the usage of the IServerTimeRange interface to report the actual time the statistics represent:
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:
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 obect:
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, "Yellowstone", "MapServer", String.Empty)
Dim pSTR As IServerTimeRange = pStatsRes
Debug.Print (pStatsRes.Count & ": " & pSTR.StartTime & " to " & pSTR.EndTime)
The following code shows the query for the count of server contexts created for each minute in the last 60 minutes for all host machines and all server objects:
Dim pGISServerConnection As IGISServerConnection = New GISServerConnection()
pGISServerConnection.Connect ("melange")
Dim pServerStats As IServerStatistics = pGISServerConnection.ServerObjectAdmin
Dim dr As IDoubleArray = pServerStats.GetSpecificStatisticForTimeIntervals(esriServerStatEvent.esriSSEContextCreated, esriServerStatFunction.esriSSFCount, esriServerTimePeriod.esriSTPMinute, 0, 60, String.Empty, String.Empty, String.Empty)
Dim i as Integer
For i = 0 To dr.Count - 1
Debug.Print (dr.Element(i))
Next i
Developers can create their own server object extensions. The goal of creating a server object extension is to provide coarse-grained methods that do a lot of work in the server, rather than pay the cost of making a large number of calls into the server from the client.
Extending a server object over creating a generic COM object has the following
advantages:
Unlike utility COM objects, server object extensions are reigstered and configured with speficic server objects and are not for add-hoc use or use with an empty server context.
The process for creating a server object extensions is the following:
A server object extension is a COM object developeed in .NET or C++ that implements IServerObjectExtension and any additional interfaces necessary for its implementation.
IServerObjectExtension is a mandatory interface that must be supported by all server object extensions, and includes two methods: Init and Shutdown. This interface is used by the server object to manage the lifetime of the server object extension. The server object cocreates the server object extension and calls the Init method handing it a back reference to the server object via the server object helper argument. The server object helper implements a weak reference on the server object. The extension can keep a strong reference on the server object helper (for example, in a member variable) but should not keep a strong reference on the server object. Extensions should get the server object from the server object helper in order to make any method calls on the server object and release the reference after making the method calls. Init is called once when the instance of the server object extension is created.
The Shutdown method informs the server object extension that the server objects context is being shutdown and is about to go away. In response the server object extension should release its reference on the server object helper:
private IServerObjectHelper m_SOH;
public void Init(IServerObjectHelper pSOH)
{
m_SOH = pSOH;
}
public void Shutdown()
{
m_SOH = null;
}
In your custom methods, you use the server object helper to get a reference to the server object, for example:
IMapServer mapsrv = m_SOH.ServerObject as IMapServer;
If your server object extension includes configuration properties or requires any additional intitializtion logic, you need to implement IObjectConstruct. IObjectConstruct is an optional interface for server object extensions. The interface includes a single method called Construct. Construct is called once when the server object extension is created after IServerObjectExtension::Init is called. Construct hands back the configuration properties for the server object extension as a property set. You should include any expensive initialization logic within your implementation of Construct.
While IServerObjectExtension::Init and IObjectConstruct::Construct are called once when the instance of the server object extension is created, if your server object extension requires logic to run each time its server context is aquired and released (each time a client calls CreateServerContext and ReleaseContext), you need to implement IObjectActivate. IObjectActivate is an optional interface for server object extensions that includes two methods: Activate and Deactivate. Activate is called each time a client calls CreateServerContext on the server object extensions server objects context, and Deactivate is called each time a client releases the context (via ReleaseContext). Because Activate and Deactivate are called each time a client gets and releases the server objects context, any logic you implement in these methods should not be expensive.
Finally, if you want your server object extension to log messages to the GIS servers log file, your server object extension should implement ILogSupport. ILogSupport is an optional interface for server object extensions that has a single InitLogging method. InitLogging is called when the server object extension is created hands back a reference to the GIS servers log object via the log argument. The extension can keep a reference on the server log (for example, in a member variable):
private ILog m_log;
public void InitLogging(ILog log)
{
m_log = log;
}
Since this method is called before IServerObjectExtension::Init and IObjectConstruct::Construct, you can use the log to log messages and errors in initialization, as well as your custom methods:
m_log.AddMessage(3,8000,"This is a normal level log message."); m_log.AddMessage(1,8000,"This is an error level log message.");
The following diaram illustrates the order in which the methods described above are called:
In some cases, your server object extension may require properties be set at the time the server object extension is configured by the server administrator. To display a form in the Create Server Object wizard in ArcCatalog, and the server object properties page, you can optionally create a COM object that implements IAGSSOEParameterPage and ICOMPropertyPage that includes a user form that encapsulates any initialization properties that must be configured for the extension.
The ICOMPropertyPage interface must be implmented for any property page created for an ArcGIS desktop application. Server object extension property pages must also implement the IAGSSOEParamaterPage interface. IAGSSOEParamaterPage includes a property for getting and setting the properties for the server object extension (ExtensionProperties), and a property for getting the properties of the server object that is being extended (ServerObjectProperties). The ICOMPropertyPage:Show method will show your form on the create server object wizard. Note that the property page COM object must be registered in the AGS Extension Parameter Pages component category on the machine on which ArcCatalog is running.
The following is an example of a server object extension property page that would be displayed in ArcCatalog when configuring the server object extension by createing a COM object that implements IAGSSOEParameterPage and ICOMPropertyPage. The property page will appear on the server object extensions pane of the Add Server Object wizard, and the ServerObject Properties dailog:
The server object extension is registered with ArcGIS Server by doing the following:
The following code shows how you register the server object extension with ArcGIS Server:
IGISServerConnection conn = new GISServerConnectionClass();
conn.Connect("your_server");
IServerObjectAdmin2 soa = conn.ServerObjectAdmin as IServerObjectAdmin2;
IServerObjectExtensionType soet = soa.CreateExtensionType();
soet.CLSID = "vegSOE.vegUtilSOE";
soet.Description = "test server obj extension";
soet.Name = "VegUtilitiesExtension";
soa.AddExtensionType("MapServer",soet);
This should be included in a setup program for distributing your custom server object extensions.
Once you have registered your server object extension with ArcGIS Server, you can create new server object configurations that include your extension either using ArcCatalog (via your server object extension property page (see the example above), or through code.
The following code shows how you can create a new server object configuration with your extension. Note that when you create a server object configuration of a particular type (e.g. MapServer), its configuration includes all extension types which are by default disabled. In this example, the server object extension desribed above is enabled for the Yellowstone MapServer, and the name of the layer to query is veg:
IServerObjectAdmin = soa = pServerConn.ServerObjectAdmin IServerObjectConfiguration2 soc = soa.GetConfiguration(Yellowstone,MapServer) as IServerObjectConfiguration2; soa.StopConfiguration(Yellowstone,MapServer); soc.ExtensionEnabled(AreaSumExtension) = true; IPropertySet props = soc.ExtensionProperties(AreaSumExtension); props.SetProperty(LayerName,Veg); soa.UpdateConfiguration(); soa.StartConfiguration(Yellowstone,MapServer);
Once a server object is running in the server that includes your extension, you can write applications that make use of your extensions functionality.
Refer above to the discussion above on consuming server object and server object extensions (Server Consumer Objects).