Edit

ICorProfilerCallback6::GetAssemblyReferences Method

  • Article

[Supported in the .NET Framework 4.5.2 and later versions]

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] The path and name of the assembly whose metadata will be modified.

pAsmRefProvider
[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

This callback is controlled by setting the COR_PRF_HIGH_ADD_ASSEMBLY_REFERENCES event mask flag when calling the ICorProfilerCallback5::SetEventMask2 method. 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. The 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.

Use the GetAssemblyReferences callback only if the profiler has to modify an assembly's metadata to add assembly references. (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. 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. This can avoid some instances in which profiler metadata modifications cause an SECURITY_E_INCOMPATIBLE_SHARE error.

The profiler uses the ICorProfilerAssemblyReferenceProvider object provided by this method to add assembly references to the CLR assembly reference closure walker. The ICorProfilerAssemblyReferenceProvider object should be used only from within this callback. Calls to the ICorProfilerAssemblyReferenceProvider::AddAssemblyReference method from this callback don't result in modified metadata, but only in a modified assembly reference closure walk. 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.

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.

Header: CorProf.idl, CorProf.h

Library: CorGuids.lib

.NET Framework Versions: Available since 4.5.2

See also