Add documentation to the various reflection apis which directly interact with CurrentContextualReflectionContext (#11687)

Author: davidwrighton

xml/System.Reflection.Emit/AssemblyBuilder.xml

@@ -442,7 +442,7 @@ The following code example shows how to define and use a dynamic assembly. The e
         <param name="access">The access rights of the assembly.</param>
         <summary>Defines a dynamic assembly that has the specified name and access rights.</summary>
         <returns>An object that represents the new assembly.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>.NET 6+ only: If the <see cref="P:System.Runtime.Loader.AssemblyLoadContext.CurrentContextualReflectionContext" /> property is null, then the assembly is created in the <see cref="T:System.Runtime.Loader.AssemblyLoadContext" /> of the function that calls DefineDynamicAssembly. Otherwise, it's created with the <see cref="T:System.Runtime.Loader.AssemblyLoadContext" /> specified in <see cref="P:System.Runtime.Loader.AssemblyLoadContext.CurrentContextualReflectionContext" />.</remarks>
       </Docs>
     </Member>
     <Member MemberName="DefineDynamicAssembly">
@@ -505,9 +505,9 @@ The following code example shows how to define and use a dynamic assembly. The e
         <param name="name">The name of the assembly.</param>
         <param name="access">The access rights of the assembly.</param>
         <param name="assemblyAttributes">A collection that contains the attributes of the assembly.</param>
-        <summary>Defines a new assembly that has the specified name, access rights, and attributes.</summary>
+        <summary>Defines a dynamic assembly that has the specified name, access rights, and attributes.</summary>
         <returns>An object that represents the new assembly.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>.NET 6+ only: If the <see cref="P:System.Runtime.Loader.AssemblyLoadContext.CurrentContextualReflectionContext" /> property is null, then the assembly is created in the <see cref="T:System.Runtime.Loader.AssemblyLoadContext" /> of the function that calls DefineDynamicAssembly. Otherwise, it's created with the <see cref="T:System.Runtime.Loader.AssemblyLoadContext" /> specified in <see cref="P:System.Runtime.Loader.AssemblyLoadContext.CurrentContextualReflectionContext" />.</remarks>
       </Docs>
     </Member>
     <MemberGroup MemberName="DefineDynamicModule">

xml/System.Reflection/Assembly.xml

@@ -3241,6 +3241,8 @@ Note: In <see href="https://go.microsoft.com/fwlink/?LinkID=247912">.NET for Win
 ## Remarks
  This method only searches the current assembly instance. The `name` parameter includes the namespace but not the assembly. To search other assemblies for a type, use the <xref:System.Type.GetType%28System.String%29?displayProperty=nameWithType> method overload, which can optionally include an assembly display name as part of the type name.
 
+ In .NET Core/.NET 5+, if there are assembly-qualified generic type parameters in the type name string, those assembly references will be loaded by the <xref:System.Runtime.Loader.AssemblyLoadContext> of the method that called Assembly.GetType, or by the <xref:System.Runtime.Loader.AssemblyLoadContext.CurrentContextualReflectionContext%2A?displayProperty=nameWithType> context if it's set.
+
 > [!NOTE]
 >  If the type has been forwarded to another assembly, it is still returned by this method. For information on type forwarding, see [Type Forwarding in the Common Language Runtime](/dotnet/standard/assembly/type-forwarding).
 
@@ -3345,6 +3347,8 @@ Note: In <see href="https://go.microsoft.com/fwlink/?LinkID=247912">.NET for Win
 ## Remarks
  This method only searches the current assembly instance. The `name` parameter includes the namespace but not the assembly. To search other assemblies for a type, use the <xref:System.Type.GetType%28System.String%29?displayProperty=nameWithType> method overload, which can optionally include an assembly display name as part of the type name.
 
+ In .NET Core/.NET 5+, if there are assembly-qualified generic type parameters in the type name string, those assembly references will be loaded by the <xref:System.Runtime.Loader.AssemblyLoadContext> of the method that called Assembly.GetType, or by the <xref:System.Runtime.Loader.AssemblyLoadContext.CurrentContextualReflectionContext%2A?displayProperty=nameWithType> context if it's set.
+
 > [!NOTE]
 >  If the type has been forwarded to another assembly, it is still returned by this method. For information on type forwarding, see [Type Forwarding in the Common Language Runtime](/dotnet/standard/assembly/type-forwarding).
 
@@ -3450,6 +3454,8 @@ Note: In <see href="https://go.microsoft.com/fwlink/?LinkID=247912">.NET for Win
 ## Remarks
  This method only searches the current assembly instance. The `name` parameter includes the namespace but not the assembly. To search other assemblies for a type, use the <xref:System.Type.GetType%28System.String%29?displayProperty=nameWithType> method overload, which can optionally include an assembly display name as part of the type name.
 
+ In .NET Core/.NET 5+, if there are assembly-qualified generic type parameters in the type name string, those assembly references will be loaded by the <xref:System.Runtime.Loader.AssemblyLoadContext> of the method that called Assembly.GetType, or by the <xref:System.Runtime.Loader.AssemblyLoadContext.CurrentContextualReflectionContext%2A?displayProperty=nameWithType> context if it's set.
+
 > [!NOTE]
 >  If the type has been forwarded to another assembly, it is still returned by this method. For information on type forwarding, see [Type Forwarding in the Common Language Runtime](/dotnet/standard/assembly/type-forwarding).
 
@@ -4097,7 +4103,7 @@ This property is marked obsolete starting in .NET 5, and generates a compile-tim
 
 ## Remarks
 
-In .NET Core/.NET 5+, the target assembly will be loaded into the current <xref:System.Runtime.Loader.AssemblyLoadContext>. For more information on assembly loading, see [Managed assembly loading algorithm](/dotnet/core/dependency-loading/loading-managed#algorithm").
+ In .NET Core/.NET 5+, the target assembly will be loaded into the current <xref:System.Runtime.Loader.AssemblyLoadContext> or into the <xref:System.Runtime.Loader.AssemblyLoadContext.CurrentContextualReflectionContext%2A?displayProperty=nameWithType> context if it's set. For more information on assembly loading, see [Managed assembly loading algorithm](/dotnet/core/dependency-loading/loading-managed#algorithm).
 
 > [!NOTE]
 > **.NET Framework only:** For information about loading assemblies from remote locations, see [`<loadFromRemoteSources>`](/dotnet/framework/configure-apps/file-schema/runtime/loadfromremotesources-element).
@@ -4191,7 +4197,7 @@ Note: In <see href="https://go.microsoft.com/fwlink/?LinkID=247912">.NET for Win
 
 ## Remarks
 
-In .NET Core/5+, the target assembly is loaded into the current <xref:System.Runtime.Loader.AssemblyLoadContext>. For more information on assembly loading, see [Managed assembly loading algorithm](/dotnet/core/dependency-loading/loading-managed#algorithm").
+ In .NET Core/.NET 5+, the target assembly will be loaded into the current <xref:System.Runtime.Loader.AssemblyLoadContext> or into the <xref:System.Runtime.Loader.AssemblyLoadContext.CurrentContextualReflectionContext%2A?displayProperty=nameWithType> context if it's set. For more information on assembly loading, see [Managed assembly loading algorithm](/dotnet/core/dependency-loading/loading-managed#algorithm).
 
 To load the correct assembly, it's recommended to call the `Load` method by passing the long form of the assembly name. The long form of an assembly name consists of its simple name (such as "System" for the System.dll assembly) along with its version, culture, public key token, and optionally its processor architecture. It corresponds to the assembly's <xref:System.Reflection.Assembly.FullName%2A> property. The following example illustrates the use of a long name to load the System.dll assembly for .NET Framework 4:
 
@@ -5571,6 +5577,8 @@ The assembly is loaded into the default AssemblyLoadContext. For more informatio
 
  Applications that load assemblies with this method will be affected by upgrades of those assemblies. Therefore, do not use this method; redesign the application to use the <xref:System.Reflection.Assembly.Load%28System.String%29> method overload or the <xref:System.Reflection.Assembly.LoadFrom%28System.String%29> method overload.
 
+ In .NET Core/5+, the target assembly is loaded into the current <xref:System.Runtime.Loader.AssemblyLoadContext> or the <xref:System.Runtime.Loader.AssemblyLoadContext.CurrentContextualReflectionContext%2A?displayProperty=nameWithType> if it's set.
+
  This method first calls <xref:System.Reflection.Assembly.Load%2A>. If the assembly is not found, this method returns the assembly from the global assembly cache that has the same simple name, and the highest version number.
 
  ]]></format>

xml/System/Activator.xml

@@ -574,6 +574,8 @@ Note: In <see href="https://go.microsoft.com/fwlink/?LinkID=247912">.NET for Win
 
  For more information on how the common language runtime identifies and loads assemblies, see [How the Runtime Locates Assemblies](/dotnet/framework/deployment/how-the-runtime-locates-assemblies). For information on using the application configuration file to define assembly locations, see [Specifying an Assembly's Location](/dotnet/framework/configure-apps/specify-assembly-location). If `assemblyName` is found, it is loaded in the default context.
 
+ In .NET Core 3.0 and later versions, assembly loads triggered by this API are affected by the current value of <xref:System.Runtime.Loader.AssemblyLoadContext.CurrentContextualReflectionContext%2A?displayProperty=nameWithType>.
+
 > [!NOTE]
 > This method can be used to create nonpublic types if the caller has been granted <xref:System.Security.Permissions.ReflectionPermission> with the <xref:System.Security.Permissions.ReflectionPermissionFlag.RestrictedMemberAccess?displayProperty=nameWithType> flag and if the grant set of the assembly that contains the nonpublic types is restricted to the caller's grant set or to a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later.
 
@@ -1018,6 +1020,8 @@ Note: In <see href="https://go.microsoft.com/fwlink/?LinkID=247912">.NET for Win
 ## Remarks
  Use <xref:System.Runtime.Remoting.ObjectHandle.Unwrap%2A?displayProperty=nameWithType> to unwrap the return value.
 
+ In .NET Core 3.0 and later versions, assembly loads triggered by this API are affected by the current value of <xref:System.Runtime.Loader.AssemblyLoadContext.CurrentContextualReflectionContext%2A?displayProperty=nameWithType>.
+
 > [!NOTE]
 > This method can be used to create nonpublic types if the caller has been granted <xref:System.Security.Permissions.ReflectionPermission> with the <xref:System.Security.Permissions.ReflectionPermissionFlag.RestrictedMemberAccess?displayProperty=nameWithType> flag and if the grant set of the nonpublic types is restricted to the caller's grant set or to a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later.
 
@@ -1493,6 +1497,8 @@ An error occurred when attempting remote activation in a target specified in <pa
 ## Remarks
  Use <xref:System.Runtime.Remoting.ObjectHandle.Unwrap%2A?displayProperty=nameWithType> to unwrap the return value.
 
+ In .NET Core 3.0 and later versions, assembly loads triggered by this API are affected by the current value of <xref:System.Runtime.Loader.AssemblyLoadContext.CurrentContextualReflectionContext%2A?displayProperty=nameWithType>.
+
 > [!NOTE]
 > This method can be used to create nonpublic types and members if the caller has been granted <xref:System.Security.Permissions.ReflectionPermission> with the <xref:System.Security.Permissions.ReflectionPermissionFlag.RestrictedMemberAccess?displayProperty=nameWithType> flag and if the grant set of the assembly that contains the nonpublic types and members is restricted to the caller's grant set or to a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later.