Programmazione

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

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

Argomenti

Opzione	Descrizione
file di input	Obbligatorio: Specifica il nome del .man file (manifesto XML) che definisce i contatori.
-ocodiceFile	Obbligatorio: Specifica il nome del file di .h codice che deve essere generato da CTRPP. Questo file conterrà funzioni helper inline C/C++ che semplificano l'inizializzazione e l'annullamento dell'inizializzazione del provider.
-rcrcFile	Obbligatorio: Specifica il nome del file di .rc risorse che deve essere generato da CTRPP. Questo file conterrà la tabella delle stringhe del provider.
-chsymFile	Specifica il nome del file di simboli facoltativo .h che deve essere generato da CTRPP. Questo file conterrà i simboli C/C++ per i nomi e i GUID di ogni insieme di contatori nel provider.
-prefissoprefisso	Specifica il prefisso da utilizzare per le variabili e le funzioni definite nel file di intestazione generato.
-NotificaCallback	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 .
-migrareoutputFile	Invece di generare .h e .rc file, aggiorna il manifesto inputFile alla versione più recente e lo salva in outputFile. Questo interruttore non può essere utilizzato con altri interruttori. Utilizzo: CTRPP -migrate NewFile.man OldFile.man
-Indietro Compat	Deprecato: In Windows 7 è stato aggiunto il supporto per i provider in modalità kernel. Per impostazione predefinita, il codice generato da 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.
-Routine di memoria	Deprecato: Se utilizzato con l'opzione -Legacy , include modelli per le routine di memoria nel codice generato. In caso contrario, questo argomento ha lo stesso effetto dell'interruttore -NotificationCallback .
-Eredità	Deprecato: Genera *.h, *.c, *.rc, e i *_r.h file utilizzando i modelli di codice di Windows Vista (genera PerfAutoInitialize e PerfAutoCleanup anziché CounterInitialize e CounterCleanup). Questa opzione può essere utilizzata con -MemoryRoutines e -NotificationCallback , ma non può essere utilizzata con altre opzioni. Non utilizzare gli interruttori -oo -rc con questo interruttore. I file generati verranno denominati in base al nome del manifesto e verranno scritti nella directory che conteneva il manifesto. Utilizzo: CTRPP -legacy OldFile.man

Osservazioni:

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

Utilizzo del file di risorse generato

Lo strumento CTRPP genererà un file di .rc risorse contenente le stringhe localizzabili necessarie per i 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 sono in grado di individuare e caricare le risorse non saranno in grado di utilizzare i contatori del provider.

Le risorse stringa devono essere gestite come segue:

• Lo sviluppatore modifica il file manifest (.man) del provider 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 (resource compiler) compila i dati dal file generato .rc da CTRPP per generare un .res file contenente le risorse binarie. Questa operazione può essere eseguita compilando direttamente il file generato .rc da CTRPP OPPURE compilando un altro .rc file che include il file generato da .rc CTRPP tramite una #include direttiva.
• Il linker incorpora i dati del 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 utilizzando lo strumento lodctr. Lo strumento lodctr converte l'attributo applicationIdentity del manifesto del provider in un percorso completo e registra il percorso completo del file binario del provider nel Registro di sistema.
  • Se il file binario del provider si trova nella stessa directory del manifesto, utilizzare: lodctr.exe /m:"C:\full\manifest\path\manifest.man". lodctr combinerà il percorso del manifesto specificato con l'attributo del manifesto applicationIdentity per formare il percorso completo.
  • In caso contrario, usare lodctr.exe /m:"C:\full\manifest\path\manifest.man" "c:\full\binary\path". lodctr combinerà il percorso binario specificato con l'attributo del manifesto applicationIdentity per formare il percorso completo.
  • A scopo diagnostico, è possibile ispezionare 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 utilizza MUI per la localizzazione, assicurarsi di copiare il file MUI insieme al file binario.
• Durante la raccolta dei counterset, il consumer utilizza il percorso completo registrato per il file binario del provider per individuare e caricare le stringhe necessarie dalle risorse del file binario del provider.

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

Lo strumento CTRPP genererà un file di .h 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 la codifica di un provider in modalità utente:

• n funzione di inizializzazione del provider denominata prefissoCounterInitialize.
• Una 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 utilizzata nelle chiamate a PerfCreateInstance, PerfDeleteInstance, e in altre API per il controllo dei dati del provider.
• Per ogni insieme di contatori, una variabile GUID di un insieme di contatori globale con il GUID di un insieme di contatori. Il nome della variabile è il valore dell'attributo dell'elemento counterSetsymbol più il suffisso "GUID", ad esempio MyCounterSetGUID. Questa variabile deve essere utilizzata nelle chiamate a PerfCreateInstance, PerfDeleteInstance, e in altre API per il controllo dei dati del provider.
• Per ogni contatore, una macro del idcontatore con il valore del contatore. Il nome della macro è il valore dell'attributo counter dell'elemento symbol . Questa macro deve essere utilizzata nelle chiamate a PerfSetCounterRefValue, PerfSetULongLongCounterValue, e in altre API per l'impostazione dei dati del provider.

Nei nomi delle funzioni, il prefisso si riferisce al valore del parametro della riga di -prefix comando. Se il -prefix parametro non viene utilizzato, le funzioni saranno denominate CounterInitialize e CounterCleanup.

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

Lo strumento CTRPP genererà un file di .h 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 la codifica dei counterset di un provider in modalità kernel:

• Funzione di inizializzazione del counterset denominata prefissoRegister Counterset. Questa funzione compila una struttura RegInfo , quindi richiama PcwRegister, inserendo l'handle di registrazione del counterset risultante nella variabile globale Counterset .
• Una funzione di pulizia del counterset denominata prefissoUnregister Counterset. Questa funzione richiama PcwUnregister sull'handle di registrazione del counterset nella variabile globale Counterset .
• Una funzione di creazione di istanze denominata prefixCreateCounterset. Questa funzione compila una matrice di strutture PcwData , quindi richiama PcwCreateInstance utilizzando l'handle di registrazione counterset nella variabile globale Counterset .
• Una funzione di pulizia dell'istanza denominata prefixClose Counterset. Questa funzione richiama PcwCloseInstance.
• Una funzione di segnalazione dell'istanza denominata prefissoAggiungicontroinsieme da utilizzare dalla funzione di callback del controinsieme. Questa funzione compila una matrice di strutture PcwData , quindi richiama PcwAddInstance.
• Windows SDK 20H1 e versioni successive: Funzione di inizializzazione RegInfo denominata prefixInitRegistrationInformationCounterset per l'uso in scenari avanzati. Questa funzione compila una struttura RegInfo . Questa funzione può essere utilizzata nei casi in cui il prefissogeneratoRegister Counterset non soddisfa le proprie esigenze, ad esempio quando si desidera personalizzare i valori nella struttura RegInfo o quando si desidera memorizzare l'handle restituito in un'altra variabile.

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

Annotazioni

La funzione AddCounterset del prefisso generata viene utilizzata quando si dispone di un callback del counterset. Le funzioni generate per creareun controinsieme e per chiudere uninsieme di controinsieme vengono utilizzate quando non si dispone di un callback per insieme di controgruppi.

Utilizzo del file di simboli generato

Se il parametro -ch viene specificato nella riga di comando, lo strumento CTRPP genererà un file di .h simboli. Questo file contiene i simboli C/C++ per i nomi e i GUID di ogni insieme di contatori nel provider. I simboli possono essere utilizzati durante la scrittura di programmi hardcoded per l'utilizzo dei dati di questo insieme di contatori utilizzando 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]