CTRPP

Das CTRPP-Tool ist ein Vorprozessor, der das Manifest für Ihren V2-Anbieter analysiert und überprüft. Das Tool generiert .rc Ressourcen mit den Zeichenfolgen, die von Consumern Ihres Anbieters benötigt werden, und generiert einen .h Header mit Code, den Sie zum Bereitstellen Ihrer Zählerdaten verwenden. Sie sollten das CTRPP-Tool während des Buildvorgangs Ihres Anbieters ausführen. Sie sollten den generierten Code als Ausgangspunkt für die Entwicklung Ihres Anbieters verwenden, anstatt diesen Code selbst zu generieren.

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

Argumente

Option	BESCHREIBUNG
inputFile	Erforderlich: Gibt den Namen der .man Datei (XML-Manifest) an, die Ihre Leistungsindikatoren definiert.
-ocodeFile	Erforderlich: Gibt den Namen der Codedatei an, die .h von CTRPP generiert werden soll. Diese Datei enthält C/C++-Inlinehilfsfunktionen, die das Initialisieren und Aufheben der Initialisierung Ihres Anbieters vereinfachen.
-rcFile	Erforderlich: Gibt den Namen der (Ressourcendatei) an, die .rc von CTRPP generiert werden soll. Diese Datei enthält die Zeichenfolgentabelle des Anbieters.
-chsymFile	Gibt den Namen der optionalen .h Symboldatei an, die von CTRPP generiert werden soll. Diese Datei enthält C/C++-Symbole für die Namen und GUIDs jedes Countersets im Anbieter.
Präfix	Gibt das Präfix an, das für die Variablen und Funktionen verwendet werden soll, die in der generierten Headerdatei definiert sind.
-NotificationCallback	Ändert die Standardsignatur der CounterInitialize-Funktion , um Parameter zum Angeben des Namens der Rückruffunktionen ControlCallback, AllocateMemory und FreeMemory einzuschließen. Dieses Argument hat die gleiche Auswirkung wie die Aufnahme des callback Attributs in das provider-Element .
-migrateoutputFile	Statt Dateien zu .h.rc generieren, aktualisieren Sie das manifest inputFile auf die neueste Version und speichern es in outputFile. Dieser Switch kann nicht mit anderen Switches verwendet werden. Syntax: CTRPP -migrate NewFile.man OldFile.man
-BackCompat	Veraltet: Unterstützung für Kernelmodusanbieter wurde in Windows 7 hinzugefügt. Standardmäßig ist der vom CTRPP für Kernelmodusanbieter generierte Code mit früheren Versionen von Windows nicht kompatibel (der Treiber kann aufgrund fehlender Pcw*** APIs nicht geladen werden). Legen Sie -BackCompat fest, um die Kompatibilität mit früheren Versionen von Windows zu aktivieren. Der Treiber lädt die erforderlichen APIs dynamisch, und der generierte Code deaktiviert den Anbieter automatisch, wenn die APIs nicht verfügbar sind.
-MemoryRoutines	Veraltet: Schließt bei Verwendung mit dem -Legacy Switch Vorlagen für Speicherroutinen in den generierten Code ein. Andernfalls hat dieses Argument die gleiche Auswirkung wie der -NotificationCallback Switch.
-Hinterlassenschaft	Veraltet: Generiert *.hDateien, *.c, *.rcund *_r.h mithilfe der Windows Vista-Codevorlagen (generiert PerfAutoInitialize und PerfAutoCleanup anstelle von CounterInitialize und CounterCleanup). Dieser Switch kann mit -MemoryRoutines und -NotificationCallback verwendet werden, kann aber nicht mit anderen Switches verwendet werden. Verwenden Sie nicht die Schalter -o oder -rc mit diesem Switch. Die generierten Dateien werden basierend auf dem Namen des Manifests benannt und in das Verzeichnis geschrieben, das das Manifest enthält. Syntax: CTRPP -legacy OldFile.man

Bemerkungen

Das CTRPP-Tool generiert eine .h Codedatei, eine .rc Ressourcendatei und optional eine .h Symboldatei.

Verwenden der generierten Ressourcendatei

Das CTRPP-Tool generiert eine .rc Ressourcendatei, die die lokalisierbaren Zeichenfolgen enthält, die von Consumern der Countersets des Anbieters benötigt werden.

Wichtig

Die Ressourcen aus dieser Datei müssen in Ihre Anbieterbinärdatei eingeschlossen werden, und der vollständige Pfad zur Anbieterbinärdatei muss während der Installation des Manifests Ihres Anbieters registriert werden. Verbraucher, die die Ressourcen nicht finden und laden können, können die Gegensätze Ihres Anbieters nicht verwenden.

Die Zeichenfolgenressourcen sollten wie folgt behandelt werden:

• Der Entwickler bearbeitet die Anbietermanifestdatei (.man), um das applicationIdentity Attribut des Anbieters auf den Namen einer Anbieterbinärdatei (.DLL, .SYS oder .EXE) festzulegen, die die Zeichenfolgenressourcen für den Anbieter enthält und als Teil der Anbieterkomponente installiert wird.
• Das CTRPP-Tool liest das Anbietermanifest und generiert eine .rc Datei.
• Das RC-Tool (Ressourcencompiler) kompiliert die Daten aus der von CTRPP generierten .rc Datei, um eine .res Datei zu generieren, die die binären Ressourcen enthält. Dies kann entweder durch direktes Kompilieren der von CTRPP generierten .rc Datei oder durch Kompilieren einer anderen .rc Datei erfolgen, die die von CTRPP generierte .rc Datei über eine #include Direktive enthält.
• Der Linker bettet die Daten aus der vom RC generierten .res Datei in die Anbieterbinärdatei ein.
• Während der Installation wird die Anbieterbinärdatei auf das System des Benutzers kopiert, und das Anbietermanifest wird mithilfe des lodctr-Tools registriert. Das lodctr-Tool konvertiert das applicationIdentity Attribut des Anbietermanifests in einen vollständigen Pfad und zeichnet den vollständigen Pfad zur Anbieterbinärdatei in der Registrierung auf.
  • Wenn sich die Anbieterbinärdatei im selben Verzeichnis wie das Manifest befindet, verwenden Sie Folgendes: lodctr.exe /m:"C:\full\manifest\path\manifest.man". lodctr kombiniert den angegebenen Manifestpfad mit dem Attribut des Manifests applicationIdentity , um den vollständigen Pfad zu bilden.
  • Verwenden Sie andernfalls lodctr.exe /m:"C:\full\manifest\path\manifest.man" "c:\full\binary\path". lodctr kombiniert den angegebenen binären Pfad mit dem Attribut des Manifests applicationIdentity , um den vollständigen Pfad zu bilden.
  • Zu Diagnosezwecken können Sie den aufgezeichneten vollständigen Pfad überprüfen, indem Sie den ApplicationIdentity Wert des Registrierungsschlüssels HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib\_V2Providers\{<ProviderGuid>}überprüfen.
  • Wenn die Binärdatei MUI für die Lokalisierung verwendet, müssen Sie die MUI-Datei zusammen mit der Binärdatei kopieren.
• Während der Countersetsammlung verwendet der Consumer den aufgezeichneten vollständigen Pfad zur Anbieterbinärdatei, um die erforderlichen Zeichenfolgen aus den Ressourcen der Anbieterbinärdatei zu suchen und zu laden.

Verwenden der generierten Codedatei in einem Benutzermodusanbieter

Das CTRPP-Tool generiert eine .h C/C++-Codedatei. Wenn das Attribut des Anbietermanifests providerType auf userModefestgelegt ist, enthält die generierte Codedatei die folgenden Definitionen, die beim Codieren eines Benutzermodusanbieters hilfreich sind:

• Eine Anbieterinitialisierungsfunktion mit dem Namen PräfixCounterInitialize.
• Eine Anbieterbereinigungsfunktion mit dem Namen PräfixCounterCleanup.
• Eine globale Anbietervariable , die das Anbieterhandle speichert, das mit dem PräfixCounterInitialize geöffnet wird. Der Name der Variablen ist der Wert des symbol Attributs des provider Elements im Manifest. Diese Variable sollte in Aufrufen PerfCreateInstancevon , PerfDeleteInstanceund anderen APIs zum Steuern der Daten Ihres Anbieters verwendet werden.
• Für jedes Counterset eine globale Gegenset-GUID-Variable mit der Gegenset-GUID. Der Name der Variablen ist der Wert des Attributs des counterSetsymbol Elements und das Suffix "GUID", z. B. MyCounterSetGUID. Diese Variable sollte in Aufrufen PerfCreateInstancevon , PerfDeleteInstanceund anderen APIs zum Steuern der Daten Ihres Anbieters verwendet werden.
• Für jeden Zähler ein Zählermakro mit dem Wert des Zählers id . Der Name des Makros ist der Wert des Attributs des countersymbol Elements. Dieses Makro sollte in Aufrufen von PerfSetCounterRefValue, PerfSetULongLongCounterValueund anderen APIs zum Festlegen der Daten Ihres Anbieters verwendet werden.

In den Funktionsnamen bezieht sich das Präfix auf den Wert des -prefix Befehlszeilenparameters. Wenn der -prefix Parameter nicht verwendet wird, werden die Funktionen und benanntCounterCleanupCounterInitialize.

Verwenden der generierten Codedatei in einem Kernelmodusanbieter

Das CTRPP-Tool generiert eine .h C/C++-Codedatei. Wenn das Attribut des Anbietermanifests providerType auf kernelModefestgelegt ist, enthält die generierte Codedatei die folgenden Definitionen, die beim Codieren der Gegensätze eines Kernelmodusanbieters hilfreich sind:

• Eine Gegensetinitialisierungsfunktion mit dem Namen PräfixRegisterCounterset. Diese Funktion füllt eine RegInfo-Struktur aus, ruft dann PcwRegister auf, und legt das resultierende Gegensatzregistrierungshandle in die globale Counterset-Variable .
• Eine Gegensetbereinigungsfunktion mit dem Namen PräfixUnregisterCounterset. Diese Funktion ruft PcwUnregister für das Counterset-Registrierungshandle in der globalen Counterset-Variable auf .
• Eine instance Erstellungsfunktion mit dem Namen PräfixCreateCounterset. Diese Funktion füllt ein Array von PcwData-Strukturen aus und ruft dann PcwCreateInstance mithilfe des Counterset-Registrierungshandles in der globalen Counterset-Variablen auf.
• Eine instance Bereinigungsfunktion namens PräfixCloseCounterset. Diese Funktion ruft PcwCloseInstance auf.
• Eine instance Berichtsfunktion namens PräfixAdd Counterset to be used from the counterset callback function. Diese Funktion füllt ein Array von PcwData-Strukturen aus, und ruft dann PcwAddInstance auf.
• Windows SDK 20H1 und höher: Eine RegInfo-Initialisierungsfunktion namens PräfixInitRegistrationInformationCounterset zur Verwendung in erweiterten Szenarien. Diese Funktion füllt eine RegInfo-Struktur aus. Diese Funktion kann in Fällen verwendet werden, in denen das generierte PräfixRegisterCounterset Nicht Ihren Anforderungen entspricht, z. B. wenn Sie die Werte in der RegInfo-Struktur anpassen möchten oder wenn Sie das zurückgegebene Handle in einer anderen Variablen speichern möchten.

In den Funktionsnamen bezieht sich das Präfix auf den Wert des -prefix Befehlszeilenparameters. Wenn der -prefix Parameter nicht verwendet wird, haben die Funktionen kein Präfix.

Hinweis

Das generierte PräfixAdd Counterset-Funktion wird verwendet, wenn Sie einen Gegensatzrückruf haben. Das generierte Präfix"Counterset erstellen" und das Präfix"Counterset schließen" werden verwendet, wenn Sie keinen Gegensatzrückruf haben.

Verwenden der generierten Symboldatei

Wenn der - ch-Parameter in der Befehlszeile angegeben wird, generiert das CTRPP-Tool eine .h Symboldatei. Diese Datei enthält die C/C++-Symbole für die Namen und GUIDs der einzelnen Countersets im Anbieter. Die Symbole können beim Schreiben von Programmen verwendet werden, die hartcodiert sind, um die Daten aus diesem Counterset mithilfe der PerfLib V2 Consumer-Funktionen zu nutzen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]