From 00f416e2c911323387f0a36a326f4d14e8ef5f91 Mon Sep 17 00:00:00 2001 From: Carlos Sanchez Lopez Date: Tue, 16 Apr 2019 12:24:18 -0700 Subject: [PATCH 1/7] Port System.Reflection source comments to Docs --- xml/System.Reflection/DispatchProxy.xml | 17 +-- xml/System.Reflection/MetadataLoadContext.xml | 129 ++++++++++++++---- 2 files changed, 112 insertions(+), 34 deletions(-) diff --git a/xml/System.Reflection/DispatchProxy.xml b/xml/System.Reflection/DispatchProxy.xml index 985695713cd..8fbf2df7933 100644 --- a/xml/System.Reflection/DispatchProxy.xml +++ b/xml/System.Reflection/DispatchProxy.xml @@ -90,11 +90,12 @@ - To be added. - To be added. - To be added. - To be added. + The interface the proxy should implement. + The base class to use for the proxy class. + Creates an object instance that derives from class and implements interface . + An object instance that implements . To be added. + is a class, or is sealed or does not have a parameterless constructor. @@ -127,10 +128,10 @@ - To be added. - To be added. - To be added. - To be added. + The method the caller invoked. + The arguments the caller passed to the method. + Whenever any method on the generated proxy type is called. Rhis method will be invoked to dispatch control. + The object to return to the caller, or for void methods. To be added. diff --git a/xml/System.Reflection/MetadataLoadContext.xml b/xml/System.Reflection/MetadataLoadContext.xml index 5e9033271dd..1c9e2d64789 100644 --- a/xml/System.Reflection/MetadataLoadContext.xml +++ b/xml/System.Reflection/MetadataLoadContext.xml @@ -38,9 +38,9 @@ - To be added. - To be added. - To be added. + A instance. + The name of the assembly that contains the core types such as . Typically, this would be "mscorlib". + Creates a new object. To be added. @@ -60,9 +60,57 @@ System.Reflection.Assembly - To be added. - To be added. - To be added. + Gets or sets the assembly that denotes the "system assembly" that houses the well-known types such as . + An instance. + + + is determined by passing the coreAssemblyName parameter passed to the constructor +to the MetadataAssemblyResolver's method. + +If no coreAssemblyName argument was specified in the constructor of , 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 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 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, will return `false` for everything, even types named . Similarly, Type.GetTypeCode() will return 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 will not throw. It will omit the pseudo-custom attribute from the list of returned attributes. + ]]> + @@ -85,7 +133,11 @@ - To be added. + 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 , nor any Reflection objects dispensed by those Assembly objects. + +Though objects provided by the strive to throw an , this is not guaranteed. + +Some APIs may return fixed or previously cached data. Accessing objects *during* a may result in an unmanaged access violation and failfast. To be added. @@ -106,8 +158,8 @@ - To be added. - To be added. + Return an atomic snapshot of the assemblies that have been loaded into the . + An instance. To be added. @@ -129,10 +181,16 @@ - To be added. - To be added. - To be added. - To be added. + An instance. + Resolves the supplied assembly name to an assembly. If an assembly was previously bound by to this name, that assembly is returned. Otherwise, the calls the specified . + A instance. + + + + Thrown if the resolver returns . @@ -154,10 +212,18 @@ - To be added. - To be added. - To be added. - To be added. + A representing the assembly name. + Resolves the supplied assembly name to an assembly. If an assembly was previously bound by to this name, that assembly is returned. Otherwise, the calls the specified . + A instance. + + + + + + Thrown i the resolver returns . @@ -179,10 +245,11 @@ - To be added. - To be added. - To be added. + A representing the path to the assembly. + Loads an assembly from a specific path on the disk and binds its assembly name to it in the . If a prior assembly with the same name was already loaded into the , the prior assembly will be returned. + A instance. To be added. + Thrown if the two assemblies do not have the same Mvid. @@ -203,10 +270,11 @@ - To be added. - To be added. - To be added. + A holding an assembly. + Loads an assembly from a byte array and binds its assembly name to it in the . If a prior assembly with the same name was already loaded into the , the prior assembly will be returned. + A instance. To be added. + Thrown if the two assemblies do not have the same Mvid. @@ -227,10 +295,19 @@ - To be added. - To be added. + A holding an assembly. + Loads an assembly from a stream and binds its assembly name to it in the . If a prior assembly with the same name was already loaded into the , the prior assembly will be returned. To be added. - To be added. + + + [!IMPORTANT] +> The takes ownership of the passed into this method. The original owner must not mutate its position, dispose the or assume that its position will stay unchanged. + ]]> + + Thrown if the two assemblies do not have the same Mvid. From 6c703cfef361fc220755aeddc6a0b14e5cea0594 Mon Sep 17 00:00:00 2001 From: Ron Petrusha Date: Wed, 17 Apr 2019 13:05:46 -0700 Subject: [PATCH 2/7] Fixed bad cref tag --- xml/System.Reflection/MetadataLoadContext.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/xml/System.Reflection/MetadataLoadContext.xml b/xml/System.Reflection/MetadataLoadContext.xml index 1c9e2d64789..955a25fa3cb 100644 --- a/xml/System.Reflection/MetadataLoadContext.xml +++ b/xml/System.Reflection/MetadataLoadContext.xml @@ -38,7 +38,7 @@ - A instance. + A instance. The name of the assembly that contains the core types such as . Typically, this would be "mscorlib". Creates a new object. To be added. @@ -311,4 +311,4 @@ Note that the behavior of this method matches the behavior of AssemblyLoadContex - \ No newline at end of file + From d9ecc7eec07cfcb62979a3ebf99d291da610c73b Mon Sep 17 00:00:00 2001 From: Ron Petrusha Date: Wed, 17 Apr 2019 13:13:04 -0700 Subject: [PATCH 3/7] Added description for type --- xml/System.Reflection/DispatchProxy.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/xml/System.Reflection/DispatchProxy.xml b/xml/System.Reflection/DispatchProxy.xml index 8fbf2df7933..77ad26c46a0 100644 --- a/xml/System.Reflection/DispatchProxy.xml +++ b/xml/System.Reflection/DispatchProxy.xml @@ -24,7 +24,7 @@ - To be added. + Provides a mechanism for instantiating proxy objects and handling their method dispatch. To be added. @@ -136,4 +136,4 @@ - \ No newline at end of file + From a7089738af7e17ef6f391dad1ce36994255c0fc5 Mon Sep 17 00:00:00 2001 From: Ron Petrusha Date: Wed, 17 Apr 2019 15:07:19 -0700 Subject: [PATCH 4/7] Added type description and remarks. --- xml/System.Reflection/MetadataLoadContext.xml | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/xml/System.Reflection/MetadataLoadContext.xml b/xml/System.Reflection/MetadataLoadContext.xml index 955a25fa3cb..e5e6a386af1 100644 --- a/xml/System.Reflection/MetadataLoadContext.xml +++ b/xml/System.Reflection/MetadataLoadContext.xml @@ -18,8 +18,16 @@ - To be added. - To be added. + 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. + + 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**). + + ]]> + From 0686adc76d9643b7417759373181982d552577c4 Mon Sep 17 00:00:00 2001 From: Ron Petrusha Date: Thu, 18 Apr 2019 12:37:36 -0700 Subject: [PATCH 5/7] Apply suggestions from code review Applying suggestions by rpetrusha in PR. Co-Authored-By: carlossanlop <1175054+carlossanlop@users.noreply.github.com> --- xml/System.Reflection/MetadataLoadContext.xml | 82 +++++++++---------- 1 file changed, 41 insertions(+), 41 deletions(-) diff --git a/xml/System.Reflection/MetadataLoadContext.xml b/xml/System.Reflection/MetadataLoadContext.xml index e5e6a386af1..e5c24b25d9d 100644 --- a/xml/System.Reflection/MetadataLoadContext.xml +++ b/xml/System.Reflection/MetadataLoadContext.xml @@ -77,44 +77,44 @@ Assemblies are treated strictly as metadata. There are no restrictions on loadin 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. +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. -The is determined by passing the coreAssemblyName parameter passed to the constructor -to the MetadataAssemblyResolver's method. +The `CoreAssembly` is determined by passing the `coreAssemblyName` parameter passed to the constructor +to the method. -If no coreAssemblyName argument was specified in the constructor of , then default values are used including "mscorlib", "System.Runtime" and "netstandard". +If no `coreAssemblyName` argument was specified in the constructor of , 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 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. +Note that is not an ideal core assembly because it excludes some of the interop-related pseudo-custom attribute types such as . 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: +The core assembly is not loaded until necessary. The following 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 as follows: -* APIs that need to parse signatures or typespecs and return the results as Types will throw. For example: +* APIs that need to parse signatures or typespecs and return the results as objects will throw an exception. For example: - * MethodBase.ReturnType - * MethodBase.GetParameters() - * Type.BaseType - * Type.GetInterfaces() + * + * System.Reflection.MethodBase.GetParameters%2A?displayProperty=nameWithType> + * + * -* 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, will return `false` for everything, even types named . Similarly, Type.GetTypeCode() will return for everything. +* 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, will return `false` for everything, even types named . Similarly, will return 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 will not throw. It will omit the pseudo-custom attribute from the list of returned attributes. ]]> @@ -141,7 +141,7 @@ If a core assembly cannot be found or if the core assembly is missing types, thi - 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 , nor any Reflection objects dispensed by those Assembly objects. + Releases any native resources (such as file locks on assembly files). After disposal, it is not safe to use any objects dispensed by the , nor any reflection objects dispensed by those objects. Though objects provided by the strive to throw an , this is not guaranteed. @@ -190,15 +190,15 @@ Some APIs may return fixed or previously cached data. Accessing objects *during* An instance. - Resolves the supplied assembly name to an assembly. If an assembly was previously bound by to this name, that assembly is returned. Otherwise, the calls the specified . - A instance. + Resolves the supplied assembly name to an assembly. If an assembly was previously bound to this name, that assembly is returned. Otherwise, the calls the specified . + An instance. resolve event but does not match the behavior of . (The latter gives up without raising its resolve event.) ]]> - Thrown if the resolver returns . + The resolver returns . @@ -221,17 +221,17 @@ Note that the behavior of this method matches the behavior of AssemblyLoadContex A representing the assembly name. - Resolves the supplied assembly name to an assembly. If an assembly was previously bound by to this name, that assembly is returned. Otherwise, the calls the specified . - A instance. + Resolves the supplied assembly name to an assembly. If an assembly was previously bound to this name, that assembly is returned. Otherwise, the calls the specified . + An instance. resolve event but does not match the behavior of . (The latter gives up without raising its resolve event.) ]]> - Thrown i the resolver returns . + The resolver returns . @@ -255,9 +255,9 @@ Note that the behavior of this method matches the behavior of AssemblyLoadContex A representing the path to the assembly. Loads an assembly from a specific path on the disk and binds its assembly name to it in the . If a prior assembly with the same name was already loaded into the , the prior assembly will be returned. - A instance. + An instance. To be added. - Thrown if the two assemblies do not have the same Mvid. + The two assemblies do not have the same Mvid. @@ -280,9 +280,9 @@ Note that the behavior of this method matches the behavior of AssemblyLoadContex A holding an assembly. Loads an assembly from a byte array and binds its assembly name to it in the . If a prior assembly with the same name was already loaded into the , the prior assembly will be returned. - A instance. + An instance. To be added. - Thrown if the two assemblies do not have the same Mvid. + The two assemblies do not have the same Mvid. @@ -312,10 +312,10 @@ Note that the behavior of this method matches the behavior of AssemblyLoadContex ## Remarks > [!IMPORTANT] -> The takes ownership of the passed into this method. The original owner must not mutate its position, dispose the or assume that its position will stay unchanged. +> The takes ownership of the passed into this method. The original owner must not mutate its position, dispose the , or assume that its position will stay unchanged. ]]> - Thrown if the two assemblies do not have the same Mvid. + The two assemblies do not have the same Mvid. From f0674bb7036a6739e650414b78dbf32fcac5eed9 Mon Sep 17 00:00:00 2001 From: Ron Petrusha Date: Thu, 25 Apr 2019 12:28:03 -0700 Subject: [PATCH 6/7] Fixed broken xrefs --- xml/System.Reflection/MetadataLoadContext.xml | 21 ++++++++++++------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/xml/System.Reflection/MetadataLoadContext.xml b/xml/System.Reflection/MetadataLoadContext.xml index e5c24b25d9d..39d87899aa7 100644 --- a/xml/System.Reflection/MetadataLoadContext.xml +++ b/xml/System.Reflection/MetadataLoadContext.xml @@ -80,7 +80,7 @@ The core assembly is treated differently than other assemblies because reference 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. The `CoreAssembly` is determined by passing the `coreAssemblyName` parameter passed to the constructor -to the method. +to the method. If no `coreAssemblyName` argument was specified in the constructor of , then default values are used, including "mscorlib", "System.Runtime" and "netstandard". @@ -92,7 +92,7 @@ The core assembly is not loaded until necessary. The following APIs do not trigg * * -* +* * * * @@ -109,12 +109,12 @@ If a core assembly cannot be found or if the core assembly is missing types, thi * APIs that need to parse signatures or typespecs and return the results as objects will throw an exception. For example: - * + * * System.Reflection.MethodBase.GetParameters%2A?displayProperty=nameWithType> * * -* 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, will return `false` for everything, even types named . Similarly, will return for everything. +* 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, will return `false` for everything, even types named . Similarly, will return 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 will not throw. It will omit the pseudo-custom attribute from the list of returned attributes. ]]> @@ -141,12 +141,17 @@ If a core assembly cannot be found or if the core assembly is missing types, thi - Releases any native resources (such as file locks on assembly files). After disposal, it is not safe to use any objects dispensed by the , nor any reflection objects dispensed by those objects. + Releases any native resources (such as file locks on assembly files). + + strive to throw an , this is not guaranteed. +After disposal, it is not safe to use any objects dispensed by the or any reflection objects dispensed by those objects. -Some APIs may return fixed or previously cached data. Accessing objects *during* a may result in an unmanaged access violation and failfast. - To be added. +Though objects provided by the strive to throw an , this is not guaranteed. + +Some APIs may return fixed or previously cached data. Accessing objects *during* a method call may result in an unmanaged access violation and failfast. + ]]> + From 65cf65484ff41fe4cdea1aa8a0b99f70eed59e2a Mon Sep 17 00:00:00 2001 From: Ron Petrusha Date: Thu, 25 Apr 2019 12:32:23 -0700 Subject: [PATCH 7/7] Fixed bad cref. --- xml/System.Reflection/MetadataLoadContext.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xml/System.Reflection/MetadataLoadContext.xml b/xml/System.Reflection/MetadataLoadContext.xml index 39d87899aa7..fbf36ff50b0 100644 --- a/xml/System.Reflection/MetadataLoadContext.xml +++ b/xml/System.Reflection/MetadataLoadContext.xml @@ -172,7 +172,7 @@ Some APIs may return fixed or previously cached data. Accessing objects *during* Return an atomic snapshot of the assemblies that have been loaded into the . - An instance. + An enumerable collection of objects. To be added.