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 値を使用して、パフォーマンス データ収集を適用できる 3 つのレベルのいずれかを指定できます。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

プロファイル レベル ID。Profiling level identifier. システムにより生成されたプロセス ID またはスレッド ID を使用します。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

各プロセスまたはスレッドには、名前を 1 つのみ割り当てることができます。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() API および 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

HeaderHeader VSPerf.h をインクルードします。Include VSPerf.h
LibraryLibrary VSPerf.lib を使用します。Use VSPerf.lib
UnicodeUnicode NameProfileW (Unicode) および 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)