Paginação com IDirectorySearch

A paginação especifica quantas linhas o servidor retorna ao cliente. Uma página pode ser definida pelo número de linhas ou por um limite de tempo. O objeto ADSI COM recupera cada página de resultados com base nos valores listados na tabela a seguir. O chamador chama IDirectorySearch::GetNextRow quando atingiu o final da página e o objeto ADSI COM recupera a próxima página.

Valor	Descrição
ADS_SEARCHPREF_PAGESIZE	Especifica o número máximo de linhas a serem retornadas em uma página.
ADS_SEARCHPREF_PAGED_TIME_LIMIT	Especifica o tempo máximo, em segundos, que o servidor deve gastar coletando uma página de resultados antes de retornar a página ao cliente. Se o limite for atingido, o servidor interromperá a pesquisa e retornará as linhas já recuperadas para a página.

 

Se nenhuma dessas preferências de pesquisa estiver definida, o padrão será nenhuma paginação. As pesquisas do Active Directory realizadas sem paginação são limitadas a retornar um máximo dos primeiros 1000 registros, portanto, você deve usar uma pesquisa paginada se houver a possibilidade de que o conjunto de resultados contenha mais de 1000 itens.

Uma operação de pesquisa pode resultar em um grande número de objetos sendo retornados. Se o servidor retornar o resultado em um conjunto, ele poderá diminuir o desempenho do cliente e do servidor, bem como afetar a carga de rede. Pesquisas paginadas podem ser usadas para evitar isso. Em uma pesquisa paginada, o cliente pode aceitar resultados em pacotes menores. O tamanho de um pacote é conhecido como o tamanho da página de pesquisa.

As pesquisas paginadas oferecem benefícios tanto para o cliente quanto para o servidor. O cliente pode ser mais ágil na apresentação dos resultados aos usuários. Isso é especialmente relevante para ferramentas de interface gráfica do usuário que podem iniciar o processo de exibição da janela enquanto o outro thread recebe os dados simultaneamente.

No lado do servidor, as pesquisas paginadas tornam a operação escalável. Por exemplo, se cem clientes emitem solicitações de pesquisa simultaneamente e, em média, cada cliente recebe duzentos objetos. Se nenhum tamanho de página for especificado, no pior cenário, o servidor deverá ter memória suficiente para armazenar 20.000 objetos. Por outro lado, se cada cliente especificar um tamanho de página para ser, por exemplo, dez objetos, o requisito de memória no servidor será reduzido em um fator de 20.

Além disso, usando uma pesquisa paginada, um cliente pode abandonar a operação em andamento. Por outro lado, em uma pesquisa não paginada, o cliente recebe um conjunto de resultados em um pacote. Isso pode diminuir o desempenho da rede.

ADSI lida com o tamanho da página para o cliente. O cliente não precisa contar o número de objetos em andamento. ADSI encapsula a interação do servidor para o cliente. Da perspectiva do cliente, a pesquisa retorna um conjunto de resultados completo.

Recomenda-se que a paginação seja usada.

Para especificar um tamanho máximo de página, defina uma opção de pesquisa ADS_SEARCHPREF_PAGESIZE com um valor de ADSTYPE_INTEGER definido como o número máximo de linhas por página na matriz ADS_SEARCHPREF_INFO passada para o método IDirectorySearch::SetSearchPreference .

O exemplo de código a seguir mostra como definir o tamanho máximo da página.

ADS_SEARCHPREF_INFO SearchPref;
SearchPref.dwSearchPref = ADS_SEARCHPREF_PAGESIZE;
SearchPref.vValue.dwType = ADSTYPE_INTEGER;
SearchPref.vValue.Integer = 1000;

Para especificar um tempo de página, defina uma opção de pesquisa ADS_SEARCHPREF_PAGED_TIME_LIMIT com um valor de ADSTYPE_INTEGER definido como o número máximo de segundos que o servidor deve gastar recuperando uma página na matriz ADS_SEARCHPREF_INFO passada para o método IDirectorySearch::SetSearchPreference .

O exemplo de código a seguir mostra como especificar a hora da página.

ADS_SEARCHPREF_INFO SearchPref;
SearchPref.dwSearchPref = ADS_SEARCHPREF_PAGED_TIME_LIMIT;
SearchPref.vValue.dwType = ADSTYPE_INTEGER;
SearchPref.vValue.Integer = 60;