Document Single file unfriendly APIs

[MichalStrehovsky]

This is a running list of APIs that might be problematic for single file and we'll need to tag in some way. Until we have such mechanism here they are:

• Assembly.Location
• Assembly.CodeBase
• Assembly.EscapedCodeBase
• AssemblyName.CodeBase
• AssemblyName.EscapedCodeBase
• AssemblyDependencyResolver
• Assembly.GetFile
• Assembly.GetFiles
• Marshal.GetHINSTANCE
• Module.FullyQualifiedName

Assembly load APIs that might be problematic if people choose them instead of Assembly.Load by accident:

• AssemblyLoadContext.LoadFromAssemblyPath
• Assembly.LoadFile
• Assembly.LoadFrom

[ghost]

Tagging subscribers to this area: @swaroop-sridhar
Notify danmosemsft if you want to be subscribed.

[swaroop-sridhar]

We should clearly document these APIs in ms-docs in .net 5.
Linker analysis is targetted for .net6.

[marek-safar]

@swaroop-sridhar are there any tests for the behaviour difference for single-exe for these APIs? I'm asking as we'd like to re-use that for similar scenarios.

[swaroop-sridhar]

@marek-safar we don't have API tests yet. I'm working on a change to add the following tests:

For .netcoreapp3.x single-file apps the APIs will return the actual location of assemblies in the extraction location.
For .net5 single-file apps, the behavior of the above APIs will be the same as assemblies loaded from a byte stream.

• AppContext.BaseDirectory
  • The single-file app directory for PublishSingleFile=true apps.
  • The extraction directory for PublishSingleFile=true IncludeAllContentInSingleFile=true apps (netcoreapp3.x compatibility mode).
• Assembly.Location: empty string
• Assembly.CodeBase, Assembly.EscapedCodeBase, AssemblyName.CodeBase AssemblyName.EscapedCodeBase: empty string
• Assembly.GetFile: null
• Assembly.GetFiles: empty array
• Marshal.GetHINSTANCE: -1

Apart from these, AssemblyLoadContext.LoadFromAssemblyPath and Assembly.LoadFile will only work on actual files.
So, we can subsequently add a test to make sure they are not loaded from the bundle.

Once I have a PR, I'll tag this issue.

[agocke]

@LakshanF This would be good to put in the docs for PublishSingleFile

[vitek-karas]

Based on discussion in #40103 and #40087 I suggest to modify the behavior as:

• AppContext.BaseDirectory
  • The single-file app directory for PublishSingleFile=true apps. [Done]
  • The extraction directory for PublishSingleFile=true IncludeAllContentInSingleFile=true apps (netcoreapp3.x compatibility mode). [Needs verification]
• Assembly.Location: empty string [Done]
• Assembly.CodeBase, Assembly.EscapedCodeBase, AssemblyName.CodeBase AssemblyName.EscapedCodeBase: throw PlatformNotSupportedException. Assembly.CodeBase and Assembly.EscapedCodeBase are obsolete in .NET 5. We should discsuss obsoleting AssemblyName.CodeBase and AssemblyName.EscapedCodeBase as well.
• Module.FullyQualifiedName: <Unknown> string (just like it does in no-single-file for memory-loaded assemblies)
• Assembly.GetFile: will throw IOException - just like it does in non-single-file for memory-loaded assemblies
• Assembly.GetFiles: will throw IOException - just like it does in non-single-file for memory-loaded assemblies
• Marshal.GetHINSTANCE: -1

[MichalStrehovsky]

We should also add "things that p/invoke into [lib]coreclr[.so|.dll|.dylib]", based on #41859.

[tlakollo]

Closing since dotnet/docs#20761 was merged