CTRPP

La herramienta CTRPP es un preprocesador que analiza y valida el manifiesto del proveedor V2. La herramienta genera .rc recursos con las cadenas necesarias para los consumidores del proveedor y genera un .h encabezado con código que se usa para proporcionar los datos del contador. Debe ejecutar la herramienta CTRPP durante la compilación del proveedor. Debe usar el código generado como punto de partida al desarrollar el proveedor en lugar de intentar generar este código usted mismo.

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

Argumentos

Opción	Descripción
inputFile	Obligatorio: Especifica el nombre del .man archivo (manifiesto XML) que define los contadores.
-ocodeFile	Obligatorio: Especifica el nombre del .h archivo de código que va a generar CTRPP. Este archivo contendrá funciones auxiliares insertadas de C/C++ que simplifican la inicialización y desinicialización del proveedor.
-rcFile	Obligatorio: Especifica el nombre del (archivo de .rc recursos) que va a generar CTRPP. Este archivo contendrá la tabla de cadenas del proveedor.
-chsymFile	Especifica el nombre del archivo de símbolos opcional .h que va a generar CTRPP. Este archivo contendrá símbolos de C/C++ para los nombres y GUID de cada conjunto de contadores del proveedor.
-prefijode prefijo	Especifica el prefijo que se va a usar para las variables y funciones definidas en el archivo de encabezado generado.
-NotificationCallback	Cambia la firma predeterminada de la función CounterInitialize para incluir parámetros para especificar el nombre de las funciones de devolución de llamada ControlCallback, AllocateMemory y FreeMemory . Este argumento tiene el mismo efecto que incluir el callback atributo en el elemento provider .
-migrateoutputFile	En lugar de generar .h archivos y .rc , actualiza el manifiesto inputFile a la versión más reciente y lo guarda en outputFile. Este modificador no se puede usar con otros modificadores. Uso: CTRPP -migrate NewFile.man OldFile.man
-BackCompat	Obsoleto: Se agregó compatibilidad con proveedores en modo kernel en Windows 7. De forma predeterminada, el código generado por CTRPP para proveedores en modo kernel no será compatible con versiones anteriores de Windows (el controlador no se cargará debido a que faltan Pcw*** API). Establézcalo -BackCompat para habilitar la compatibilidad con versiones anteriores de Windows. El controlador cargará dinámicamente las API necesarias y el código generado deshabilitará silenciosamente el proveedor si las API no están disponibles.
-MemoryRoutines	Obsoleto: Cuando se usa con el -Legacy modificador, incluye plantillas para rutinas de memoria en el código generado. De lo contrario, este argumento tiene el mismo efecto que el -NotificationCallback modificador.
-Legado	Obsoleto: Genera *.harchivos , *.c, *.rcy *_r.h mediante las plantillas de código de Windows Vista (genera PerfAutoInitialize y PerfAutoCleanup en lugar de CounterInitialize y CounterCleanup). Este modificador se puede usar con -MemoryRoutines y -NotificationCallback , pero no se puede usar con ningún otro modificador. No use los modificadores -o o -rc con este modificador. Los archivos generados se denominarán en función del nombre del manifiesto y se escribirán en el directorio que contenía el manifiesto. Uso: CTRPP -legacy OldFile.man

Comentarios

La herramienta CTRPP genera un .h archivo de código, un .rc archivo de recursos y, opcionalmente, genera un .h archivo de símbolos.

Uso del archivo de recursos generado

La herramienta CTRPP generará un .rc archivo de recursos que contiene las cadenas localizables necesarias para los consumidores de los conjuntos de contadores del proveedor.

Importante

Los recursos de este archivo deben incluirse en el binario del proveedor y la ruta de acceso completa al binario del proveedor debe registrarse durante la instalación del manifiesto del proveedor. Los consumidores que no pueden localizar y cargar los recursos no podrán usar los conjuntos de contadores del proveedor.

Los recursos de cadena deben controlarse de la siguiente manera:

• El desarrollador edita el archivo de manifiesto del proveedor (.man) para establecer el applicationIdentity atributo del proveedor en el nombre de un binario del proveedor (.DLL, .SYS o .EXE) que contendrá los recursos de cadena del proveedor y se instalará como parte del componente del proveedor.
• La herramienta CTRPP lee el manifiesto del proveedor y genera un .rc archivo.
• La herramienta RC (compilador de recursos) compila los datos del archivo generado por .rc CTRPP para generar un .res archivo que contiene los recursos binarios. Esto se puede hacer mediante la compilación directa del archivo generado por .rc CTRPP O mediante la compilación de otro .rc archivo que incluye el archivo generado por .rc CTRPP mediante una #include directiva .
• El enlazador inserta los datos del archivo generado por .res RC en el binario del proveedor.
• Durante la instalación, el binario del proveedor se copia en el sistema del usuario y el manifiesto del proveedor se registra mediante la herramienta lodctr. La herramienta lodctr convierte el applicationIdentity atributo del manifiesto del proveedor en una ruta de acceso completa y registra la ruta de acceso completa al binario del proveedor en el registro.
  • Si el binario del proveedor está en el mismo directorio que el manifiesto, use: lodctr.exe /m:"C:\full\manifest\path\manifest.man". lodctr combinará la ruta de acceso del manifiesto especificada con el atributo del applicationIdentity manifiesto para formar la ruta de acceso completa.
  • En otros casos, use lodctr.exe /m:"C:\full\manifest\path\manifest.man" "c:\full\binary\path". lodctr combinará la ruta de acceso binaria especificada con el atributo del applicationIdentity manifiesto para formar la ruta de acceso completa.
  • Para fines de diagnóstico, puede inspeccionar la ruta de acceso completa registrada comprobando el ApplicationIdentity valor de la clave HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib\_V2Providers\{<ProviderGuid>}del Registro .
  • Si el binario usa MUI para la localización, asegúrese de copiar el archivo MUI junto con el binario.
• Durante la colección de conjuntos de contadores, el consumidor usa la ruta de acceso completa registrada al binario del proveedor para buscar y cargar las cadenas necesarias desde los recursos del binario del proveedor.

Uso del archivo de código generado en un proveedor en modo de usuario

La herramienta CTRPP generará un .h archivo de código de C/C++. Si el atributo del manifiesto del providerType proveedor se establece userModeen , el archivo de código generado contendrá las siguientes definiciones que son útiles para codificar un proveedor en modo de usuario:

• Una función de inicialización del proveedor denominada prefijoCounterInitialize.
• Una función de limpieza del proveedor denominada prefijoCounterCleanup.
• Variable de proveedor global que almacena el identificador del proveedor abierto por la función CounterInitialize de prefijo. El nombre de la variable es el valor del symbol atributo del provider elemento en el manifiesto. Esta variable se debe usar en llamadas a PerfCreateInstance, PerfDeleteInstancey otras API para controlar los datos del proveedor.
• Para cada conjunto de contadores, una variable GUID de conjunto de contadores global con el GUID del conjunto de contadores. El nombre de la counterSet variable es el valor del atributo del symbol elemento más el sufijo "GUID", por ejemplo, MyCounterSetGUID. Esta variable se debe usar en llamadas a PerfCreateInstance, PerfDeleteInstancey otras API para controlar los datos del proveedor.
• Para cada contador, una macro de contador con el valor del id contador. El nombre de la counter macro es el valor del atributo del symbol elemento. Esta macro se debe usar en llamadas a PerfSetCounterRefValue, PerfSetULongLongCounterValuey otras API para establecer los datos del proveedor.

En los nombres de función, el prefijo hace referencia al valor del -prefix parámetro de línea de comandos. Si el -prefix parámetro no se usa, las funciones se denominarán CounterInitialize y CounterCleanup.

Uso del archivo de código generado en un proveedor en modo kernel

La herramienta CTRPP generará un .h archivo de código de C/C++. Si el atributo del manifiesto del providerType proveedor se establece kernelModeen , el archivo de código generado contendrá las siguientes definiciones que son útiles para codificar los conjuntos de contadores de un proveedor en modo kernel:

• Función de inicialización de conjunto de contadores denominada prefijoRegisterCounterset. Esta función rellena una estructura RegInfo y, a continuación, invoca PcwRegister, colocando el identificador de registro del conjunto de contadores resultante en la variable global Counterset .
• Una función de limpieza de conjuntos de contadores denominada prefijoUnregisterCounterset. Esta función invoca PcwUnregister en el identificador de registro del conjunto de contadores en la variable global Counterset .
• Una función de creación de instancias denominada prefijoCreateCounterset. Esta función rellena una matriz de estructuras PcwData y, a continuación, invoca PcwCreateInstance mediante el identificador de registro del conjunto de contadores en la variable global Counterset .
• Una función de limpieza de instancias denominada prefijoCerrarconjunto de contadores. Esta función invoca a PcwCloseInstance.
• Una función de informes de instancia denominada prefijoAgregarconjunto de contadores que se usará desde la función de devolución de llamada del conjunto de contadores. Esta función rellena una matriz de estructuras PcwData y luego invoca PcwAddInstance.
• Windows SDK 20H1 y versiones posteriores: Una función de inicialización RegInfo denominada prefijoInitRegistrationInformationCounterset para su uso en escenarios avanzados. Esta función rellena una estructura RegInfo . Esta función se puede usar en los casos en los que el prefijogenerado RegisterCounterset no satisface sus necesidades, por ejemplo, cuando desea personalizar los valores de la estructura RegInfo o cuando desea almacenar el identificador devuelto en otra variable.

En los nombres de función, el prefijo hace referencia al valor del -prefix parámetro de línea de comandos. Si el -prefix parámetro no se usa, las funciones no tendrán ningún prefijo.

Nota

La función AddCounterset del prefijo generado se usa cuando se tiene una devolución de llamada de conjunto de contadores. El prefijogenerado Creaconjunto de contadores y las funciones de prefijoCloseCounterset se usan cuando no tienes una devolución de llamada de conjunto de contadores.

Uso del archivo de símbolos generado

Si se especifica el parámetro -ch en la línea de comandos, la herramienta CTRPP generará un .h archivo de símbolos. Este archivo contiene los símbolos de C/C++ para los nombres y GUID de cada conjunto de contadores del proveedor. Los símbolos se pueden usar al escribir programas codificados de forma rígida para consumir los datos de este conjunto de contadores mediante las funciones perfLib V2 Consumer.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows Vista [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2008 [solo aplicaciones de escritorio]