ArcGIS Runtime API for .NET——查询和编辑

ArcGIS Runtime API for .NET——查询和编辑

查询
  查询提供了基于属性，空间和时间标准的任意组合从数据集中返回要素子集的功能。为了定义属性标准，可以使用一个复合SQL表达式，该表达式使用多个属性字段，数据类型和运算符（例如，“ POP> 1000000 AND NAME LIKE’San％’”）。
  查询不需要定义所有类型的条件（属性，空间和时间）。例如，保留未定义的空间和时间过滤器意味着不会使用这些标准来限制搜索（换句话说，将评估整个空间和时间范围）。
  还可以执行查询以返回相关要素，要素计数，包含符合条件的所有要素的范围或有关数据集的统计信息。

编辑
  通过使用编辑API，可以对编辑操作进行精细控制，从而允许创建和编辑要素，添加，编辑或删除要素附件以及编辑要素的几何形状。
  支持多种编辑工作流程，包括已连接和已断开（离线）编辑。

一.查询

  查询提供了基于属性，空间和时间（时间）标准的任意组合从数据集中返回要素子集的功能。
（1）基于可用的属性字段，使用标准SQL表达式定义属性条件。
（2）空间标准使用几何形状和空间关系（在内部，包含，相交等）。
（3）可以使用单个日期或时间或范围来定义时间过滤器。
  还可以执行查询以返回相关要素，要素计数，包含符合条件的所有要素的范围或有关数据集的统计信息。

注意：
  本主题描述了查询数据集（功能表）以返回结果中的功能子集（或摘要）。 ArcGIS Runtime还提供查询以查找门户（例如ArcGIS Online）中的项目，用户或组。

1.API参考中的相关类和成员

QueryParameters：定义查询的属性，空间和时间标准。 它还具有控制结果返回方式的属性。
FeatureTable.QueryFeaturesAsync()：使用QueryParameters中定义的条件和首选项返回一组结果。
FeatureTable.QueryFeatureCountAsync()：使用QueryParameters返回满足查询条件的特征的数量。
FeatureTable.QueryExtentAsync()：使用QueryParameters返回满足查询条件的要素的地理范围。
FeatureTable.QueryStatisticsAsync()：使用StatisticsQueryParameters返回描述数据集中特征的请求统计信息。
ArcGISFeatureTable.QueryRelatedFeaturesAsync()：在其参与的一个或所有关系中查找指定要素的相关要素。

2.查询的工作方式

  查询条件是使用查询参数对象定义的。 您可以在此处指定属性，空间和/或时间输入。 大多数ArcGIS Runtime查询都将查询参数作为输入来定义查询条件以及结果的某些首选项。 当针对特定的数据集（功能表）执行查询时，结果将作为功能的集合返回。
  查询不需要定义每种类型的条件。 仅当明确定义查询条件时，才评估查询条件（例如，缺少时间条件意味着不根据时间过滤结果）。

注意：
  要使用查询返回数据集中的所有要素，请使用始终为true的表达式，例如“ 1 = 1”，并保留未定义的空间和时间条件。

3.查询参数

查询参数使用以下命令定义查询条件：
（1）属性条件的SQL表达式
（2）几何和空间关系的空间标准
（3）时间标准的日期/时间或日期/时间范围

可以为查询定义的一些空间关系包括：
  (Intersects)相交：要素的一部分包含在几何中。
  (Touches)接触：特征触摸几何的边界。
  (Crosses)交叉：要素穿过几何。
  (Within)内：要素完全被几何包围。
  (Contains)包含：要素的一部分或全部包含在几何体内。

注意：
  并非所有空间关系都对所有几何组合均有效。

  查询参数可用于标准查询中以返回要素，或用于返回要素计数或范围的查询。 还可以使用查询参数在地图上进行选择，以显示与条件匹配的要素。
  专用查询参数用于返回统计信息或相关功能的查询。 除了查询条件外，这些查询参数还定义了诸如要返回的统计信息类型或要评估的关系之类的内容。
  本示例使用空间条件在多边形内查找要素。 但是，查询参数只是传递给FeatureLayer而不是在FeatureTable上执行查询，而是将满足条件的要素显示为新选择。

// Build a buffer (polygon) around a click point
var buffer = GeometryEngine.Buffer(queryPoint, 5000);

// Use the buffer to define the geometry for a query
var query = new QueryParameters();
query.Geometry = buffer;
query.SpatialRelationship = SpatialRelationship.Contains;

// Select features in a feature layer using the query
await damageLayer.SelectFeaturesAsync(query, Esri.ArcGISRuntime.Mapping.SelectionMode.New);

4.查询结果

  查询结果通常提供功能的集合。 可以迭代结果要素将其显示在地图上，读取其属性，等等。 统计信息查询返回记录的集合，这些记录描述了数据集中要素所请求的统计信息。 对要素计数或范围的查询分别返回一个数字和一个集合。
  通过在查询参数中指定输出空间参考，可以在指定的空间参考中返回查询结果的几何图形。 如果未指定空间参考，则结果将在数据集的空间参考中返回。 通常，需要在与应用程序地图相同的空间参考中使用结果要素。

注意：
  如果不需要使用结果的几何图形（例如，用于显示要素），则可以设置查询参数以排除几何图形。 排除结果的几何部分可以极大地提高性能，特别是对于包含多个要素或复杂几何的结果。
  还可以设置要素的最大返回数量， 通过限制返回结果的信息量，它也可以提高性能。

识别
  识别就像空间查询的快捷方式。 它可以快速回答以下问题：这是什么？ 它为用户提供了一种通过点击或单击来快速浏览和了解地图或场景内容的方法。 从标识操作返回的信息可以显示在应用程序的弹出窗口或其他UI组件中。 与查询不同，用户无法提供属性或时间条件来过滤结果。 但是，可以返回指定位置的所有地理元素（来自所有图层）。

var layer = MyMapView.Map.OperationalLayers[0];
var pixelTolerance = 20;
var returnPopupsOnly = false;
var maxResults = 5;

// identify a layer using MapView, passing in the layer, the tap point, tolerance, types to return, and max results
IdentifyLayerResult idResults = await MyMapView.IdentifyLayerAsync(layer, tapScreenPoint, pixelTolerance, returnPopupsOnly, maxResults);

// get the layer identified and cast it to FeatureLayer
FeatureLayer idLayer = idResults.LayerContent as FeatureLayer;

// iterate each identified GeoElement in the results
foreach (GeoElement idElement in idResults.GeoElements)
{
    // cast the result GeoElement to Feature
    Feature idFeature = idElement as Feature;

    // select this feature in the feature layer
    idLayer.SelectFeature(idFeature);

二.编辑

编辑意味着你可以添加，更新和删除功能。 更新功能包括：
  （1）修改属性
  （2）修改几何形状（例如，移动或重塑形状）
  （3）添加，更新和删除要素附件（相关文件，例如图片，文档或视频）地图操作图层集中的要素图层提供了编辑的基础。 要素图层存储和利用数据库表编辑要素图层数据称为要素表。

许多工作流程均支持编辑功能：
  （1）在线要素服务编辑，即从服务创建表的地方，进行编辑，并且一旦用户完成编辑操作，所做的更改便被应用召回服务。适用于多用户编辑方案。
  （2）脱机要素服务的编辑和同步，即在脱机前从启用了同步的要素服务中创建本地地理数据库，在脱机时从地理数据库中检索表，进行编辑，然后在设备返回时将更改应用回该服务再次联机（服务器更改也可以同步回去）。适用于多用户离线工作流程。有关离线工作流程的更多信息，请参见离线地图，场景和数据。
  （3）静态要素集合编辑，即根据地图或门户项目中的要素创建表，进行编辑并将更改保存回地图或门户项目中。这是用于向许多客户端共享静态数据的合适工作流，但不应用于跨多个客户端编辑数据或共享频繁更改的数据。
  （4）脱机基于文件的编辑。可以从支持OGC GeoPackage规范的GeoPackage文件（.gpkg）中对要素进行编辑。这样的文件是独立的，没有功能服务的支持；它完全脱机。如果你的工作流程包括在线共享编辑和在许多用户之间管理编辑，则建议你使用在线要素服务编辑。

注意：
  可以通过编辑与功能链接的注释关联的任何功能的属性和/或地理位置来编辑功能链接的注释。 注释更改将应用于注释要素表，并在地图视图中可见。

1.为数据创建要素服务

  要素服务提供要素的符号系统，要素几何以及一组属性字段（模式）。 要素服务包含服务图层（要素数据）和表（非空间，表格数据），可以通过要素表为在线和离线要素服务工作流程进行编辑。 功能服务允许对随时间变化的数据进行可伸缩的多客户端编辑。
  在构建执行要素服务编辑的应用程序之前，需要一个要素服务来公开要编辑的图层。 有多种发布要素服务的方法。
  （1）你可以登录到组织的门户并从各种数据源发布要素，例如CSV文件，GeoJSON，shapefile，要素集合或文件地理数据库。所有这些选项及其步骤均在ArcGIS Online文档的“发布托管要素服务”主题中进行了概述。
  （2）你可以使用ArcGIS Pro将要素服务发布到ArcGIS Online或ArcGIS Enterprise。对于脱机工作流程，必须启用功能访问功能，并确保该服务已启用同步（在准备数据以供脱机使用中讨论）。
  （3）你可以使用ArcGIS for Developers网站创建要素图层。使用你的组织帐户或免费的开发人员订阅登录到该站点。访问“层”选项卡，然后单击“创建新层”按钮。对于脱机工作流程，请按照说明创建新要素图层，以确保已选中该框以使该图层可脱机以允许对其进行查看，编辑和同步。创建图层后，你可以在ArcGIS Online Map Viewer中向其中添加数据。
  无论你发布什么服务，都会为地图服务和要素服务创建REST URL（端点）。 可以在应用程序中使用使用这些URL来引用你的服务。 地图服务端点可用于对要素的只读访问（仅查看），因此请确保引用要素服务端点进行编辑。 脱机编辑工作流程需要启用同步的功能服务。 启用了同步的要素服务使你可以生成供脱机使用的地理数据库，并使你能够将本地编辑同步回该服务。

注意：
  ArcGIS Server 10.4或更高版本或ArcGIS Online中的托管服务需要发布已启用同步的要素服务。

2.要素集合

  要素集合是在地图或引用的门户项目内部存储为JSON格式的静态要素集合。 许多ArcGIS Online操作都会创建要素集合，例如将Map Notes添加到地图，导入shapefile，导入GPX文件或将分析结果作为项目共享。 特征集合有两种表示形式，这对于理解编辑和保存特征非常重要。
  （1）地图中的要素集合-这是将要素JSON作为要素集合层保存在单个地图中。
  （2）作为门户项目的要素集合-这是将要素JSON保存在门户项目中。 可以在多个地图中引用这些要素集合。
  这两种要素集类型的编辑要素的工作流程是相同的。 但是，用户查看保留编辑内容方面存在着差异。 对于地图中的要素集合，保存地图后，地图中的要素集将保留下来，打开地图的其他人将看到编辑后的要素。而对于作为门户项目的要素集合，保存地图时，将不会保存存储为门户项目的要素集合，必须更新或保存门户项目以确保其他人可以看到编辑的要素。
  功能集不应该用于多用户编辑，因为客户端可以轻松地保留功能集的旧版本并覆盖彼此的更改。 将要素服务用于这些类型的工作流程。

3.执行编辑

  通过使用编辑API，可以对编辑操作进行精细控制，从而允许你创建和编辑要素，添加，编辑或删除要素附件以及编辑要素的几何形状。
  对于使用本地地理数据库的编辑工作流，可以使用地理数据库事务来管理一组编辑（事务）。然后，你可以控制何时将这些编辑作为一个单位提交（保存）或回滚（丢弃）。
  企业级地理数据库可以使用版本控制来适应多用户编辑方案和长事务。如果您需要多个编辑者同时访问服务并具有撤消和重做其编辑功能的能力，则可以利用ArcGIS Enterprise门户中的分支版本。有关更多信息，请参见ArcGIS Pro文档中的“发布分支版本化数据”主题。
  对于某些要素服务编辑工作流，最好让分析师使用ArcGIS Pro定期查看编辑内容以验证数据完整性。尽管API中的组件可以执行某些数据验证，但是仅使用ArcGIS Runtime SDK不能执行其他任务，例如验证拓扑。

4.新增要素

  对于创建新要素，应用程序通常允许用户单击地图以指定新要素的位置。 可以通过侦听地图视图上的click事件来提供此功能，该事件随后会调用用于添加新要素的方法。
  要将要素添加到要素表，请从几何图形（例如，点，线或面）创建一个新要素，为该新要素创建属性，然后调用添加要素。 这会将要素添加到设备本地存储的表中。 即使你正在编辑服务功能表，您所做的编辑也将存储在客户端的表中。 必须显式应用服务要素表编辑，以将其提交给父级要素服务。

注意：
  在要素服务中添加或更新的所有要素都应具有有效的几何。 在ArcGIS Runtime离线编辑工作流中使用要素时，创建具有空（空）几何的要素可能会导致意外问题。 添加新要素时，好的做法是确保新功能的几何不为空。 如果要素的位置未知，则可能要使用空的几何。

private async void AddDamageFeature(MapPoint structureLocation, string type, string cause)
{
    var attributes = new Dictionary();
    attributes.Add("typdamage", type);
    attributes.Add("primcause", cause);

    // create a new feature in the damage table, pass in the attributes and geometry
    var newFeature = _damagePointsTable.CreateFeature(attributes, structureLocation);
    // add the new feature (this updates the local copy of the table)
    await _damagePointsTable.AddFeatureAsync(newFeature);

    // push this update (apply edits) to the feature service
    IReadOnlyList editResults = await _damagePointsTable.ApplyEditsAsync();
    // check the results for errors
    foreach (var r in editResults)
    {
        if (r.CompletedWithErrors)
        {
            Console.WriteLine("Edit to Object '" + r.ObjectId + "' failed: " + r.Error.Message);
        }
    }
}

5.更新要素

  要素更新包括移动或重塑要素的几何形状或对属性值进行编辑。 与所有编辑操作一样，所做的更改不会自动提交给要素源，需要开发人员进行提交。

// get all selected features in the layer
var damageLayer = MyMapView.Map.OperationalLayers[0] as FeatureLayer;
var selectedFeatures = await damageLayer.GetSelectedFeaturesAsync();

// loop through all features in the selection
foreach (ArcGISFeature f in selectedFeatures)
{
    // load the feature
    await f.LoadAsync();

    // update the damage type attribute
    f.Attributes["typdamage"] = "Inaccessible";

    // get the feature's geometry (point), move it to the north
    var location = f.Geometry as MapPoint;
    var newLocation = new MapPoint(location.X, location.Y + 50000);

    // set the feature's new location
    f.Geometry = newLocation;

    // update the feature in the local cache with these edits
    await _damagePointsTable.UpdateFeatureAsync(f);
}

// apply all the edits back to the service feature table
var editResults = await _damagePointsTable.ApplyEditsAsync();

6.删除要素

  你可以使用可以接受功能列表的delete features方法从要素表中删除多个要素，也可以仅使用一个具有删除要素的调用来删除一个要素。 与所有编辑操作一样，所做的更改不会自动提交给要素源，需要开发人员进行提交。

// get all selected features in the layer
var damageLayer = MyMapView.Map.OperationalLayers[0] as FeatureLayer;
var selectedFeatures = await damageLayer.GetSelectedFeaturesAsync();

// delete the selected features from the local cache
await _damagePointsTable.DeleteFeaturesAsync(selectedFeatures);

// apply all the edits back to the service feature table
var editResults = await _damagePointsTable.ApplyEditsAsync();

7.编辑者追踪

  编辑框架支持跟踪对要素的特定编辑。 这是通过跟踪以下要素属性来实现的：
  （1）哪个用户创建了要素
  （2）要素创建的日期和时间
  （3）哪个用户最后编辑了要素
  （4）上次编辑要素的日期和时间

三.使用分支版本化数据

  当你想要在面向服务的体系结构中（通过要素服务）提供多用户编辑并且您的用户不需要直接访问地理数据库时，请使用分支版本控制的数据（一种企业级地理数据库版本控制）。 要比较版本控制类型，请参阅ArcGIS Pro的主题版本控制类型。

  使用分支版本控制，编辑者可以在自己的地理数据库个人版本中工作，以使其他用户不会看到不完整的工作，并且编辑者也不会彼此阻碍访问数据。 每个版本都可以代表正在进行的工作，例如设计或一组工作订单，这些工作可以跨越多个会话，并且在必要时可以持续数周或数月。

使用分支版本化数据集的一些常见工作流程包括：
  （1）多用户编辑，例如在自己的分支机构工作的各个现场工作人员
  （2）为各种结果建模，每种情况都在其自己的分支中表示
  （3）编辑和跟踪项目的不同阶段

要在你的应用中使用分支版本控制：
  （1）必须按照“设置和共享版本化的数据”部分中的说明设置和共享数据。
  （2）可以使用ServiceGeodatabase类将数据带入应用程序，如使用分支版本部分中所述。

  可以像离线编辑要素服务或离线使用单个图层一样，离线编辑分支版本化数据，如“从分支版本中编辑数据”部分所述。

1.设置并共享版本化数据

  如果你需要多个编辑者同时访问服务并能够使用自己的一组编辑功能，则必须首先将数据注册为分支版本。当您将该数据集作为服务共享时，可以选择在发布时启用版本管理功能，该功能允许创建和管理版本。有关使用分支版本控制设置数据库的更多信息，请参见ArcGIS Pro帮助中的“将数据集注册为分支版本”。

  要编辑分支版本控制的数据，必须通过功能服务访问它。将数据注册为分支版本后，将数据作为Web要素层发布到组织的ArcGIS Enterprise门户。确保发布引用引用数据的图层。然后，这些数据将作为要素服务提供，可以在分支版本控制工作流中对其进行编辑。有关如何共享分支版本数据的更多信息，请参见ArcGIS Pro帮助的“共享分支版本数据”。
  在ArcGIS Runtime中，使用ServiceGeodatabase类表示托管的地理数据库。可以通过提供服务URI和可选的版本名称来创建类的实例。还可以从服务功能表中读取ServiceGeodatabase属性。
  如果要素表是从Web地图加载的，或者是从服务地理数据库（使用GetTable（layerId））创建的，则ServiceFeatureTable将具有关联的ServiceGeodatabase。使用任何构造函数创建的独立服务要素表都无法访问服务地理数据库。
  服务地理数据库允许你管理它包含的所有表的编辑，例如检查服务地理数据库是否具有本地编辑，应用所有编辑或撤消所有本地编辑。此类操作会影响服务地理数据库的连接表中的所有表（它管理的要素表的集合），并应用于所有类型的编辑（添加或删除要素，更新要素的几何或属性值，编辑附件等）。此外，当服务地理数据库支持分支版本控制时，你可以读取地理数据库的可用版本，切换当前版本或创建新版本。
  使用GetVersionsAsync可获取有关服务地理数据库包含当前用户有权访问的版本的信息。该信息包括名称，描述，访问级别（私有，受保护或公共），创建日期等。你可以通过提供名称，描述和访问级别来创建新版本。你可以访问自己拥有的公共版本和受保护版本以及私有版本。你看不到有关其他用户拥有的私有版本的信息，或无法连接到该私有版本。
  以下步骤显示了在服务地理数据库中使用版本时的一些常见任务。其中包括获取要素图层使用的服务地理数据库，获取有关当前版本的信息，创建新版本以及将地理数据库使用的版本切换到新版本。

（1）从地图中的要素图层获取服务要素表

// Get the feature table from a feature layer and cast it to ServiceFeatureTable
// (if the table is not a ServiceFeatureTable, it will be null)
ServiceFeatureTable table = layer.FeatureTable as ServiceFeatureTable;

（2）从服务要素表获取服务地理数据库。 确保服务地理数据库已加载。 加载服务要素表也将加载其服务地理数据库。

// If the feature table is a ServiceFeatureTable, see if it has a service geodatabase
if (table != null)
{
    ServiceGeodatabase serviceGdb = table.ServiceGeodatabase;
    if(serviceGdb != null)
    {
        // Load the service geodatabase if necessary
        if (serviceGdb.LoadStatus != LoadStatus.Loaded)
        {
            await serviceGdb.LoadAsync();
        }

（3）查看服务地理数据库是否支持分支版本控制。 如果是这样，请获取其版本列表以及有关当前版本的信息。

// (continued from above)
        // See if the service geodatabase supports branch versioning
        if (serviceGdb.SupportsBranchVersioning)
        {
            // Get the versions contained in the service geodatabase
            IReadOnlyList versions = await serviceGdb.GetVersionsAsync();

            // Get the info for the current version and read its description
            ServiceVersionInfo thisVersionInfo = versions.First(v => v.Name == serviceGdb.VersionName);
            string versionDesc = thisVersionInfo.Description;

（4）创建定义新版本属性的服务版本参数：名称，描述和访问级别。

// (continued from above)
            // Create service version parameters to define a new private version
            var versionParams = new ServiceVersionParameters()
            {
                Access = VersionAccess.Private,
                Name = "DesignTwo",
                Description = "Experimenting with an alternate design"
            };

（5）将参数传递到服务地理数据库以创建新版本。 然后将数据库的当前版本切换到新版本。

// (continued from above)
            // Use the parameters to create a new version in the service geodatabase
            var designTwoVersion = await serviceGdb.CreateVersionAsync(versionParams);

            // Switch the version used in the map to the new one
            await serviceGdb.SwitchVersionAsync(designTwoVersion.Name);
        }
    }

注意：
  对于来自支持分支版本控制的服务地理数据库中的表，ServiceFeatureTable上的GeodatabaseVersion提供了版本名称。 与来自传统版本化地理数据库的表不同，你无法通过更改该值来更改版本，而应使用SwitchVersionAsync（）。 切换版本后，ServiceFeatureTable上的GeodatabaseVersion将报告当前版本。 ServiceGeodatabase.VersionName’还报告ServiceGeodatabase`当前连接到的版本的名称。

2.编辑分支版本中的数据

  可以从分支版本对服务要素表进行编辑，就像对任何服务要素表进行编辑一样。 可以使用“编辑”主题中描述的相同工作流程。 在该标准工作流程中，ServiceGeodatabase类提供了一些其他成员来管理编辑。 例如，可以通过调用ApplyEditsAsync来应用所有本地编辑（适用于该版本中的所有表），并且可以使用UndoLocalEditsAsync撤消所有编辑。 协调和发布版本是后台操作，应使用ArcGIS Pro或其他企业流程执行。

（1）编辑要素表，例如添加，删除或更新要素。 对附件的编辑以及添加或删除关联也可以由服务地理数据库管理。

// Create a new feature and define its geometry and attributes
Feature feature = table.CreateFeature();
feature.Geometry = featureLocation;
feature.SetAttributeValue("CITY", "Chula Vista");

// Add the new feature to the local table
await table.AddFeatureAsync(feature);

// Delete some features
var cityFeatures = await table.QueryFeaturesAsync(new QueryParameters { WhereClause = "CITY='National City'" });
await table.DeleteFeaturesAsync(cityFeatures);

（2）要素表编辑只会影响本地数据集，除非它们明确地应用于服务。 在应用本地编辑之前，可能需要检查服务地理数据库的已连接表，以查看其管理的表。 加载Web地图时，服务地理数据库的连接表将包含同一要素服务中地图中的所有表。 从服务地理数据库访问表（使用GetTable（layerId））还将把该表添加到已连接表的集合中。

// See which tables are from the service geodatabase
IReadOnlyList serviceTables = serviceGdb.ConnectedTables;

（3）可以将编辑单独应用于每个表的要素服务，或者，如果数据集来自服务地理数据库，则可以将其应用于服务地理数据库中所有已连接表的所有本地编辑。 可以在服务要素表或服务地理数据库上使用HasLocalEdits（）来查看是否存在未保存的本地编辑。

if (table.HasLocalEdits())
{
    // Apply edits for the table to the service
    await table.ApplyEditsAsync();
}

if (serviceGdb.HasLocalEdits())
{
    // Apply local edits for all connected tables to the service
    await serviceGdb.ApplyEditsAsync();
}

  在服务地理数据库上而不是在每个单独的表上调用ApplyEditsAsync的优点是，它确保所有编辑操作都在单个事务中进行。 所有编辑都将应用，或者全部不应用。 如果对每个表分别应用编辑，则可能仅会应用一些编辑（例如，如果在操作过程中失去网络连接）。

注意：
  如果表没有全局ID字段，则将无法在服务地理数据库级别对附件应用编辑。 尝试这样做将导致GeodatabaseAttachmentsRequireGlobalIds错误。

（4）还可以分别撤消每个表的本地编辑或服务地理数据库中所有已连接表的所有本地编辑。

// Undo edits to the table
await table.UndoLocalEditsAsync();

// Undo all local edits for the version
await serviceGdb.UndoLocalEditsAsync();

具体示例见下篇。