NameProfile

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at NameProfile.

The NameProfile function assigns a string to the specified process or thread.

The NameProfile API is available only for instrumentation profiling. The NameProfile API is not supported for sampling profiling.

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

Parameters

pszName

The name of the profiling element. A name is invalid (resulting in NameProfileA return NAME_ERROR_INVALID_NAME) if:

  • The pointer passed into NameProfileA is a NULL value

  • The string data of pszName starts with a number

  • The string data of pszName contains a space

  • The string data of pszName contains any of the following characters: ,;.`~!@#$%^&*()=[]{}|\?/<>

Level

Indicates the profile level to which performance data collection can be applied. The following PROFILE_CONTROL_LEVEL values can be used to indicate one of the three levels to which performance data collection can be applied:

EnumeratorDescription
PROFILE_GLOBALLEVELGlobal level setting affects all processes and threads in the profiling run.
PROFILE_PROCESSLEVELProcess level setting affect all threads that are part of specified process.
PROFILE_THREADLEVELThread profiling Level setting affects the specified thread.

dwId

Profiling level identifier. Use the process or thread identifier that is generated by the system.

The function indicates success or failure by using PROFILE_COMMAND_STATUS enumeration. The return value can be one of the following:

EnumeratorDescription
NAME_ERROR_ID_NOEXISTThe profiling element specified does not exist.
NAME_ERROR_INVALID_NAMEThe name is invalid.
NAME_ERROR_LEVEL_NOEXISTThe profile level specified does not exist.
NAME_ERROR_NO_SUPPORTThe specified operation is not supported.
NAME_ERROR_OUTOFMEMORYMemory was not available to record the event.
NAME_ERROR_REDEFINITIONA name was already assigned to the profile element. The name in this function is ignored.
NAME_ERROR_TEXTTRUNCATEDThe name text exceeded 32 characters including the null character and was therefore truncated.
NAME_OKName was registered successfully.

Only one name can be assigned to each process or thread. After a profiling element is named, subsequent calls to NameProfile for that element are ignored.

If the same name is given to different threads or processes, the report will include data from all elements at that level with that name.

If you specify a process or thread other than the current one, you must make sure that it has initialized and started running before you name it. Otherwise, the NameProfile method fails.

System_CAPS_ICON_important.jpg Important

CreateProcess() and CreateThread() API functions can return before the thread or process is initialized.

Microsoft.VisualStudio.Profiler.dll

HeaderInclude VSPerf.h
LibraryUse VSPerf.lib
UnicodeImplemented as NameProfileW (Unicode) and NameProfileA (ANSI).

The following code illustrates the NameProfile function call. The example assumes the use of Win32 string macros and the compiler settings for ANSI to determine whether the code calls the ANSI enabled function.

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  
}  

Visual Studio Profiler API Reference (Native)

Show: