NameProfile

Articolo
09/12/2008

Aggiornamento: novembre 2007

La funzione NameProfile assegna una stringa al processo o al thread specificato.

L'API NameProfile è disponibile solo per analisi tramite strumentazione. L'API NameProfile non è supportata per l'analisi tramite campionamento.

PROFILE_COMMAND_STATUS PROFILERAPI NameProfile(
                                                                      LPCTSTR pszName, 
                                   PROFILE_CONTROL_LEVEL Level,
                                   unsigned int dwId);

Parametri

pszName

Nome dell'elemento di profilo. Un nome non è valido (NameProfileA restituisce NAME_ERROR_INVALID_NAME) quando:

Il puntatore passato a NameProfileA è un valore NULL
I dati stringa di pszName iniziano con un numero
I dati stringa di pszName contengono uno spazio
I dati stringa di pszName contengono uno dei seguenti caratteri: ,;.`~!@#$%^&*()=[]{}|\?/<>

Level

Indica il livello di analisi al quale può essere applicata la raccolta dei dati sulle prestazioni. Gli enumeratori PROFILE_CONTROL_LEVEL seguenti possono essere utilizzati per indicare uno dei tre livelli a cui può essere applicata la raccolta dei dati sulle prestazioni:

dwId

Identificatore del livello di profilo. Utilizzare l'identificatore del processo o del thread generato dal sistema.

Valore proprietà/Valore restituito

La funzione indica esito positivo o negativo utilizzando l'enumerazione PROFILE_COMMAND_STATUS. Il valore restituito può essere uno dei seguenti:

Enumerator	Descrizione
NAME_ERROR_ID_NOEXIST	L'elemento di profilo specificato non esiste.
NAME_ERROR_INVALID_NAME	Nome non valido.
NAME_ERROR_LEVEL_NOEXIST	Il livello di profilo specificato non esiste.
NAME_ERROR_NO_SUPPORT	L'operazione specificata non è supportata.
NAME_ERROR_OUTOFMEMORY	Memoria non disponibile per registrare l'evento.
NAME_ERROR_REDEFINITION	All'elemento di profilo è stato già assegnato un nome. Il nome presente in questa funzione verrà ignorato.
NAME_ERROR_TEXTTRUNCATED	Il testo del nome è stato troncato perché ha superato 32 caratteri, incluso il carattere null.
NAME_OK	Il nome è stato registrato correttamente.

Note

A ogni processo o thread è possibile assegnare un solo nome. Dopo aver assegnato un nome a un elemento di profilo, le chiamate successive alla funzione NameProfile relative all'elemento in questione verranno ignorate.

Se viene assegnato lo stesso nome a thread o processi diversi, nel report saranno inclusi i dati di tutti gli elementi con quel nome presenti nel livello specifico.

Se si specifica un processo o un thread diverso da quello attuale, è necessario verificare che sia stato inizializzato e avviato prima dell'assegnazione del nome. In caso contrario, l'esecuzione del metodo NameProfile avrà esito negativo.

Nota importante:
Le funzioni API CreateProcess() e CreateThread() possono essere restituite prima dell'inizializzazione del thread o del processo.

Equivalente .NET Framework

Microsoft.VisualStudio.Profiler.dll

Informazioni sulla funzione

Intestazione	Includere VSPerf.h
Libreria	Utilizzare VSPerf.lib
Unicode	Implementato come NameProfileW (Unicode) e NameProfileA (ANSI).

Esempio

Nel codice riportato di seguito è illustrata la chiamata della funzione NameProfile. Nell'esempio si presuppone l'utilizzo di macro di stringa Win32 e delle impostazioni del compilatore per ANSI per stabilire se il codice chiama la versione ANSI della funzione.

void ExerciseNameProfile()
{
    // Variables used to print output.
    HRESULT hResult;
    TCHAR tchBuffer[256];

    // Create and initialize variables to pass to 
    // ExerciseNameProfile.  The value of this 
    // parameter is based on the needs of the code;
    // and for the sake of simplicity in this example, 
    // the variable is assigned an arbitrary value.
    TCHAR * profileName = TEXT("ExerciseNameProfile");

    // Declare enumeration to hold result of call to 
    // ExerciseNameProfle.
    PROFILE_COMMAND_STATUS nameResult;

    nameResult =  NameProfile(
        profileName,
        PROFILE_GLOBALLEVEL,
        PROFILE_CURRENTID);

    // Format and print result.
    LPCTSTR pszFormat = TEXT("%s %d.\0");
    TCHAR* pszTxt = TEXT("NameProfile returned");
    hResult = StringCchPrintf(tchBuffer, 256, pszFormat, 
        pszTxt, nameResult);

#ifdef DEBUG
    OutputDebugString(tchBuffer);
#endif
}

Vedere anche

Altre risorse

Riferimenti per le API del profiler di Visual Studio (native)

Condividi tramite