Skip to content
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

Adjust remarks for Assembly.Load on .NET Core #9764

Merged
merged 9 commits into from
Oct 24, 2024
Merged

Adjust remarks for Assembly.Load on .NET Core #9764

Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
38029a8
Adjust remarks for Assembly.Load on .NET Core
agocke Mar 26, 2024
3610c3e
Attempt to fix up problems
agocke Apr 16, 2024
e78a4cc
Mark API as unsupported
agocke Apr 16, 2024
87bf285
Fix xrefs
agocke Apr 16, 2024
9fafa66
Respond to PR comments
agocke Aug 30, 2024
870fff0
Merge remote-tracking branch 'upstream/main' into add-netcore-remarks
agocke Aug 30, 2024
dbe92d0
Apply suggestions from code review
agocke Aug 30, 2024
75d9b2f
Apply suggestions from code review
gewarren Oct 24, 2024
5607fe4
Update xml/System.Reflection/Assembly.xml
gewarren Oct 24, 2024
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
25 changes: 21 additions & 4 deletions xml/System.Reflection/Assembly.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4044,9 +4044,11 @@ This property is marked obsolete starting in .NET 5, and generates a compile-tim
<format type="text/markdown"><![CDATA[

## Remarks
<xref:System.IO.FileLoadException> is thrown if `assemblyRef` specifies the full assembly name and the first assembly that matches the simple name has a different version, culture, or public key token. The loader does not continue probing for other assemblies that match the simple name.

**.NET Framework only:** See [`<loadFromRemoteSources>`](/dotnet/framework/configure-apps/file-schema/runtime/loadfromremotesources-element) for loading assemblies from remote locations.
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").

> [!NOTE]
> **.NET Framework only:** For information about loading assemblies from remote locations, see [`<loadFromRemoteSources>`](/dotnet/framework/configure-apps/file-schema/runtime/loadfromremotesources-element).

> [!NOTE]
> **.NET Framework only:** Do not use an <xref:System.Reflection.AssemblyName> with only the <xref:System.Reflection.AssemblyName.CodeBase%2A> property set. The <xref:System.Reflection.AssemblyName.CodeBase%2A> property does not supply any elements of the assembly identity (such as name or version), so loading does not occur according to load-by-identity rules, as you would expect from the <xref:System.Reflection.Assembly.Load%2A> method. Instead, the assembly is loaded using load-from rules. For information about the disadvantages of using the load-from context, see the <xref:System.Reflection.Assembly.LoadFrom%2A?displayProperty=nameWithType> method overload or [Best Practices for Assembly Loading](/dotnet/framework/deployment/best-practices-for-assembly-loading).
Expand Down Expand Up @@ -4137,6 +4139,9 @@ Note: In <see href="https://go.microsoft.com/fwlink/?LinkID=247912">.NET for Win
<format type="text/markdown"><![CDATA[

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

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 the .NET Framework 4:

:::code language="csharp" source="~/snippets/csharp/System.Reflection/Assembly/Load/load11.cs" id="Snippet1":::
Expand Down Expand Up @@ -4241,6 +4246,8 @@ To load the correct assembly, it's recommended to call the `Load` method by pass

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

This method overload always creates a new <xref:System.Reflection.Assembly> object in its own isolated load context.

**.NET Framework only:** The trust level of an assembly that is loaded by using this method is the same as the trust level of the calling assembly. To load an assembly from a byte array with the trust level of the application domain, use the <xref:System.Reflection.Assembly.Load%28System.Byte%5B%5D%2CSystem.Byte%5B%5D%2CSystem.Security.SecurityContextSource%29> method overload. For more information about the use of evidence with overloads of the <xref:System.Reflection.Assembly.Load%2A> method that take byte arrays, see the <xref:System.Reflection.Assembly.Load%28System.Byte%5B%5D%2CSystem.Byte%5B%5D%2CSystem.Security.Policy.Evidence%29> method overload.
Expand Down Expand Up @@ -4631,6 +4638,11 @@ The assembly is loaded using the supplied evidence. The raw bytes representing t
<format type="text/markdown"><![CDATA[

## Remarks

This API is present in .NET Core for compatibility, but it is recommended to use <xref:System.Runtime.Loader.AssemblyLoadContext> overloads in .NET Core 2.0 and later.

The assembly is loaded into a new AssemblyLoadContext created for this purpose. For more information on assembly loading, see [Managed assembly loading algorithm](/dotnet/core/dependency-loading/loading-managed#algorithm").

Use the <xref:System.Reflection.Assembly.LoadFile%2A> method to load and examine assemblies that have the same identity, but are located in different paths. <xref:System.Reflection.Assembly.LoadFile%2A> does not load files into the load-from context, and does not resolve dependencies using the load path, as the <xref:System.Reflection.Assembly.LoadFrom%2A> method does. <xref:System.Reflection.Assembly.LoadFile%2A> is useful in this limited scenario because <xref:System.Reflection.Assembly.LoadFrom%2A> cannot be used to load assemblies that have the same identities but different paths; it will load only the first such assembly.

**.NET Framework only:** See [`<loadFromRemoteSources>`](/dotnet/framework/configure-apps/file-schema/runtime/loadfromremotesources-element) for loading assemblies from remote locations.
Expand Down Expand Up @@ -4797,10 +4809,15 @@ See [`<loadFromRemoteSources>`](/dotnet/framework/configure-apps/file-schema/run
<format type="text/markdown"><![CDATA[

## Remarks

This API is present in .NET Core for compatibility, but it is recommended to use <xref:System.Runtime.Loader.AssemblyLoadContext> overloads in .NET Core 2.0 and later.

The assembly is loaded into the default AssemblyLoadContext. For more information on assembly loading, see [Managed assembly loading algorithm](/dotnet/core/dependency-loading/loading-managed#algorithm").

The `assemblyFile` parameter must refer to a URI without escape characters. This method supplies escape characters for all invalid characters in the URI.

> [!NOTE]
> File transfer protocol (FTP) is not supported. If the URI supplied for `assemblyFile` is an FTP address, the assembly is not loaded. No exception is thrown.
> .NET Framework only: File transfer protocol (FTP) is not supported. If the URI supplied for `assemblyFile` is an FTP address, the assembly is not loaded. No exception is thrown.

`assemblyFile` may be absolute or relative to the current directory.

Expand Down Expand Up @@ -5051,7 +5068,7 @@ See [`<loadFromRemoteSources>`](/dotnet/framework/configure-apps/file-schema/run

## Remarks

In .NET Core and .NET 5+, this method throws <xref:System.NotSupportedException> when called. Use <xref:System.Reflection.Assembly.LoadFrom%28System.String%29> instead.
This API is not supported in .NET Core/.NET 5+. This method throws <xref:System.NotSupportedException> when called. Use <xref:System.Reflection.Assembly.LoadFrom%28System.String%29> instead.

The `assemblyFile` parameter must refer to a URI without escape characters. This method supplies escape characters for all invalid characters in the URI.

Expand Down