Skip to content

Port System.Reflection source comments to Docs #2317

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Apr 26, 2019
Merged

Port System.Reflection source comments to Docs #2317

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
00f416e
Port System.Reflection source comments to Docs
carlossanlop Apr 16, 2019
6c703cf
Fixed bad cref tag
Apr 17, 2019
d9ecc7e
Added description for type
Apr 17, 2019
a708973
Added type description and remarks.
Apr 17, 2019
0686adc
Apply suggestions from code review
Apr 18, 2019
f0674bb
Fixed broken xrefs
Apr 25, 2019
65cf654
Fixed bad cref.
Apr 25, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 11 additions & 10 deletions xml/System.Reflection/DispatchProxy.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@
</Base>
<Interfaces />
<Docs>
<summary>To be added.</summary>
<summary>Provides a mechanism for instantiating proxy objects and handling their method dispatch.</summary>
<remarks>To be added.</remarks>
</Docs>
<Members>
Expand Down Expand Up @@ -90,11 +90,12 @@
</TypeParameters>
<Parameters />
<Docs>
<typeparam name="T">To be added.</typeparam>
<typeparam name="TProxy">To be added.</typeparam>
<summary>To be added.</summary>
<returns>To be added.</returns>
<typeparam name="T">The interface the proxy should implement.</typeparam>
<typeparam name="TProxy">The base class to use for the proxy class.</typeparam>
<summary>Creates an object instance that derives from class <typeparamref name="TProxy" /> and implements interface <typeparamref name="T" />.</summary>
<returns>An object instance that implements <typeparamref name="T" />.</returns>
<remarks>To be added.</remarks>
<exception cref="T:System.ArgumentException"><typeparamref name="T" /> is a class, or <typeparamref name="TProxy" /> is sealed or does not have a parameterless constructor.</exception>
</Docs>
</Member>
<Member MemberName="Invoke">
Expand Down Expand Up @@ -127,12 +128,12 @@
<Parameter Name="args" Type="System.Object[]" />
</Parameters>
<Docs>
<param name="targetMethod">To be added.</param>
<param name="args">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="targetMethod">The method the caller invoked.</param>
<param name="args">The arguments the caller passed to the method.</param>
<summary>Whenever any method on the generated proxy type is called. Rhis method will be invoked to dispatch control.</summary>
<returns>The object to return to the caller, or <see langword="null" /> for void methods.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
</Members>
</Type>
</Type>
143 changes: 114 additions & 29 deletions xml/System.Reflection/MetadataLoadContext.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,16 @@
</Interface>
</Interfaces>
<Docs>
<summary>To be added.</summary>
<remarks>To be added.</remarks>
<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>
<remarks>
<format type="text/markdown"><![CDATA[

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.

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**).

]]></format>
</remarks>
</Docs>
<Members>
<Member MemberName=".ctor">
Expand All @@ -38,9 +46,9 @@
<Parameter Name="coreAssemblyName" Type="System.String" />
</Parameters>
<Docs>
<param name="resolver">To be added.</param>
<param name="coreAssemblyName">To be added.</param>
<summary>To be added.</summary>
<param name="resolver">A <see cref="T:System.Reflection.MetadataAssemblyResolver" /> instance.</param>
<param name="coreAssemblyName">The name of the assembly that contains the core types such as <see cref="T:System.Object" />. Typically, this would be "mscorlib".</param>
<summary>Creates a new <see cref="T:System.Reflection.MetadataLoadContext" /> object.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -60,9 +68,57 @@
<ReturnType>System.Reflection.Assembly</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
<summary>Gets or sets the assembly that denotes the "system assembly" that houses the well-known types such as <see cref="T:System.Int32" />.</summary>
<value>An <see cref="T:System.Reflection.Assembly" /> instance.</value>
<remarks>
<format type="text/markdown">
<![CDATA[
## Remarks

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.

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.

The <xref:System.Reflection.MetadataLoadContext.CoreAssembly> is determined by passing the coreAssemblyName parameter passed to the <xref:System.Reflection.MetadataAssemblyResolver> constructor
to the MetadataAssemblyResolver's <xref:System.Reflection.MetadataAssemblyResolver.Resolve> method.

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".

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.

Note that <xref:System.Runtime> is not an ideal core assembly as it excludes some of the interop-related pseudo-custom attribute types such as 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.

The CoreAssembly is not loaded until necessary. These APIs do not trigger the search for the core assembly:

* MetadataLoadContext.LoadFromStream()
* LoadFromAssemblyPath()
* LoadFromByteArray()
* Assembly.GetName()
* Assembly.FullName
* Assembly.GetReferencedAssemblies()
* Assembly.GetTypes()
* Assembly.DefinedTypes
* Assembly.GetExportedTypes()
* Assembly.GetForwardedTypes()
* Assembly.GetType(string, bool, bool)
* Type.Name
* Type.FullName
* Type.AssemblyQualifiedName

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:

* APIs that need to parse signatures or typespecs and return the results as Types will throw. For example:

* MethodBase.ReturnType
* MethodBase.GetParameters()
* Type.BaseType
* Type.GetInterfaces()

* APIs that need to compare types to well known core types will not throw and the comparison will evaluate to `false`. For example, if you do not specify a core assembly, <xref:Type.IsPrimitive> will return `false` for everything, even types named <xref:System.Int32>. Similarly, Type.GetTypeCode() will return <xref:TypeCode.Object> for everything.

* 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.
]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="Dispose">
Expand All @@ -85,7 +141,11 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added.</summary>
<summary>Releases any native resources (such as file locks on assembly files.) After disposal, it is not safe to use any Assembly objects dispensed by the <see cref="T:System.Reflection.MetadataLoadContext" />, nor any Reflection objects dispensed by those Assembly objects.

Though objects provided by the <see cref="T:System.Reflection.MetadataLoadContext" /> strive to throw an <see cref="T:System.ObjectDisposedException" />, this is not guaranteed.

Some APIs may return fixed or previously cached data. Accessing objects *during* a <see cref="M:System.Reflection.MetadataLoadContext.Dispose" /> may result in an unmanaged access violation and failfast.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -106,8 +166,8 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added.</summary>
<returns>To be added.</returns>
<summary>Return an atomic snapshot of the assemblies that have been loaded into the <see cref="T:System.Reflection.MetadataLoadContext" />.</summary>
<returns>An <see cref="T:System.Collections.Generic.IEnumerable&lt;System.Reflection.Assembly&gt;" /> instance.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -129,10 +189,16 @@
<Parameter Name="assemblyName" Type="System.Reflection.AssemblyName" />
</Parameters>
<Docs>
<param name="assemblyName">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<param name="assemblyName">An <see cref="T:System.Reflection.AssemblyName" /> instance.</param>
<summary>Resolves the supplied assembly name to an assembly. If an assembly was previously bound by to this name, that assembly is returned. Otherwise, the <see cref="T:System.Reflection.MetadataLoadContext" /> calls the specified <see cref="T:System.Reflection.MetadataAssemblyResolver" />.</summary>
<returns>A <see cref="T:System.Reflection.Assembly" /> instance.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
Note that the behavior of this method matches the behavior of AssemblyLoadContext.LoadFromAssemblyName() resolve event but does not match the behavior of Assembly.ReflectionOnlyLoad(). (the latter gives up without raising its resolve event.)
]]></format>
</remarks>
<exception cref="T:System.IO.FileNotFoundException">Thrown if the resolver returns <see langword="null" />.</exception>
</Docs>
</Member>
<Member MemberName="LoadFromAssemblyName">
Expand All @@ -154,10 +220,18 @@
<Parameter Name="assemblyName" Type="System.String" />
</Parameters>
<Docs>
<param name="assemblyName">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<param name="assemblyName">A <see cref="T:System.String" /> representing the assembly name.</param>
<summary>Resolves the supplied assembly name to an assembly. If an assembly was previously bound by to this name, that assembly is returned. Otherwise, the <see cref="T:System.Reflection.MetadataLoadContext" /> calls the specified <see cref="T:System.Reflection.MetadataAssemblyResolver" />.</summary>
<returns>A <see cref="T:System.Reflection.Assembly" /> instance.</returns>
<remarks>
<format type="text/markdown">
<![CDATA[
## Remarks
Note that the behavior of this method matches the behavior of AssemblyLoadContext.LoadFromAssemblyName() resolve event but does not match the behavior of Assembly.ReflectionOnlyLoad(). (the latter gives up without raising its resolve event.)
]]>
</format>
</remarks>
<exception cref="T:System.IO.FileNotFoundException">Thrown i the resolver returns <see langword="null" />.</exception>
</Docs>
</Member>
<Member MemberName="LoadFromAssemblyPath">
Expand All @@ -179,10 +253,11 @@
<Parameter Name="assemblyPath" Type="System.String" />
</Parameters>
<Docs>
<param name="assemblyPath">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="assemblyPath">A <see cref="T:System.String" /> representing the path to the assembly.</param>
<summary>Loads an assembly from a specific path on the disk and binds its assembly name to it in the <see cref="T:System.Reflection.MetadataLoadContext" />. If a prior assembly with the same name was already loaded into the <see cref="T:System.Reflection.MetadataLoadContext" />, the prior assembly will be returned.</summary>
<returns>A <see cref="T:System.Reflection.Assembly" /> instance.</returns>
<remarks>To be added.</remarks>
<exception cref="T:System.IO.FileLoadException">Thrown if the two assemblies do not have the same Mvid.</exception>
</Docs>
</Member>
<Member MemberName="LoadFromByteArray">
Expand All @@ -203,10 +278,11 @@
<Parameter Name="assembly" Type="System.Byte[]" />
</Parameters>
<Docs>
<param name="assembly">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="assembly">A <see cref="T:System.Byte[]" /> holding an assembly.</param>
<summary>Loads an assembly from a byte array and binds its assembly name to it in the <see cref="T:System.Reflection.MetadataLoadContext" />. If a prior assembly with the same name was already loaded into the <see cref="T:System.Reflection.MetadataLoadContext" />, the prior assembly will be returned.</summary>
<returns>A <see cref="T:System.Reflection.Assembly" /> instance.</returns>
<remarks>To be added.</remarks>
<exception cref="T:System.IO.FileLoadException">Thrown if the two assemblies do not have the same Mvid.</exception>
</Docs>
</Member>
<Member MemberName="LoadFromStream">
Expand All @@ -227,11 +303,20 @@
<Parameter Name="assembly" Type="System.IO.Stream" />
</Parameters>
<Docs>
<param name="assembly">To be added.</param>
<summary>To be added.</summary>
<param name="assembly">A <see cref="T:System.IO.Stream" /> holding an assembly.</param>
<summary>Loads an assembly from a stream and binds its assembly name to it in the <see cref="T:System.Reflection.MetadataLoadContext" />. If a prior assembly with the same name was already loaded into the <see cref="T:System.Reflection.MetadataLoadContext" />, the prior assembly will be returned.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<remarks>
<format type="text/markdown">
<![CDATA[
## Remarks

> [!IMPORTANT]
> 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.
]]></format>
</remarks>
<exception cref="T:System.IO.FileLoadException">Thrown if the two assemblies do not have the same Mvid.</exception>
</Docs>
</Member>
</Members>
</Type>
</Type>