Connecting to a GIS server

Summary

To use ArcObjects in your application via ArcGIS for Server, you must connect directly to the geographic information system (GIS) server, which requires network access to the Server Object Manager (SOM).

Local (DCOM) connections are only supported for ArcGIS Server versions prior to 10.1.

ArcGIS Server Connection objects

To connect to a GIS server, use the following ArcGIS Connection libraries:

ESRI.ArcGIS.ADF.Core
ESRI.ArcGIS.ADF.Local
ESRI.ArcGIS.ADF.Connection.Core
ESRI.ArcGIS.ADF.Connection.Local

The Connection libraries are native .NET assemblies that enable you to connect to the GIS server through the AGSServerConnection class as shown in the following code example:

[C#]


        ESRI.ArcGIS.ADF.Identity identity = new ESRI.ArcGIS.ADF.Identity("user", "passwd", 
    "domain");
ESRI.ArcGIS.ADF.Connection.AGS.AGSServerConnection agsconnection;
agsconnection = new ESRI.ArcGIS.ADF.Connection.AGS.AGSServerConnection("hostname",
    identity);
agsconnection.Connect();
IServerObjectManager SOM = agsconnection.ServerObjectManager;

[VB.NET]


        Dim identity As ESRI.ArcGIS.ADF.Identity = New ESRI.ArcGIS.ADF.Identity("user", "passwd", "domain")
Dim agsconnection As ESRI.ArcGIS.ADF.Connection.AGS.AGSServerConnection
agsconnection = New ESRI.ArcGIS.ADF.Connection.AGS.AGSServerConnection("hostname", identity)
agsconnection.Connect
Dim SOM As IServerObjectManager = agsconnection.ServerObjectManager

The Connection libraries also contain a ConnectionManager class to manage fail-over and round-robin capabilities within the client. For more information, see the Using connection library topic in the ArcGIS Server Application Developer Framework (ADF) Help system, in Creating ArcGIS Server solutions, Developing Web applications using the Web ADF, Using the connection library.

Security

To connect a client application to ArcGIS Server, the application must be running as an operating system user that is a member of one of the following two operating system user groups defined on the ArcGIS Server machines—ArcGIS Server users group (agsusers) or ArcGIS Server administrators group (agsadmin) as shown in the following illustration.

If the user the application is running as is not a member of either group, Connect returns an error.

Illustration of the agsusers and agsadmin user groups.

In addition to the Connect method, the IGISServerConnection interface has the following two properties:

ServerObjectManager
ServerObjectAdmin

If the application is running as a user in the users or administrators group, the application can access the ServerObjectManager property, which returns the IServerObjectManager interface. The IServerObjectManager interface provides methods for accessing and creating objects within the server for use by applications.

The IServerObjectManager interface is described in the following illustration:

Illustration showing descriptions for the IServerObjectManager interface.

To access the ServerObjectAdmin property, the application must be running as a user who is a member of the administrators group. If the connected user is not a member of this group, attempts to access the ServerObjectAdmin property fail. The ServerObjectAdmin property returns the IServerObjectAdmin interface, which provides methods for administering the various aspects of the server, such as server object configurations and server machines. Unless you are writing a GIS server administration application, your application does not need to use the IServerObjectAdmin interface.

The ServerObjectManager object provides methods for getting information about the GIS server and for creating server contexts for use by an application. This object is shown in the following illustration:

The ServerObjectAdmin object provides methods for administrating the GIS server and its server objects. This object is shown in the following illustration:

The IServerObjectAdmin interface is described in the following illustration:

Illustration showing descriptions of the IServerObjectAdmin interface.

When connecting to the server using the native .NET connection object from a Web application or Web service, you must consider impersonation. Your Web application or Web service must connect to the GIS server as a user in the agsusers group. The identity of the process or thread determines the account you used to access the GIS server. Process identity is associated with the user account under which a process is running. For ASP.NET Web applications or Web services, you can impersonate a user at runtime by adding the identity tag to the web.config file and defining the appropriate attributes as shown in the following code example:

[XML]


        <identity impersonate="true" userName="mydomain\myuser" password="mypassword"/>

If you do not use impersonation in an ASP.NET application, the application attempts to connect to the GIS server using the identity of the ASP.NET worker process, which can be ASPNET or NETWORK SERVICE, depending on the platform and machine settings.

Thread level impersonation is provided via the Connection library previously discussed. An Identity object is created with account credentials of a user in the agsusers group on the GIS server. When the AGSServerConnection is instantiated, it is provided the Identity object as a constructor parameter. The identity is used for the duration of the connection, which can involve concurrent access from multiple threads in the same process. The following code example shows how a multi-threaded application creates concurrent connections to one or more GIS servers using different identities:

[C#]


        public partial class _Default: System.Web.UI.Page
{
    private UserThread m_thread;

    protected void Button1_Click(object sender, EventArgs e)
    {
        m_thread = new UserThread();
        Thread t = new Thread(new ThreadStart(m_thread.Connection1));
        t.Start();
        Thread t2 = new Thread(new ThreadStart(m_thread.Connection2));
        t2.Start();
    }
}

public class UserThread
{
    public void Connection1()
    {
        ESRI.ArcGIS.ADF.Identity id = new ESRI.ArcGIS.ADF.Identity("user1", "pass1",
            "domain1");
        ESRI.ArcGIS.ADF.Connection.AGS.AGSServerConnection agsconn;
        agsconn = new ESRI.ArcGIS.ADF.Connection.AGS.AGSServerConnection("server1",
            id);
        agsconn.Connect();
        if (!agsconn.IsConnected)
        {
            agsconn.Dispose();
            return ;
        }
        ESRI.ArcGIS.Server.IServerObjectManager som = agsconn.ServerObjectManager;
        string servertype = "MapServer";
        string serverobjectname = "Canada";
        ESRI.ArcGIS.Server.IServerContext servercontext = som.CreateServerContext
            (serverobjectname, servertype);
        IMapServer ms = (IMapServer)servercontext.ServerObject;

        System.Threading.Thread.Sleep(10000);

        servercontext.ReleaseContext();
        agsconn.Dispose();
    }

    public void Connection2()
    {
        ESRI.ArcGIS.ADF.Identity id = new ESRI.ArcGIS.ADF.Identity("user2", "pass2",
            "domain2");
        ESRI.ArcGIS.ADF.Connection.AGS.AGSServerConnection agsconn;
        agsconn = new ESRI.ArcGIS.ADF.Connection.AGS.AGSServerConnection("server2",
            id);
        agsconn.Connect();
        if (!agsconn.IsConnected)
        {
            agsconn.Dispose();
            return ;
        }
        ESRI.ArcGIS.Server.IServerObjectManager som = agsconn.ServerObjectManager;
        string servertype = "MapServer";
        string serverobjectname = "USA";
        ESRI.ArcGIS.Server.IServerContext servercontext = som.CreateServerContext
            (serverobjectname, servertype);
        IMapServer ms = (IMapServer)servercontext.ServerObject;

        servercontext.ReleaseContext();
        agsconn.Dispose();
    }
}

[VB.NET]


        Partial Public Class _Default
Inherits System.Web.UI.Page
Private m_thread As UserThread
Protected Sub Button1_Click(ByVal sender As Object, ByVal e As EventArgs)
m_thread = New UserThread()
Dim t As New Thread(New ThreadStart(AddressOf m_thread.Connection1))
t.Start()
Dim t2 As New Thread(New ThreadStart(AddressOf m_thread.Connection2))
t2.Start()
End Sub

End Class


Public Class UserThread

    Public Sub Connection1()
        Dim id As New ESRI.ArcGIS.ADF.Identity("user1", "pass1", "domain1")
        Dim agsconn As ESRI.ArcGIS.ADF.Connection.AGS.AGSServerConnection
        agsconn = New ESRI.ArcGIS.ADF.Connection.AGS.AGSServerConnection("server1", id)
        agsconn.Connect()
        If (Not agsconn.IsConnected) Then
            agsconn.Dispose()
            Return
        End If
        Dim som As ESRI.ArcGIS.Server.IServerObjectManager = agsconn.ServerObjectManager
        Dim servertype As String = "MapServer"
        Dim serverobjectname As String = "Canada"
        Dim servercontext As ESRI.ArcGIS.Server.IServerContext = som.CreateServerContext(serverobjectname, servertype)
        Dim ms As IMapServer = CType(servercontext.ServerObject, IMapServer)
        System.Threading.Thread.Sleep(10000)
        servercontext.ReleaseContext()
        agsconn.Dispose()
    End Sub


    Public Sub Connection2()
        Dim id As New ESRI.ArcGIS.ADF.Identity("user2", "pass2", "domain2")
        Dim agsconn As ESRI.ArcGIS.ADF.Connection.AGS.AGSServerConnection
        agsconn = New ESRI.ArcGIS.ADF.Connection.AGS.AGSServerConnection("server2", id)
        agsconn.Connect()
        If (Not agsconn.IsConnected) Then
            agsconn.Dispose()
            Return
        End If
        Dim som As ESRI.ArcGIS.Server.IServerObjectManager = agsconn.ServerObjectManager
        Dim servertype As String = "MapServer"
        Dim serverobjectname As String = "USA"
        Dim servercontext As ESRI.ArcGIS.Server.IServerContext = som.CreateServerContext(serverobjectname, servertype)
        Dim ms As IMapServer = CType(servercontext.ServerObject, IMapServer)
        servercontext.ReleaseContext()
        agsconn.Dispose()
    End Sub

End Class