程式碼剖析 API 方法慣例
本主題討論分析工具回呼傳回值和呼叫端配置的緩衝區。
回呼傳回值
分析工具會針對 Common Language Runtime (CLR) 引發的每個告知傳回 HRESULT 狀態值。 這個狀態值可以是 S_OK 或 E_FAIL。 目前，執行階段會忽略每個回呼中的狀態值，但 ICorProfilerCallback::ObjectReferences 方法除外。
呼叫端配置的緩衝區
接收由呼叫端配置之緩衝區的 ICorProfilerInfo 方法 (例如 GetAppDomainInfo 方法) 通常符合下列簽章：
HRESULT GetBuffer
(
[in] /* Some query information (for example, a name).*/,
[in] ULONG32 cBufferSizeStart,
[out] ULONG32 *pcBufferMax,
[out] /* TYPE */ InfoBuffer[]
);
這些方法一定以下列方式運作：
cBufferSizeStart 參數會指定緩衝區中配置的元素數目。 這個值表示由這個方法的呼叫端所配置的緩衝區大小。
pcBufferMax 參數設定為可用元素的總數。 在方法傳回之後，pcBufferMax 會設定為可傳回元素的最大數目，而非實際傳回的元素數目。 因此，pcBufferMax 與由呼叫端配置之緩衝區的實際大小無關。
InfoBuffer 參數會指定由呼叫端配置的緩衝區。 它是由這個方法的呼叫端建立的。 它的大小是由 cBufferSizeStart 指定的。 在方法傳回之後，這個緩衝區會盡可能多填入些元素。 可用元素可能多於緩衝區的容量。 如果 InfoBuffer 為 null，則 cBufferSizeStart 必須是 0。 如果傳回任何元素，方法會傳回 S_OK，並會將 pcBufferMax 設定為可用元素的總數。
有兩個方法可使用由呼叫端配置的緩衝區：
單一行程方法：配置預期夠大、足以包含所有傳回元素的緩衝區。 如果緩衝區證實太小，要準備重新配置它。 否則，可能會發生資料截斷。
雙重行程方法：或者，呼叫方法兩次。 先使用長度為零的 InfoBuffer 參數來呼叫，以取得正確的緩衝區大小。 接著，將緩衝區大小設定為 pcBufferMax 中傳回的值，並再次呼叫函式。
第一個方法比較快，並且避免動態配置。 不過，如果緩衝區不夠大，無法包含資訊，您必須重新配置它。
第二個方法比較慢，因為它涉及到兩個呼叫和動態配置。 例如，假設針對應用程式定義域名稱，要求查詢資訊。 這個方法傳回之後，您必須驗證 InfoBuffer 夠大，足以包含應用程式定義域的完整名稱。 若要完成這項工作，請比較 pcBufferMax 所指向的值與 cBufferSizeStart 參數的值。 如果 pcBufferMax 指向大於 cBufferSizeStart 的值，請配置較大的 InfoBuffer 緩衝區，以較大的大小來更新 cBufferSizeStart，然後重新呼叫方法。
選擇性輸出參數
在分析 API 中，除非方法只有一個輸出參數 (使用 [out] 在方法語法中指定)，否則所有輸出參數都為選擇性參數。 分析工具會對不感興趣的輸出參數傳遞 null。 分析工具也必須對與輸出參數相關聯的任何輸入參數傳遞一致的值。 例如，null 輸出參數表示要以資料填滿其中的緩衝區，則指定該緩衝區大小的輸入參數必須設為 0。