Dynamics 365本地版9.1虚拟实体服务器端分页参数异常排查

问题场景与现象 #

使用Dynamics 365 9.1本地版，配置连接外部OData v4 API的虚拟实体以实现服务器端分页，API支持skip和top查询参数，但遇到以下问题：

• 当API方法使用[FromQuery] int? skip和[FromQuery] int? top参数时，无法获取数据；
• 若为参数设置默认值（如skip=0、top=10），API仅返回默认数量的记录，忽略Dynamics发送的skip和top参数值。

API简化代码 #

[HttpGet]
public async Task<ActionResult<List<UserCertificatesDto>>> Get([FromQuery] int? skip , [FromQuery] int? top )
{
    int skipValue = skip ?? 0;
    int topValue = top ?? 10;

    var certificates = await _userCertificates.GetAllByPage(skipValue, topValue);
    return Ok(new
    {
        value = certificates,
        totalRecordCount = certificates.Count,
        hasMoreRecords = (skipValue + topValue) < certificates.Count
    });
}

已完成操作 #

• 配置虚拟实体数据源启用服务器端分页；
• 通过Postman独立测试API，传递skip和top参数可正常工作；
• 验证虚拟实体字段与API属性名称匹配。

咨询问题 #

1. Dynamics 365如何向API传递skip、top分页参数？
2. 是否需要特殊配置确保参数被正确处理？
3. Dynamics 365虚拟实体是否支持依赖查询参数分页的API？
4. Dynamics 365 9.1本地版在虚拟实体OData分页方面有哪些特殊注意事项？

问题解答 #

1. Dynamics 365传递分页参数的方式 #

Dynamics 365虚拟实体针对OData v4数据源，默认会按照OData标准的$skip和$top查询参数传递分页指令，而非自定义的skip和top参数。你的API当前接收的参数名与Dynamics发送的不匹配，这是核心问题。

2. 需要的特殊配置及参数处理调整 #

• 修改API参数名：将API的参数名改为OData标准的$skip和$top，可通过FromQuery的Name属性指定参数名，示例代码如下：

[HttpGet]
public async Task<ActionResult<List<UserCertificatesDto>>> Get([FromQuery(Name = "$skip")] int? skip , [FromQuery(Name = "$top")] int? top )
{
    int skipValue = skip ?? 0;
    int topValue = top ?? 10;

    var totalCount = await _userCertificates.GetTotalCount();
    var certificates = await _userCertificates.GetAllByPage(skipValue, topValue);
    return Ok(new
    {
        value = certificates,
        totalRecordCount = totalCount,
        hasMoreRecords = (skipValue + topValue) < totalCount
    });
}

• 数据源配置验证：确认虚拟实体数据源的“启用服务器端分页”选项已勾选，9.1本地版默认支持OData v4的$skip/$top，无需额外自定义参数映射。
• 修正响应格式：API返回的totalRecordCount必须是全量数据的总条数，而非当前页的记录数，否则Dynamics无法判断是否还有更多数据，导致分页逻辑失效。

3. 虚拟实体对查询参数分页API的支持 #

Dynamics 365虚拟实体支持依赖查询参数分页的API，但必须遵循OData v4的标准规范（使用$skip/$top参数）。如果API使用自定义参数名，只能通过修改API适配标准参数，9.1本地版不支持自定义参数映射。

4. Dynamics 365 9.1本地版的特殊注意事项 #

• 严格遵循OData标准：该版本虚拟实体仅支持OData v4标准的$skip/$top分页参数，不支持自定义分页参数的自动映射。
• 总记录数必须准确：必须返回全量数据的总条数，否则服务器端分页会失效，Dynamics可能只会请求第一页或重复请求相同数据。
• 数据源配置限制：9.1本地版的虚拟实体数据源没有自定义分页参数的配置项，无法将Dynamics的分页指令映射为非标准参数。
• API性能要求：确保API的分页查询逻辑高效，避免全表扫描，因为Dynamics会根据数据展示需求多次请求不同页码的数据。

内容的提问来源于stack exchange，提问作者Ahmed Hamdy