Convenções de método de API de criação de perfil
Este tópico discute os valores de retorno de chamada de retorno do profiler e buffers alocados do chamador.
Valores de retorno de chamada de retorno
Um gerador de perfil retorna um valor de status como um HRESULT para cada notificação que o common language runtime (CLR) gera. Este valor de status pode ser S_OK ou E_FAIL. Atualmente, o runtime ignora o valor de status de cada retorno de chamada, exceto o ICorProfilerCallback::ObjectReferences método.
Buffers alocados do chamador
ICorProfilerInfo métodos que recebem os buffers alocados do chamador, como o GetAppDomainInfo método, geralmente estão em conformidade com a seguinte assinatura:
HRESULT GetBuffer
(
[in] /* Some query information (for example, a name).*/,
[in] ULONG32 cBufferSizeStart,
[out] ULONG32 *pcBufferMax,
[out] /* TYPE */ InfoBuffer[]
);
Esses métodos sempre se comportam como segue:
O cBufferSizeStart parâmetro especifica o número de elementos alocada no buffer. Esse valor representa o tamanho do buffer, o que é alocado pelo chamador desse método.
O pcBufferMax parâmetro for definido como o número total de elementos disponíveis. Depois que o método retorna, pcBufferMax é definida como o número máximo de elementos que foi retornado em vez do número de elementos que realmente foram retornados. Portanto, pcBufferMax é independente do tamanho real do que o buffer alocado pelo chamador.
O InfoBuffer parâmetro especifica o buffer alocado pelo chamador. Ele é criado pelo chamador desse método. Seu tamanho é especificado por cBufferSizeStart. Depois que o método retorna, esse buffer será preenchido com tantos elementos possível. Pode haver mais elementos disponíveis não caberão no buffer. Se InfoBuffer for nulo, cBufferSizeStart deve ser 0. Se todos os elementos são retornados, o método retorna S_OK e define pcBufferMax para o número total de elementos disponíveis.
Há duas maneiras de trabalhar com buffers alocados do chamador:
Método de passagem única: Alocar um buffer que você espera que irá ser grande o suficiente para conter todos os elementos retornados. Esteja preparado para realocar o buffer se ela é muito pequeno. Caso contrário, o truncamento de dados pode ocorrer.
Método de passagem de duplo: Como alternativa, chame o método duas vezes. Chamar primeiro com um comprimento zero InfoBuffer parâmetro para obter o tamanho de buffer correto. Em seguida, defina o tamanho do buffer para o valor retornado em pcBufferMax e chamar a função novamente.
O primeiro método é mais rápido e evita a alocação dinâmica. No entanto, talvez você precise realocar o buffer se não for grande o suficiente para conter as informações.
O segundo método é mais lento porque envolve duas chamadas e alocação dinâmica. Por exemplo, vamos supor que as informações de consulta solicitada foram para o nome do domínio do aplicativo. Após esse método retorna, você deve verificar que InfoBuffer era grande o suficiente para conter o nome completo do domínio de aplicativo. Para fazer isso, compare o valor que pcBufferMax aponta com o valor de cBufferSizeStart parâmetro. Se pcBufferMax aponta para um valor maior que cBufferSizeStart, alocar uma maior InfoBuffer buffer, a atualização cBufferSizeStart com o novo, maior o tamanho e a chamada novamente, o método.
Parâmetros de saída opcional
Na API de criação de perfil, todos os parâmetros de saída (especificada por [out] na sintaxe do método) são opcionais, a menos que um método tenha somente a saída de um parâmetro. Um gerador de perfil passa null para quaisquer parâmetros de saída que não está interessado. O profiler também deve passar valores consistentes para quaisquer parâmetros de entrada que estão associados com o parâmetro de saída. Por exemplo, se um parâmetro de saída nulo representa um buffer para ser preenchido com dados, o parâmetro de entrada especifica o tamanho do buffer deve ser definido como 0.