Le CTRPP

L’outil CTRPP est un préprocesseur qui analyse et valide le manifeste de votre fournisseur V2. L’outil génère .rc des ressources avec les chaînes nécessaires aux consommateurs de votre fournisseur, et il génère un en-tête avec du .h code que vous utilisez pour fournir vos données de compteur. Vous devez exécuter l’outil CTRPP pendant la construction de votre fournisseur. Vous devez utiliser le code généré comme point de départ lors du développement de votre fournisseur au lieu d’essayer de générer ce code vous-même.

ctrpp -o codeFile -rc rcFile [-legacy] [-MemoryRoutines] [-NotificationCallback] [-prefix prefix] [-ch symFile] [-backcompat] inputFile

Les arguments

Remarques

L’outil CTRPP génère un .h fichier de code, un .rc fichier de ressources et, éventuellement, un fichier de .h symboles.

Utilisation du fichier de ressources généré

L’outil CTRPP génère un .rc fichier de ressources qui contient les chaînes localisables nécessaires aux consommateurs des compteurs du fournisseur.

Les ressources de chaîne doivent être gérées comme suit :

• Le développeur modifie le fichier manifeste () du fournisseur pour.man définir l’attribut applicationIdentity du fournisseur sur le nom d’un fichier binaire du fournisseur (.DLL, .SYS ou .EXE) qui contiendra les ressources de chaîne du fournisseur et sera installé dans le cadre du composant du fournisseur.
• L’outil CTRPP lit le manifeste du fournisseur et génère un .rc fichier.
• L’outil RC (resource compiler) compile les données du fichier généré par .rc CTRPP pour générer un .res fichier contenant les ressources binaires. Cela peut être fait soit en compilant directement le fichier généré par .rc CTRPP OU en compilant un autre .rc fichier qui inclut le fichier généré par .rc CTRPP via une #include directive.
• L’éditeur de liens intègre les données du fichier généré par .res RC dans le fichier binaire du fournisseur.
• Lors de l’installation, le fichier binaire du fournisseur est copié sur le système de l’utilisateur et le manifeste du fournisseur est enregistré à l’aide de l’outil lodctr. L’outil lodctr convertit l’attribut applicationIdentity du manifeste du fournisseur en un chemin d’accès complet et enregistre le chemin d’accès complet au binaire du fournisseur dans le registre.
  • Si le fichier binaire du fournisseur se trouve dans le même répertoire que le manifeste, utilisez : lodctr.exe /m:"C:\full\manifest\path\manifest.man". lodctr combinera le chemin d’accès au manifeste spécifié avec l’attribut du manifeste pour former le chemin d’accès applicationIdentity complet.
  • Sinon, utilisez lodctr.exe /m:"C:\full\manifest\path\manifest.man" "c:\full\binary\path". lodctr combinera le chemin binaire spécifié avec l’attribut du applicationIdentity manifeste pour former le chemin complet.
  • À des fins de diagnostic, vous pouvez inspecter le chemin d’accès complet enregistré en vérifiant la valeur de la ApplicationIdentity clé HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib\_V2Providers\{<ProviderGuid>}de registre.
  • Si le fichier binaire utilise MUI pour la localisation, assurez-vous de copier le fichier MUI avec le fichier binaire.
• Lors de la collecte de compteurs, le consommateur utilise le chemin d’accès complet enregistré au fichier binaire du fournisseur pour localiser et charger les chaînes nécessaires à partir des ressources du fichier binaire du fournisseur.

Utilisation du fichier de code généré dans un fournisseur en mode utilisateur

L’outil CTRPP génère un fichier de .h code C/C++. Si l’attribut du manifeste du providerType fournisseur est défini sur userMode, le fichier de code généré contient les définitions suivantes qui sont utiles pour coder un fournisseur en mode utilisateur :

• n fonction d’initialisation du fournisseur nommée préfixeCounterInitialize.
• Une fonction de nettoyage du fournisseur nommée préfixeCounterCleanup.
• Variable globale du fournisseur qui stocke le descripteur du fournisseur ouvert par la fonction CounterInitialize du préfixe. Le nom de la variable est la valeur de l’attribut symbol de l’élément provider dans le manifeste. Cette variable doit être utilisée dans les appels à , PerfDeleteInstanceet à PerfCreateInstanced’autres API pour contrôler les données de votre fournisseur.
• Pour chaque ensemble de compteurs, une variable GUID de compteur globale avec le GUID de compteur. Le nom de la variable est la valeur de l’attribut de l’élément counterSetsymbol plus le suffixe « GUID », par exemple MyCounterSetGUID. Cette variable doit être utilisée dans les appels à , PerfDeleteInstanceet à PerfCreateInstanced’autres API pour contrôler les données de votre fournisseur.
• Pour chaque compteur, une macro de compteur avec la valeur du id compteur. Le nom de la macro est la valeur de l’attribut de l’élément countersymbol . Cette macro doit être utilisée dans les appels à PerfSetCounterRefValue, PerfSetULongLongCounterValueet à d’autres API pour définir les données de votre fournisseur.

Dans les noms de fonctions, prefix fait référence à la valeur du paramètre de ligne de -prefix commande. Si le paramètre n’est -prefix pas utilisé, les fonctions seront nommées CounterInitialize et CounterCleanup.

Utilisation du fichier de code généré dans un fournisseur en mode noyau

L’outil CTRPP génère un fichier de .h code C/C++. Si l’attribut du manifeste du providerType fournisseur est défini sur kernelMode, le fichier de code généré contient les définitions suivantes qui sont utiles pour coder les compteurs d’un fournisseur en mode noyau :

• Une fonction d’initialisation de compteur nommée préfixeRegister Counterset. Cette fonction remplit une structure RegInfo puis appelle PcwRegister, en plaçant le handle d’enregistrement de compteur résultant dans la variable globale Counterset .
• Une fonction de nettoyage de compteur nommée préfixeDésinscrireCompteur. Cette fonction appelle PcwUnregister sur le handle d’enregistrement du compteur dans la variable globale Counterset .
• Une fonction de création d’instance nommée préfixeCreateCounterset. Cette fonction remplit un tableau de structures PcwData , puis appelle PcwCreateInstance à l’aide du handle d’enregistrement counterset dans la variable Counterset globale.
• Une fonction de nettoyage d’instance nommée préfixeClose Counterset. Cette fonction appelle PcwCloseInstance.
• Une fonction de rapport d’instance nommée préfixeAjouterun compteur à utiliser à partir de la fonction de rappel de compteur. Cette fonction remplit un tableau de structures PcwData , puis appelle PcwAddInstance.
• Kit de développement logiciel (SDK) Windows 20H1 et versions ultérieures : Une fonction d’initialisation RegInfo nommée préfixeInitRegistrationInformationCounterset à utiliser dans des scénarios avancés. Cette fonction remplit une structure RegInfo . Cette fonction peut être utilisée dans les cas où le préfixegénéré RegisterCounterset ne répond pas à vos besoins, par exemple lorsque vous souhaitez personnaliser les valeurs dans la structure RegInfo ou lorsque vous souhaitez stocker le handle renvoyé dans une autre variable.

Dans les noms de fonctions, prefix fait référence à la valeur du paramètre de ligne de -prefix commande. Si le paramètre n’est -prefix pas utilisé, les fonctions n’auront pas de préfixe.

Utilisation du fichier de symboles généré

Si le paramètre -ch est spécifié sur la ligne de commande, l’outil CTRPP génère un .h fichier de symboles. Ce fichier contient les symboles C/C++ pour les noms et les GUID de chaque compteur dans le fournisseur. Les symboles peuvent être utilisés lors de l’écriture de programmes codés en dur pour consommer les données de ce compteur à l’aide des fonctions PerfLib V2 Consumer Functions.

Spécifications