NameProfileNameProfile

NameProfile 함수는 지정된 프로세스 또는 스레드에 문자열을 할당합니다.The NameProfile function assigns a string to the specified process or thread.

NameProfile API는 계측 프로파일링에 사용할 수 있습니다.The NameProfile API is available only for instrumentation profiling. NameProfile API는 샘플링 프로파일링에 대해 지원되지 않습니다.The NameProfile API is not supported for sampling profiling.

구문Syntax

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

매개 변수Parameters

pszName

프로파일링 요소의 이름입니다.The name of the profiling element. 다음의 경우 이름이 잘못되었습니다(NameProfileA에서 NAME_ERROR_INVALID_NAME 반환).A name is invalid (resulting in NameProfileA return NAME_ERROR_INVALID_NAME) if:

  • NameProfileA로 전달된 포인터가 NULL 값인 경우The pointer passed into NameProfileA is a NULL value

  • pszName의 문자열 데이터가 숫자로 시작하는 경우The string data of pszName starts with a number

  • pszName의 문자열 데이터에 공백이 포함된 경우The string data of pszName contains a space

  • pszName의 문자열 데이터에 ,;.`~!@#$%^&*()=[]{}|\?/<>> 문자 중 하나가 포함된 경우The string data of pszName contains any of the following characters: ,;.`~!@#$%^&*()=[]{}|\?/<>

    Level

    성능 데이터 수집을 적용할 수 있는 프로필 수준을 나타냅니다.Indicates the profile level to which performance data collection can be applied. 다음 PROFILE_CONTROL_LEVEL 값은 성능 데이터 수집을 적용할 수 있는 세 가지 수준 중 하나를 나타내는 데 사용될 수 있습니다.The following PROFILE_CONTROL_LEVEL values can be used to indicate one of the three levels to which performance data collection can be applied:

열거자Enumerator 설명Description
PROFILE_GLOBALLEVELPROFILE_GLOBALLEVEL 전역 수준 설정은 프로파일링 실행의 모든 프로세스와 스레드에 영향을 줍니다.Global level setting affects all processes and threads in the profiling run.
PROFILE_PROCESSLEVELPROFILE_PROCESSLEVEL 프로세스 수준 설정은 지정된 프로세스의 일부인 모든 스레드에 영향을 줍니다.Process level setting affect all threads that are part of specified process.
PROFILE_THREADLEVELPROFILE_THREADLEVEL 스레드 프로파일링 수준 설정은 지정된 스레드에 영향을 줍니다.Thread profiling Level setting affects the specified thread.

dwId

프로파일링 수준 식별자입니다.Profiling level identifier. 시스템에서 생성한 프로세스 또는 스레드 식별자를 사용합니다.Use the process or thread identifier that is generated by the system.

속성 값/반환 값Property Value/Return Value

이 함수는 PROFILE_COMMAND_STATUS 열거형을 사용하여 성공 또는 실패를 나타냅니다.The function indicates success or failure by using PROFILE_COMMAND_STATUS enumeration. 반환 값은 다음 중 하나일 수 있습니다.The return value can be one of the following:

열거자Enumerator 설명Description
NAME_ERROR_ID_NOEXISTNAME_ERROR_ID_NOEXIST 지정된 프로파일링 요소가 없습니다.The profiling element specified does not exist.
NAME_ERROR_INVALID_NAMENAME_ERROR_INVALID_NAME 이름이 잘못되었습니다.The name is invalid.
NAME_ERROR_LEVEL_NOEXISTNAME_ERROR_LEVEL_NOEXIST 지정된 프로파일링 수준이 없습니다.The profile level specified does not exist.
NAME_ERROR_NO_SUPPORTNAME_ERROR_NO_SUPPORT 지정된 작업은 지원되지 않습니다.The specified operation is not supported.
NAME_ERROR_OUTOFMEMORYNAME_ERROR_OUTOFMEMORY 메모리에 이벤트를 기록할 수 없습니다.Memory was not available to record the event.
NAME_ERROR_REDEFINITIONNAME_ERROR_REDEFINITION 이름이 프로필 요소에 이미 할당되었습니다.A name was already assigned to the profile element. 이 함수의 이름은 무시됩니다.The name in this function is ignored.
NAME_ERROR_TEXTTRUNCATEDNAME_ERROR_TEXTTRUNCATED 이름 텍스트가 null 문자를 포함하여 32자를 초과했으므로 잘렸습니다.The name text exceeded 32 characters including the null character and was therefore truncated.
NAME_OKNAME_OK 이름이 등록되었습니다.Name was registered successfully.

설명Remarks

하나의 이름만 각 프로세스 또는 스레드에 할당될 수 있습니다.Only one name can be assigned to each process or thread. 프로파일링 요소에 이름이 지정된 후 해당 요소의 NameProfile에 대한 후속 호출은 무시됩니다.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. 그렇지 않으면 NameProfile 메서드가 실패합니다.Otherwise, the NameProfile method fails.

중요

CreateProcess() 및 CreateThread() API 함수는 스레드 또는 프로세스가 초기화되기 전에 반환할 수 있습니다.CreateProcess() and CreateThread() API functions can return before the thread or process is initialized.

.NET Framework의 해당 값.NET Framework Equivalent

Microsoft.VisualStudio.Profiler.dllMicrosoft.VisualStudio.Profiler.dll

함수 정보Function Information

헤더Header VSPerf.h 포함Include VSPerf.h
라이브러리Library VSPerf.lib 사용Use VSPerf.lib
유니코드Unicode NameProfileW(유니코드) 및 NameProfileA(ANSI)로 구현됐습니다.Implemented as NameProfileW (Unicode) and NameProfileA (ANSI).

Example

다음 코드에서는 NameProfile 함수 호출을 보여 줍니다.The following code illustrates the NameProfile function call. 예제에서는 코드에서 ANSI 사용 함수를 호출할지 여부를 결정하도록 Win32 문자열 매크로 및 ANSI에 대한 컴파일러 설정의 사용을 가정합니다.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  
}  

참고 항목See Also

Visual Studio 프로파일러 API 참조(네이티브)Visual Studio Profiler API Reference (Native)