CTRPP

Articolo
06/12/2023

Lo strumento CTRPP è un preprocessore che analizza e convalida il manifesto per il provider V2. Lo strumento genera .rc risorse con le stringhe necessarie per i consumer del provider e genera un'intestazione .h con codice usato per fornire i dati del contatore. È consigliabile eseguire lo strumento CTRPP durante la compilazione del provider. È consigliabile usare il codice generato come punto di partenza quando si sviluppa il provider anziché provare a generare manualmente questo codice.

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

Argomenti

Opzione	Descrizione
inputFile	Obbligatorio: Specifica il nome del `.man` file (manifesto XML) che definisce i contatori.
-ocodeFile	Obbligatorio: Specifica il nome del file di `.h` codice da generare da CTRPP. Questo file conterrà funzioni helper inline C/C++ che semplificano l'inizializzazione e l'inizializzazione del provider.
-rc rcFile	Obbligatorio: Specifica il nome del file di `.rc` risorse da generare da CTRPP. Questo file conterrà la tabella di stringhe del provider.
-chsymFile	Specifica il nome del file di simboli facoltativo `.h` da generare da CTRPP. Questo file conterrà simboli C/C++ per i nomi e i GUID di ogni counterset nel provider.
Prefisso -prefix	Specifica il prefisso da usare per le variabili e le funzioni definite nel file di intestazione generato.
-NotificationCallback	Modifica la firma predefinita della funzione CounterInitialize per includere i parametri per specificare il nome delle funzioni di callback ControlCallback, AllocateMemory e FreeMemory . Questo argomento ha lo stesso effetto dell'inclusione dell'attributo `callback` nell'elemento provider .
-migrateoutputFile	Anziché generare `.h` file e `.rc` , aggiorna il manifesto inputFile alla versione più recente e lo salva in outputFile. Questa opzione non può essere utilizzata con altri commutatori. Sintassi: `CTRPP -migrate NewFile.man OldFile.man`
-BackCompat	Deprecato: Il supporto per i provider in modalità kernel è stato aggiunto in Windows 7. Per impostazione predefinita, il codice generato dal CTRPP per i provider in modalità kernel non sarà compatibile con le versioni precedenti di Windows (il driver non verrà caricato a causa di API mancanti `Pcw***` ). Impostare `-BackCompat` per abilitare la compatibilità con le versioni precedenti di Windows. Il driver caricherà dinamicamente le API necessarie e il codice generato disabiliterà automaticamente il provider se le API non sono disponibili.
-MemoryRoutines	Deprecato: Se usato con l'opzione `-Legacy` , include i modelli per le routine di memoria nel codice generato. In caso contrario, questo argomento ha lo stesso effetto dell'opzione `-NotificationCallback` .
-Eredità	Deprecato: Genera `.h`file , `.c`, `.rc`e `_r.h` usando i modelli di codice di Windows Vista (genera PerfAutoInitialize e PerfAutoCleanup anziché CounterInitialize e CounterCleanup). Questa opzione può essere usata con -MemoryRoutines e -NotificationCallback , ma non può essere usata con altre opzioni. Non usare le opzioni -o-rc con questa opzione. I file generati verranno denominati in base al nome del manifesto e verranno scritti nella directory che contiene il manifesto. Sintassi: `CTRPP -legacy OldFile.man`

Commenti

Lo strumento CTRPP genera un .h file di codice, un .rc file di risorse e, facoltativamente, genera un .h file di simboli.

Uso del file di risorse generato

Lo strumento CTRPP genererà un .rc file di risorse contenente le stringhe localizzabili necessarie dai consumer dei contatori del provider.

Importante

Le risorse di questo file devono essere incluse nel file binario del provider e il percorso completo del file binario del provider deve essere registrato durante l'installazione del manifesto del provider. I consumer che non riescono a individuare e caricare le risorse non potranno usare i contatori del provider.

Le risorse stringa devono essere gestite come segue:

Lo sviluppatore modifica il file manifesto del provider (.man) per impostare l'attributo applicationIdentity del provider sul nome di un file binario del provider (.DLL, .SYS o .EXE) che conterrà le risorse stringa per il provider e verrà installato come parte del componente del provider.
Lo strumento CTRPP legge il manifesto del provider e genera un .rc file.
Lo strumento RC (compilatore di risorse) compila i dati dal file generato .rc dal CTRPP per generare un .res file contenente le risorse binarie. A tale scopo, è possibile compilare direttamente il file generato dal .rc CTRPP OPPURE compilando un altro .rc file che include il file generato .rc dal CTRPP tramite una #include direttiva .
Il linker incorpora i dati dal file generato .res da RC nel file binario del provider.
Durante l'installazione, il file binario del provider viene copiato nel sistema dell'utente e il manifesto del provider viene registrato usando lo strumento lodctr. Lo strumento lodctr converte l'attributo applicationIdentity del manifesto del provider in un percorso completo e registra il percorso completo al file binario del provider nel Registro di sistema.
- Se il file binario del provider si trova nella stessa directory del manifesto, usare : lodctr.exe /m:"C:\full\manifest\path\manifest.man". lodctr combina il percorso manifesto specificato con l'attributo del applicationIdentity manifesto per formare il percorso completo.
- In caso contrario, usare lodctr.exe /m:"C:\full\manifest\path\manifest.man" "c:\full\binary\path". lodctr combina il percorso binario specificato con l'attributo del applicationIdentity manifesto per formare il percorso completo.
- A scopo di diagnostica, è possibile esaminare il percorso completo registrato controllando il ApplicationIdentity valore della chiave HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib\_V2Providers\{<ProviderGuid>}del Registro di sistema .
- Se il file binario usa MUI per la localizzazione, assicurarsi di copiare il file MUI insieme al file binario.
Durante la raccolta di contatori, il consumer usa il percorso completo registrato al file binario del provider per individuare e caricare le stringhe necessarie dalle risorse del file binario del provider.

Uso del file di codice generato in un provider in modalità utente

Lo strumento CTRPP genererà un .h file di codice C/C++. Se l'attributo del manifesto del providerType provider è impostato su userMode, il file di codice generato conterrà le definizioni seguenti utili per codificare un provider in modalità utente:

Funzione di inizializzazione del provider denominata prefissoCounterInitialize.
Funzione di pulizia del provider denominata prefissoCounterCleanup.
Variabile del provider globale che archivia l'handle del provider aperto dalla funzione CounterInitialize del prefisso. Il nome della variabile è il valore dell'attributo symbol dell'elemento provider nel manifesto. Questa variabile deve essere usata nelle chiamate a PerfCreateInstance, PerfDeleteInstancee altre API per controllare i dati del provider.
Per ogni contatore, una variabile GUID del counterset globale con il GUID del contatore. Il nome della variabile è il valore dell'attributo dell'elemento counterSetsymbol e il suffisso "GUID", ad esempio MyCounterSetGUID. Questa variabile deve essere usata nelle chiamate a PerfCreateInstance, PerfDeleteInstancee altre API per controllare i dati del provider.
Per ogni contatore, una macro contatore con il valore del id contatore. Il nome della macro è il valore dell'attributo counter dell'elemento symbol . Questa macro deve essere usata nelle chiamate a PerfSetCounterRefValue, PerfSetULongLongCounterValuee altre API per impostare i dati del provider.

Nei nomi delle funzioni , il prefisso fa riferimento al valore del parametro della -prefix riga di comando. Se il -prefix parametro non viene usato, le funzioni verranno denominate CounterInitialize e CounterCleanup.

Uso del file di codice generato in un provider in modalità kernel

Lo strumento CTRPP genererà un .h file di codice C/C++. Se l'attributo del manifesto del providerType provider è impostato su kernelMode, il file di codice generato conterrà le definizioni seguenti utili per codificare i contatori di un provider in modalità kernel:

Funzione di inizializzazione del counterset denominata prefissoRegisterCounterset. Questa funzione compila una struttura RegInfo e quindi richiama PcwRegister, inserendo l'handle di registrazione del counterset risultante nella variabile Counterset globale.
Funzione di pulizia del counterset denominata prefissoUnregisterCounterset. Questa funzione richiama PcwUnregister sull'handle di registrazione del contatore nella variabile counterset globale Counterset .
Funzione di creazione dell'istanza denominata prefissoCreateCounterset. Questa funzione compila una matrice di strutture PcwData e quindi richiama PcwCreateInstance usando l'handle di registrazione del contatore nella variabile Counterset globale.
Funzione di pulizia dell'istanza denominata prefissoCloseCounterset. Questa funzione richiama PcwCloseInstance.
Funzione di segnalazione dell'istanza denominata prefissoAddCounterset da usare dalla funzione di callback del counterset. Questa funzione compila una matrice di strutture PcwData e quindi richiama PcwAddInstance.
Windows SDK 20H1 e versioni successive: Una funzione di inizializzazione RegInfo denominata prefissoInitRegistrationInformationCounterset da usare in scenari avanzati. Questa funzione compila una struttura RegInfo . Questa funzione può essere usata nei casi in cui il prefissogenerato RegisterCounterset non soddisfa le proprie esigenze, ad esempio quando si desidera personalizzare i valori nella struttura RegInfo o quando si desidera archiviare l'handle restituito in un'altra variabile.

Nei nomi delle funzioni , il prefisso fa riferimento al valore del parametro della -prefix riga di comando. Se il -prefix parametro non viene usato, le funzioni non avranno alcun prefisso.

Nota

La funzione AddCounterset generata viene usata quando si dispone di un callback del counterset. Il prefissogenerato Creacounterset e le funzioni closecountersetdel prefisso vengono usati quando non si dispone di un callback del counterset.

Uso del file di simboli generato

Se il parametro -ch viene specificato nella riga di comando, lo strumento CTRPP genererà un .h file di simboli. Questo file contiene i simboli C/C++ per i nomi e i GUID di ogni counterset nel provider. I simboli possono essere usati durante la scrittura di programmi hardcoded per utilizzare i dati di questo counterset usando le funzioni Consumer PerfLib V2.

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista [solo app desktop]
Server minimo supportato	Windows Server 2008 [solo app desktop]