Document how to access reference assemblies from Roslyn

[svick]

Describe the new topic

• Explain why this topic is needed.

  One pitfall when using Roslyn is how to find assemblies to reference.

  In simple cases on .Net Framework and recent versions of .Net Core (2.0+, I think), referencing runtime assemblies can work (e.g. MetadataReference.CreateFromFile(typeof(object).Assembly.Location)).

  In more complicated cases, I believe the right solution is to use DependencyContext, following this guide: https://github.com/dotnet/core/issues/2082#issuecomment-442713181. But because that is far from obvious, I believe it should be documented in a much more prominent location than a comment on a GitHub issue.

• Suggest a location in the Table of Contents.

  Somewhere in ".NET Compiler Platform SDK". Possibly under "Tutorials"?

• Write an abstract. In one short paragraph, describe what this topic will cover.

  It should explain why reference assemblies are useful (probably linking to the article suggested in https://github.com/dotnet/docs/issues/2638, if it exists) and then describe how to take advantage of them by using <PreserveCompilationContext>, Microsoft.Extensions.DependencyModel and DependencyContext together with Roslyn Compilation.

• Create an outline for the new topic. We'll help review the outline and approve it before anyone writes a topic.

  • Intro to reference assemblies when it comes to Roslyn.
  • How to reference runtime assemblies. (?)
  • How to reference reference assemblies.

Help us make content visible

• Tell us what search terms you used and how you searched docs.

  The people that should be directed to this potential document are those that find that their Roslyn Compilation does not work (e.g. they get an error when loading the emitted assembly, because it was not actually emitted: https://github.com/dotnet/roslyn/issues/27783#issuecomment-397164483). If they look more closely, they find diagnostic errors such as "CS0012: The type 'Object' is defined in an assembly that is not referenced": https://github.com/dotnet/roslyn/issues/27783#issuecomment-397496206.

  (The linked issue is just one, but I've seen others have this issue, e.g. https://github.com/dotnet/core/issues/2082.)

  So I think it would be great if this article showed up when searching for these errors. And also some more general queries, like "roslyn references".

cc: @BillWagner

[Thraka]

Hi @svick

Thank you for the suggestion. I've categorized this request and put it in the backlog.

[dotnet-bot]

This issue has been closed as part of the issue backlog grooming process outlined in #22351.

That automated process may have closed some issues that should be addressed. If you think this is one of them, reopen it with a comment explaining why. Tag the @dotnet/docs team for visibility.

[Youssef1313]

I believe this issue needs to be addressed.

[glopesdev]

Also clarify the relationship with the basic reference assemblies project: https://github.com/jaredpar/basic-reference-assemblies/issues/12

[NMSAzulX]

Thanks to this issue, I think I should give some feedback. I am using roslyn and string scripts to build dynamic assemblies. I have made an open source library that has been used by many people. So far, there is no problem except that asp.net can't unload the domain. It automatically manages references. I divided the reference into two parts, 1. all assemblies from the DependencyContext .Default, and 2 references from dynamic compilation. Each time the assembly is compiled in the same domain, it adds up the references of guarantee 1 and 2 to roslyn to compile. Through reflection, I pre-cache all using code. Users only need to pay attention to their class code or method code.

But I found that DependencyContext can't reflect private fields because its meta-information is incomplete. If it is not complete, at least it should be described in the document. (If you say private fields should not be used by developers. I want to say, never underestimate developers' customized ideas, they will customize high-performance libraries that belong to their own needs. It is necessary to use the private / internal field.).

I have a little suggestion: allow developers to convert assemblies in the domain into references. Perhaps roslyn can automatically manage references based on domain (AssemblyLoadContext). This becomes easier when there is a unified reference management API.(If you are worried about the compatibility problems caused by the version, you can start with the version that supports assemblyloadcontext.)

[NMSAzulX]

< PreserveCompilationContext > this gives me a headache, and I have to release a nuget package for this so that developers can ignore the < PreserveCompilationContext > tag.

https://github.com/dotnetcore/Compile.Environment/blob/master/DotNetCore.Compile.Environment/targets/DotNetCore.Compile.Environment.targets

https://github.com/dotnetcore/Compile.Environment/blob/master/DotNetCore.Compile.Environment/DotNetCore.Compile.Environment.csproj#L32

[MSDN-WhiteKnight]

But I found that DependencyContext can't reflect private fields because its meta-information is incomplete. If it is not complete, at least it should be described in the document.

DependencyContext returns paths to reference assemblies. Reference assemblies by design does not contain private members, it is already documented here: https://docs.microsoft.com/en-us/dotnet/standard/assembly/reference-assemblies#reference-assemblies-structure It is not directly related to roslyn, because you can't reference private members in C#/VB anyway.

[NMSAzulX]

@MSDN-WhiteKnight Thanks. I can only use private fields in this way ,
domain.addreference(typeof(List<int>).Assembly.Location);