ICorProfilerCallback6::GetAssemblyReferences 方法ICorProfilerCallback6::GetAssemblyReferences Method

[.NET Framework 4.5.2 與更新版本提供支援][Supported in the .NET Framework 4.5.2 and later versions]

當 Common Language Runtime 執行組件參考關閉查核時,通知分析工具組件處於非常早期的載入中階段。Notifies the profiler that an assembly is in a very early loading stage, when the common language runtime performs an assembly reference closure walk.

語法Syntax

HRESULT GetAssemblyReferences(        [in, string] const WCHAR* wszAssemblyPath,  
        [in] ICorProfilerAssemblyReferenceProvider* pAsmRefProvider  
);  

參數Parameters

wszAssemblyPath
[in] 要修改其中繼資料之組件的路徑及名稱。[in] The path and name of the assembly whose metadata will be modified.

pAsmRefProvider
ICorProfilerAssemblyReferenceProvider 介面的位址指標,這個介面會指定要加入的元件參考。[in] A pointer to the address of an ICorProfilerAssemblyReferenceProvider interface that specifies the assembly references to add.

傳回值Return Value

忽略此回呼傳回的值。Return values from this callback are ignored.

備註Remarks

此回呼是藉由在呼叫ICorProfilerCallback5:: SetEventMask2方法時設定COR_PRF_HIGH_ADD_ASSEMBLY_REFERENCES事件遮罩旗標來控制。This callback is controlled by setting the COR_PRF_HIGH_ADD_ASSEMBLY_REFERENCES event mask flag when calling the ICorProfilerCallback5::SetEventMask2 method. 如果 profiler 登錄 ICorProfilerCallback6:: GetAssemblyReferences 回呼方法,則執行時間會傳遞要載入之元件的路徑和名稱,以及指向該方法的 ICorProfilerAssemblyReferenceProvider 介面物件的指標。If the profiler registers for the ICorProfilerCallback6::GetAssemblyReferences callback method, the runtime passes the path and name of the assembly to be loaded, along with a pointer to an ICorProfilerAssemblyReferenceProvider interface object to that method. 然後,分析工具可以ICorProfilerAssemblyReferenceProvider::AddAssemblyReference COR_PRF_ASSEMBLY_REFERENCE_INFO 針對其計畫從回呼中指定的元件參考的每個目標群組件,使用物件呼叫 ICorProfilerAssemblyReferenceProvider:: AddAssemblyReference 方法 GetAssemblyReferencesThe profiler can then call the ICorProfilerAssemblyReferenceProvider::AddAssemblyReference method with a COR_PRF_ASSEMBLY_REFERENCE_INFO object for each target assembly it plans to reference from the assembly specified in the GetAssemblyReferences callback.

若分析工具必須修改組件的中繼資料以加入組件參考時,才能使用 GetAssemblyReferences 回呼Use the GetAssemblyReferences callback only if the profiler has to modify an assembly's metadata to add assembly references. (但請注意,元件中繼資料的實際修改是在 ICorProfilerCallback:: ModuleLoadFinished回呼方法中完成。 ) 分析工具應該執行 GetAssemblyReferences 回呼方法,以通知 common LANGUAGE runtime (CLR) 當載入模組時,將會新增元件參考。(But note that the actual modification of an assembly's metadata is done in the ICorProfilerCallback::ModuleLoadFinishedcallback method.) The profiler should implement the GetAssemblyReferences callback method to inform the common language runtime (CLR) that assembly references will be added when the module has been loaded. 這可以確保在這早期階段由 CLR 執行的組件共用決定,即使在分析工具計劃於稍後修改中繼資料組件參考時也能保持有效性。This helps ensure that assembly sharing decisions made by the CLR during this early stage remain valid although the profiler plans to modify the metadata assembly references later. 這可以避免一些由分析工具中繼資料修改而導致 SECURITY_E_INCOMPATIBLE_SHARE 錯誤的情況。This can avoid some instances in which profiler metadata modifications cause an SECURITY_E_INCOMPATIBLE_SHARE error.

分析工具會使用這個方法所提供的 ICorProfilerAssemblyReferenceProvider 物件,將元件參考加入至 CLR 元件參考關閉的寫入器。The profiler uses the ICorProfilerAssemblyReferenceProvider object provided by this method to add assembly references to the CLR assembly reference closure walker. ICorProfilerAssemblyReferenceProvider物件只能從這個回呼內使用。The ICorProfilerAssemblyReferenceProvider object should be used only from within this callback. 此回呼的 ICorProfilerAssemblyReferenceProvider:: AddAssemblyReference 方法呼叫不會產生修改過的中繼資料,而只會在修改過的元件參考關閉過程中。Calls to the ICorProfilerAssemblyReferenceProvider::AddAssemblyReference method from this callback don't result in modified metadata, but only in a modified assembly reference closure walk. 分析工具仍然必須使用 IMetaDataAssemblyEmit 物件,以明確地在參考元件的 ICorProfilerCallback:: ModuleLoadFinished 回呼中加入元件參考,即使它會執行 GetAssemblyReferences 回呼。The profiler will still have to use an IMetaDataAssemblyEmit object to explicitly add assembly references from within the ICorProfilerCallback::ModuleLoadFinished callback for the referencing assembly, even if it implements the GetAssemblyReferences callback.

分析工具應該準備好接收相同元件的這個回呼的重複呼叫,而且每個這類重複呼叫的回應方式都相同 (藉由讓相同的 ICorProfilerAssemblyReferenceProvider:: AddAssemblyReference 呼叫集合) 。The profiler should be prepared to receive duplicate calls to this callback for the same assembly, and should respond identically for each such duplicate call (by making the same set of ICorProfilerAssemblyReferenceProvider::AddAssemblyReference calls).

需求Requirements

平台: 請參閱 系統需求Platforms: See System Requirements.

標頭: CorProf.idl、CorProf.hHeader: CorProf.idl, CorProf.h

程式庫: CorGuids.libLibrary: CorGuids.lib

.NET Framework 版本:自 4.5.2 起可用Available since 4.5.2.NET Framework Versions: 自 4.5.2 起可用Available since 4.5.2

另請參閱See also