ArcObjects Library Reference (Carto)  

IMapServer2.Identify Method

Returns a collection of Map Server Identify Result objects at the given location. If LayerIDs is Nothing/Null or empty, all layers are searched.

[Visual Basic .NET]
Public Function Identify ( _
    ByVal mapDesc As IMapDescription, _
    ByVal MapImage As IImageDisplay, _
    ByVal searchShape As IGeometry, _
    ByVal Tolerance As Integer, _
    ByVal option As esriIdentifyOption, _
    ByVal layerIds As ILongArray _
) As IMapServerIdentifyResults
[C#]
public IMapServerIdentifyResults Identify (
    IMapDescription mapDesc,
    IImageDisplay MapImage,
    IGeometry searchShape,
    int Tolerance,
    esriIdentifyOption option,
    ILongArray layerIds
);
[C++]
HRESULT Identify(
  IMapDescription* mapDesc,
  IImageDisplay* MapImage,
  IGeometry* searchShape,
  long Tolerance,
  esriIdentifyOption option,
  ILongArray* layerIds,
  IMapServerIdentifyResults** identifyResult
);
[C++]

Parameters

mapDesc [in]

  mapDesc is a parameter of type IMapDescription

MapImage [in]

  MapImage is a parameter of type IImageDisplay

searchShape [in]

  searchShape is a parameter of type IGeometry

Tolerance [in]
  Tolerance is a parameter of type long
option [in]

  option is a parameter of type esriIdentifyOption

layerIds [in]

  layerIds is a parameter of type ILongArray

identifyResult [out, retval]

  identifyResult is a parameter of type IMapServerIdentifyResults

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Remarks

Identify returns map features and their attribute values based on a search location. This can be conducted on an individual layer, the top-most layer, all layers, or just on all the visible layers. This method returns a collection of objects that implement IMapServerIdentifyResult.

Identify requires a number of input parameters. These include: a MapDescription, an ImageDisplay, a search shape, a tolerance, the esriIdentifyOption, and an array of layer Ids to be identified. Please note that it does not work with StandaloneTable.

Time aware layer

Identify recognizes time settings of a layer. When a layer's UseTime is true and MapDescription's TimeValue is set, Identify only searches features that fall within the time frame.

Layer with HTMLPopup

Identify can return results additionally in rich html format. When a layer's HTMLPopupType is not esriServerHTMLPopupTypeNone, you can use one of identify two htmlpopup options to get identify result in html format the way it is authored.

MapDescription

The MapDescription contains all the LayerDescriptions in the map. These LayerDescriptions include a DefinitionExpression property. A DefinitionExpression can be set on a layer in order to limit layer features available for display or query. This expression can be set in the source map document as a definition query, or can be set using the DefinitionExpression property. The DefinitionExpression set in the LayerDescription will override any any definition query set in the source map. MapServer Identify results should honor any definition query or DefinitionExpression set on the layer.

ImageDisplay

This is needed to determine whether layers are visible or not based on the current map scale.

SearchShape 

Geometry set in ISpatialFilter should meet the following criteria:

Tolerance

Tolerance is the distance in which features are searched. The unit is in pixel. It is only used for when SearchShape is a point.

esriIdentifyOption

The esriIdentifyOption parameter includes: esriIdentifyAllLayers, esriIdentifyVisibleLayers and esriIdentifyTopmost. If esriIdentifyAllLayers is being used all features for all layers in the map that fall within the tolerance value of the searchShape will be returned. If esriIdentifyVisibleLayers is used then only features from visible layers are returned. Layer visibility depends on whether the layer is on or off (the Visible property on ILayerDescription3) or whether the layer is on, but not visible due to scale dependencies (the MinScale and MaxScale properties on IMapLayerInfo2). The mapImage parameter is needed to determine whether the layer is not visible based on scale dependencies. The esriIdentifyOption esriIdentifyTopmost refers to the visible layer that is topmost in the map drawing order at the location specified by searchShape.

Layer IDs

The parameters esriIdentifyOption and LayerIDs behave like a boolean AND. There is no precedence. For example: if esriIdentifyOption is esriIdentifyVisibleLayers and pLayerIDs is Nothing/Null or empty, all the visible layers are searched. If esriIdentifyOption is esriIdentifyVisibleLayers and pLayerIDs contains only the first layer, the first layer is searched only if it is visible.

Results

Identify always honors field visibility, and by default it respects field aliases and field formatting set in the source map document. If you want to use field names instead of field aliases, set ReturnFieldNamesInResults to True. When you want to have value in original data type (i.e. as Double instead of formatted string) so that you can do some computation (e.g. change the numeric or date to your locale settings), set FormatValuesInResults to False. It is important to note that these properties are only honored when the layer being identified implements IFeatureLayer  (e.g. FeatureLayer).

Geometry is always returned in the same spatial reference system as the DefaultMapDescription, even though the source data of a layer may be in a different coordinate system. The value of the Shape field in the IMapServerIdentifyResult::PropetySet or in related IMapServerRow::PropertySet is a string showing the type of the geometry. To get the geometry associated with the result, use the IMapServerIdentifyResult::Shape property instead. Identify does not return geometry associated with any related feature. If the feature being identified has more than one field with the same name, only one will be passed back to the client and the rest will be dropped from the result.

In some cases, for performance reason, you may want limit or adjust the geometry being returned in the identify result. Use ILayerResultOptions to manage this. If IncludeGeometry is set to False, Shape property returns nothing. This should increase performance in cases where feature geometry is large. When ILayerResultOptions is not used, the Shape property returns geometry. If the Shape field is invisible in the source map, the Shape property may still contain geometry depending on how IncludeGeometry is set by the user. You can also choose to densify or generalize the returned geometry by using GeometryResultOptions. Densification is used to better support clients that do not support Arcs (e.g. Bezier, Circular etc.). Generalization reduces the amount of geography being sent across the network and should lead to better performance.

Miscellaneous

In order to control the amount of information MapServer needs to process for a query, a maximum number of records can be set. This value is contained in the MaxRecordCount property on IMapServerInit2. The default value for this property is 1000. If 1,100 features match a given query only the first 1,000 results will be returned. You will be unable to access the remaining 100 records. To be able to access these records the MaxRecordCount would need to be increased to 1,100. MaxRecordCount can also be changed by modifying the MaxRecordCount XML tag in the MapServer's configuration file.

If the layer being identified has a relationship to other tables, the IMapServerRelationship and IMapServerRow interfaces provide access to properties of the relationship and related tables. The number of rows returned is not limited by MaxRecordCount.

[C#]

It assumes that you already have a valid ServerContext, MapServer, MapDescription and ImageDisplay objects and that you are working with a server context. However, if you are not developing an ArcGIS Server application using a server context, you should use New to create local ArcObjects instead of using CreateObject on IServerContext.

// Search point
IPoint pSearchPnt = pServerContext.CreateObject("esriGeometry.Point") as IPoint;
pSearchPnt.SpatialReference = pMapDescription.SpatialReference;
pSearchPnt.X = 194000;
pSearchPnt.Y = 4700000;

/*
setting LayerResultOptions to generalize the resultant geometry
*/
//creating GeometryLayerOptions in the server context
IGeometryResultOptions pGeomResultOptions = pServerContext.CreateObject("esriGeodatabase.GeometryResultOptions") as IGeometryResultOptions;
pGeomResultOptions.GeneralizeGeometries = true;
pGeomResultOptions.MaximumAllowableOffset = 2000;

//creating LayerResultOptions the server context
ILayerResultOptions pLayerResultOptions = pServerContext.CreateObject("esriCarto.LayerResultOptions") as ILayerResultOptions;
pLayerResultOptions.IncludeGeometry = true;
pLayerResultOptions.GeometryResultOptions = pGeomResultOptions;

//executing Identify function
IMapServerIdentifyResults pIDResults = pMapServer.Identify(pMapDescription, pImageDisplay, pSearchPnt, 3, esriIdentifyOption.esriIdentifyAllLayers, null);

System.Object O1; System.Object O2; // two dummy objects
System.Array pFieldNameArray; System.Array pValueArray;

for (int i = 0; i < pIDResults.Count; i++)  // looping thru all results
{
IMapServerIdentifyResult pIDResult = pIDResults.get_Element(i);
Debug.Print("Primary value: " + pIDResult.Name + "(LayerID: " + pIDResult.LayerID.ToString() + ")");
Debug.Print(pIDResult.Properties.Count.ToString());


pIDResult.Properties.GetAllProperties(out O1, out O2); // getting all fields & values for a feature
pFieldNameArray = (System.Array)O1;
pValueArray = (System.Array)O2;
for (int i = 0; i < pIDResults.Count; i++)  // looping thru all results
{
    IMapServerIdentifyResult pIDResult = pIDResults.get_Element(i);
    Debug.Print("Primary value: " + pIDResult.Name + "(LayerID: " + pIDResult.LayerID.ToString() + ")");
    Debug.Print(pIDResult.Properties.Count.ToString());


    pIDResult.Properties.GetAllProperties(out O1, out O2); // getting all fields & values for a feature
    pFieldNameArray = (System.Array)O1;
    pValueArray = (System.Array)O2;
    for (int j = 0; j < pFieldNameArray.Length; j++) //printing field names & values
    {
        Debug.Print(pFieldNameArray.GetValue(j) + ": " + "\t" + pValueArray.GetValue(j).ToString());
    }


    //checking whether it has any related records
    IMapServerRelationships pRelates = pIDResult.RelatedRows;
    if (pRelates != null)
    {
        for (int k = 0; k < pRelates.Count; k++)
        {
            IMapServerRelationship pRelate = pRelates.get_Element(k);
            //printing the relationship class name
            Debug.Print("\tRelationship: " + pRelate.Name);
            IMapServerRows pRelatedRows = pRelate.Rows;
            if (pRelatedRows != null)
            {
                //looping through each related rows
                for (int l = 0; l < pRelatedRows.Count; l++)
                {
                    IMapServerRow pRelatedRow = pRelatedRows.get_Element(l);
                    if (pRelatedRow != null)
                    {
                        Debug.Print("\t++Related Record for: " + pRelatedRows.get_Element(l).Name);
                        pRelatedRow.PropertySet.GetAllProperties(out O1, out O2);
                        pFieldNameArray = (System.Array)O1;
                        pValueArray = (System.Array)O2;
                        //printing fieldnames & values for each related row
                        for (int m = 0; m < pFieldNameArray.Length; m++)
                        {
                            Debug.Print("\t  " + pFieldNameArray.GetValue(m) + ": \t" + pValueArray.GetValue(m).ToString());
                        } // end of printing all field-value pairs
                    } // end of making sure the row is valid
                } // end of looping all rows
            } // end of checking the relationship has rows
        } // end of looping all relationship
    } // checking whether the result has any related record
    Debug.Print("--------------------------");
} // end of looping all results

See Also

IMapServer2 Interface