You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Port System.Reflection source comments to Docs (#2317)
* Port System.Reflection source comments to Docs
* Fixed bad cref tag
* Added description for type
* Added type description and remarks.
* Apply suggestions from code review
Applying suggestions by rpetrusha in PR.
Co-Authored-By: carlossanlop <[email protected]>
* Fixed broken xrefs
* Fixed bad cref.
Copy file name to clipboardExpand all lines: xml/System.Reflection/DispatchProxy.xml
+11-10Lines changed: 11 additions & 10 deletions
Original file line number
Diff line number
Diff line change
@@ -24,7 +24,7 @@
24
24
</Base>
25
25
<Interfaces />
26
26
<Docs>
27
-
<summary>To be added.</summary>
27
+
<summary>Provides a mechanism for instantiating proxy objects and handling their method dispatch.</summary>
28
28
<remarks>To be added.</remarks>
29
29
</Docs>
30
30
<Members>
@@ -90,11 +90,12 @@
90
90
</TypeParameters>
91
91
<Parameters />
92
92
<Docs>
93
-
<typeparamname="T">To be added.</typeparam>
94
-
<typeparamname="TProxy">To be added.</typeparam>
95
-
<summary>To be added.</summary>
96
-
<returns>To be added.</returns>
93
+
<typeparamname="T">The interface the proxy should implement.</typeparam>
94
+
<typeparamname="TProxy">The base class to use for the proxy class.</typeparam>
95
+
<summary>Creates an object instance that derives from class <typeparamrefname="TProxy" /> and implements interface <typeparamrefname="T" />.</summary>
96
+
<returns>An object instance that implements <typeparamrefname="T" />.</returns>
97
97
<remarks>To be added.</remarks>
98
+
<exceptioncref="T:System.ArgumentException"><typeparamrefname="T" /> is a class, or <typeparamrefname="TProxy" /> is sealed or does not have a parameterless constructor.</exception>
98
99
</Docs>
99
100
</Member>
100
101
<MemberMemberName="Invoke">
@@ -127,12 +128,12 @@
127
128
<ParameterName="args"Type="System.Object[]" />
128
129
</Parameters>
129
130
<Docs>
130
-
<paramname="targetMethod">To be added.</param>
131
-
<paramname="args">To be added.</param>
132
-
<summary>To be added.</summary>
133
-
<returns>To be added.</returns>
131
+
<paramname="targetMethod">The method the caller invoked.</param>
132
+
<paramname="args">The arguments the caller passed to the method.</param>
133
+
<summary>Whenever any method on the generated proxy type is called. Rhis method will be invoked to dispatch control.</summary>
134
+
<returns>The object to return to the caller, or <seelangword="null" /> for void methods.</returns>
<summary>Represents a closed universe of Type objects loaded for inspection-only purposes. Each MetadataLoadContext can have its own binding rules and is isolated from all other MetadataLoadContexts.</summary>
22
+
<remarks>
23
+
<formattype="text/markdown"><![CDATA[
24
+
25
+
A `MetadataLoadContext` serves as a dictionary that binds assembly names to <xref:System.Reflection.Assembly> instances that were previously loaded into the context or need to be loaded.
26
+
27
+
Assemblies are treated strictly as metadata. There are no restrictions on loading assemblies based on target platform, CPU architecture, or pointer size. There are no restrictions on the assembly designated as the core assembly (**mscorlib**).
<paramname="coreAssemblyName">The name of the assembly that contains the core types such as <seecref="T:System.Object" />. Typically, this would be "mscorlib".</param>
51
+
<summary>Creates a new <seecref="T:System.Reflection.MetadataLoadContext" /> object.</summary>
The core assembly is treated differently than other assemblies because references to these well-known types do not include the assembly reference, unlike normal types.
79
+
80
+
Typically, this assembly is named "mscorlib" or "netstandard". If the core assembly cannot be found, the value will be `null`, and many other reflection methods, including those that parse method signatures, will throw an exception.
81
+
82
+
The `CoreAssembly` is determined by passing the `coreAssemblyName` parameter passed to the <xref:System.Reflection.MetadataAssemblyResolver> constructor
83
+
to the <xref:System.Reflection.MetadataAssemblyResolver.Resolve%2A?displayProperty=nameWithType> method.
84
+
85
+
If no `coreAssemblyName` argument was specified in the constructor of <xref:System.Reflection.MetadataLoadContext>, then default values are used, including "mscorlib", "System.Runtime" and "netstandard".
86
+
87
+
The designated core assembly does not need to contain the core types directly. It can type forward them to other assemblies. Thus, it is perfectly permissible to use the mscorlib facade as the designated core assembly.
88
+
89
+
Note that <xref:System.Runtime> is not an ideal core assembly because it excludes some of the interop-related pseudo-custom attribute types such as <xref:System.Runtime.InteropServices.DllImportAttribute>. However, it can serve if you have no interest in those attributes. The CustomAttributes API will skip those attributes if the core assembly does not include the necessary types.
90
+
91
+
The core assembly is not loaded until necessary. The following APIs do not trigger the search for the core assembly:
If a core assembly cannot be found or if the core assembly is missing types, this will affect the behavior of the <xref:System.Reflection.MetadataLoadContext> as follows:
109
+
110
+
* APIs that need to parse signatures or typespecs and return the results as <xref:System.Type> objects will throw an exception. For example:
* APIs that need to compare types to well-known core types will not throw an exception, and the comparison will evaluate to `false`. For example, if you do not specify a core assembly, <xref:System.Type.IsPrimitive> will return `false` for everything, even types named <xref:System.Int32>. Similarly, <xref:System.Type.GetTypeCode%2A?displayProperty=nameWithType> will return <xref:System.TypeCode.Object> for everything.
118
+
119
+
* If a metadata entity sets flags that surface as a pseudo-custom attribute, and the core assembly does not contain the pseudo-custom attribute type, the necessary constructor or any of the parameter types of the constructor, the <xref:System.Reflection.MetadataLoadContext> will not throw. It will omit the pseudo-custom attribute from the list of returned attributes.
120
+
]]></format>
121
+
</remarks>
66
122
</Docs>
67
123
</Member>
68
124
<MemberMemberName="Dispose">
@@ -85,8 +141,17 @@
85
141
</ReturnValue>
86
142
<Parameters />
87
143
<Docs>
88
-
<summary>To be added.</summary>
89
-
<remarks>To be added.</remarks>
144
+
<summary>Releases any native resources (such as file locks on assembly files). </summary>
145
+
<remarks>
146
+
<formattype="text/markdown"><![CDATA[
147
+
148
+
After disposal, it is not safe to use any <xref:System.Reflection.Assembly> objects dispensed by the <xref:System.Reflection.MetadataLoadContext> or any reflection objects dispensed by those <xref:System.Reflection.Assembly> objects.
149
+
150
+
Though objects provided by the <xref:System.Reflection.MetadataLoadContext> strive to throw an <xref:System.ObjectDisposedException>, this is not guaranteed.
151
+
152
+
Some APIs may return fixed or previously cached data. Accessing objects *during* a <xref:System.Reflection.MetadataLoadContext.Dispose%2A> method call may result in an unmanaged access violation and failfast.
153
+
]]></format>
154
+
</remarks>
90
155
</Docs>
91
156
</Member>
92
157
<MemberMemberName="GetAssemblies">
@@ -106,8 +171,8 @@
106
171
</ReturnValue>
107
172
<Parameters />
108
173
<Docs>
109
-
<summary>To be added.</summary>
110
-
<returns>To be added.</returns>
174
+
<summary>Return an atomic snapshot of the assemblies that have been loaded into the <seecref="T:System.Reflection.MetadataLoadContext" />.</summary>
175
+
<returns>An enumerable collection of <seexref="T:System.Reflection.Assembly" /> objects.</returns>
<summary>Resolves the supplied assembly name to an assembly. If an assembly was previously bound to this name, that assembly is returned. Otherwise, the <seecref="T:System.Reflection.MetadataLoadContext" /> calls the specified <seecref="T:System.Reflection.MetadataAssemblyResolver" />.</summary>
Note that the behavior of this method matches the behavior of the <xref:System.Runtime.Loader.AssemblyLoadContext.LoadFromAssemblyName%2A?displayProperty=nameWithType> resolve event but does not match the behavior of <xref:System.Reflection.Assembly.ReflectionOnlyLoad%2A?displayProperty=nameWithType>. (The latter gives up without raising its resolve event.)
<paramname="assemblyName">A <seecref="T:System.String" /> representing the assembly name.</param>
229
+
<summary>Resolves the supplied assembly name to an assembly. If an assembly was previously bound to this name, that assembly is returned. Otherwise, the <seecref="T:System.Reflection.MetadataLoadContext" /> calls the specified <seecref="T:System.Reflection.MetadataAssemblyResolver" />.</summary>
Note that the behavior of this method matches the behavior of <xref:System.Runtime.Loader.AssemblyLoadContext.LoadFromAssemblyName%2A?displayProperty=nameWithType> resolve event but does not match the behavior of <xxref:System.Reflection.Assembly.ReflectionOnlyLoad%2A?displayProperty=nameWithType>. (The latter gives up without raising its resolve event.)
<paramname="assemblyPath">A <seecref="T:System.String" /> representing the path to the assembly.</param>
262
+
<summary>Loads an assembly from a specific path on the disk and binds its assembly name to it in the <seecref="T:System.Reflection.MetadataLoadContext" />. If a prior assembly with the same name was already loaded into the <seecref="T:System.Reflection.MetadataLoadContext" />, the prior assembly will be returned.</summary>
<exceptioncref="T:System.IO.FileLoadException">The two assemblies do not have the same Mvid.</exception>
186
266
</Docs>
187
267
</Member>
188
268
<MemberMemberName="LoadFromByteArray">
@@ -203,10 +283,11 @@
203
283
<ParameterName="assembly"Type="System.Byte[]" />
204
284
</Parameters>
205
285
<Docs>
206
-
<paramname="assembly">To be added.</param>
207
-
<summary>To be added.</summary>
208
-
<returns>To be added.</returns>
286
+
<paramname="assembly">A <seecref="T:System.Byte[]" /> holding an assembly.</param>
287
+
<summary>Loads an assembly from a byte array and binds its assembly name to it in the <seecref="T:System.Reflection.MetadataLoadContext" />. If a prior assembly with the same name was already loaded into the <seecref="T:System.Reflection.MetadataLoadContext" />, the prior assembly will be returned.</summary>
<paramname="assembly">A <seecref="T:System.IO.Stream" /> holding an assembly.</param>
312
+
<summary>Loads an assembly from a stream and binds its assembly name to it in the <seecref="T:System.Reflection.MetadataLoadContext" />. If a prior assembly with the same name was already loaded into the <seecref="T:System.Reflection.MetadataLoadContext" />, the prior assembly will be returned.</summary>
232
313
<returns>To be added.</returns>
233
-
<remarks>To be added.</remarks>
314
+
<remarks>
315
+
<formattype="text/markdown">
316
+
<![CDATA[
317
+
## Remarks
318
+
319
+
> [!IMPORTANT]
320
+
> The <xref:System.Reflection.MetadataLoadContext> takes ownership of the <xref:System.IO.Stream> passed into this method. The original owner must not mutate its position, dispose the <xref:System.IO.Stream>, or assume that its position will stay unchanged.
321
+
]]></format>
322
+
</remarks>
323
+
<exceptioncref="T:System.IO.FileLoadException">The two assemblies do not have the same Mvid.</exception>
0 commit comments