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: .NET Core 2.1 Roslyn cannot find System.Decimal in assemblies core#2082 (comment). 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 What are reference assemblies? #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: Low perfomance? roslyn#27783 (comment)). If they look more closely, they find diagnostic errors such as "CS0012: The type 'Object' is defined in an assembly that is not referenced": Low perfomance? roslyn#27783 (comment).

  (The linked issue is just one, but I've seen others have this issue, e.g. .NET Core 2.1 Roslyn cannot find System.Decimal in assemblies core#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.