ICLRProfiling::AttachProfiler, méthode

Article
08/10/2011

Attache le profileur indiqué au processus spécifié.

HRESULT AttachProfiler(
  [in] DWORD dwProfileeProcessID,
  [in] DWORD dwMillisecondsMax,                     // optional
  [in] const CLSID * pClsidProfiler,
  [in] LPCWSTR wszProfilerPath,                     // optional
  [in] size_is(cbClientData)] void * pvClientData,  // optional
  [in] UINT cbClientData);                          // optional

Paramètres

dwProfileeProcessID
[in] ID du processus auquel le profileur doit être attaché. Sur un ordinateur 64 bits, le nombre de bits du processus profilé doit correspondre au nombre de bits du processus déclencheur qui appelle AttachProfiler. Si le compte d'utilisateur sous lequel AttachProfiler est appelé dispose des privilèges d'administrateur, le processus cible peut être tout processus sur le système. Sinon, le processus cible doit être la propriété du même compte d'utilisateur.
dwMillisecondsMax
[in] Durée d'attente, en millisecondes, pour que AttachProfiler se termine. Le processus déclencheur doit passer un délai d'attente suffisant pour permettre au profileur spécifique de terminer son initialisation.
pClsidProfiler
[in] Pointeur vers le CLSID du profileur à charger. Le processus déclencheur peut réutiliser cette mémoire après le retour de AttachProfiler.
wszProfilerPath
[in] Chemin d'accès complet au fichier DLL du profileur à charger. Cette chaîne ne doit pas comporter plus de 260 caractères, y compris la marque de fin null. Si wszProfilerPath est null ou une chaîne vide, le Common Language Runtime (CLR) essaie de trouver l'emplacement du fichier DLL du profileur en recherchant le CLSID dans le Registre pointé par pClsidProfiler.
pvClientData
[in] Pointeur vers les données qui seront passées au profileur par la méthode ICorProfilerCallback3::InitializeForAttach. Le processus déclencheur peut réutiliser cette mémoire après le retour de AttachProfiler. Si pvClientData est null, cbClientData doit être égal à 0 (zéro).
cbClientData
[in] Taille, en octets, des données vers lesquelles pvClientData pointe.

Valeur de retour

La méthode retourne les HRESULT suivants :

HRESULT	Description
S_OK	Le profileur spécifié s'est correctement attaché au processus cible.
CORPROF_E_PROFILER_ALREADY_ACTIVE	Un profileur est déjà actif ou en cours d'attachement au processus cible.
CORPROF_E_PROFILER_NOT_ATTACHABLE	Le profileur spécifié ne prend pas en charge l'attachement. Le processus déclencheur peut essayer d'attacher un profileur différent.
CORPROF_E_PROFILEE_INCOMPATIBLE_WITH_TRIGGER	Impossible de demander un attachement de profileur car la version du processus cible est incompatible avec le processus actuel appelant AttachProfiler.
HRESULT_FROM_WIN32(ERROR_ACCESS_DENIED)	L'utilisateur du processus déclencheur n'a pas accès au processus cible.
HRESULT_FROM_WIN32(ERROR_PRIVILEGE_NOT_HELD)	L'utilisateur du processus déclencheur ne dispose pas des privilèges nécessaires pour attacher un profileur au processus cible donné. Le journal des événements de l'application peut contenir des d'informations supplémentaires.
CORPROF_E_IPC_FAILED	Une défaillance s'est produite lors de la communication avec le processus cible. Cela se produit généralement lorsque le processus cible s'arrête.
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)	Le processus cible n'existe pas ou n'exécute pas un CLR qui prend en charge l'attachement. Cela peut indiquer que le CLR a été déchargé depuis l'appel à la méthode d'énumération au moment de l'exécution.
HRESULT_FROM_WIN32(ERROR_TIMEOUT)	Le délai d'attente a expiré sans que le chargement du profileur ait commencé. Vous pouvez renouveler l'opération d'attachement. L'expiration des délais d'attente se produit lorsqu'un finaliseur du processus cible s'exécute pendant un temps plus long que la valeur du délai d'expiration.
E_INVALIDARG	Un ou plusieurs paramètres ont des valeurs non valides.
E_FAIL	Une autre défaillance non spécifiée s'est produite.
Autres codes d'erreur	Si la méthode ICorProfilerCallback3::InitializeForAttach du profileur retourne un HRESULT qui indique la défaillance, AttachProfiler retourne ce même HRESULT. Dans ce cas, E_NOTIMPL est converti en CORPROF_E_PROFILER_NOT_ATTACHABLE.

Notes

Pour plus d'informations sur l'attachement et le détachement des générateurs de profils, consultez Attachement au profileur et détachement du profileur.

Gestion de la mémoire

Conformément aux conventions COM, l'appelant de AttachProfiler (par exemple, le code déclencheur créé par le développeur de profileur) est chargé de l'allocation et de la libération de la mémoire pour les données vers lesquelles le paramètre pvClientData pointe. Lorsque le CLR exécute l'appel AttachProfiler, il fait une copie de la mémoire vers laquelle pvClientData pointe et la transmet au processus cible. Lorsque le CLR à l'intérieur du processus cible reçoit sa propre copie du bloc pvClientData, il passe le bloc au générateur de profils via la méthode InitializeForAttach, puis libère sa copie du bloc pvClientData du processus cible.