Docs: What are reference assemblies?

[svick]

I was looking for documentation explaining what reference assemblies are and didn't find any on Google or on docs.MS search. Does this information exist and did I just fail to find it?

If it doesn't exist, should it? It's a fairly advanced topic and might be considered an implementation detail, but I think this information would still be useful. It could either be a section in an existing article, or a separate article (probably a relatively short one).

In addition to the basic information, it could also explain how reference assemblies are used in .Net Framework, .Net Standard and NuGet packages. (And in the future, how the C# compiler can be used to produce them, see https://github.com/dotnet/roslyn/issues/2184.)

[mairaw]

@weshaggard @terrajobst any thoughts on this?

[weshaggard]

Closest thing we have is https://github.com/dotnet/standard/blob/master/docs/history/evolution-of-design-time-assemblies.md. @svick is there more information you would like to see about reference assemblies in that doc?

[svick]

@weshaggard Thanks. That's actually more in-depth on theory than what I was expecting. I think some more practical information could be useful (like mentioning the Program Files (x86)\Reference Assemblies directory or the ref directory in NuGet packages), but my main issue is that I think the information should be part of docs.MS and not hidden in a relatively obscure GitHub repo.

[weshaggard]

but my main issue is that I think the information should be part of docs.MS and not hidden in a relatively obscure GitHub repo.

I agree it might be worth a conceptional document on the official docs site.

[terrajobst]

Hey @svick, you might find my video on reference assemblies helpful in that regard. If that's true, we've something concrete we could incorporate in our docs.

[svick]

@terrajobst Yeah, I think that's a good complement to the dotnet/standard document.

[tannergooding]

@terrajobst, does your video also cover the C# 7.1 reference assembly feature (https://github.com/dotnet/roslyn/blob/master/docs/features/refout.md)?

[MSDN-WhiteKnight]

This information is now present in C# compiler options documentation: -refonly and -refout. It covers their structure well. However, there are issues:

• It is hard to discover by searching
• Exactly the same remarks text is duplicated in refout and refonly articles
• No information on the actual purpose or use cases of reference assemblies
• No information how developers obtain reference assemblies for .NET Framework (targeting packs)

And, most impotantly, reference assemblies from older targeting packs (.NET 4.7.2 and below), located at C:\Program Files (x86)\Reference Assemblies, are different in structure then ones produced by Roslyn compiler's refout/refonly switch, and don't match the description in these articles. For example, they don't have a single throw null statement in methods' body, but rather have totally empty body, or a single return instruction in body. Supposedly, it is because they were generated by some internal tool that had different rules. It also should be documented somehow.

I suggest to create a new Reference assemblies article under https://docs.microsoft.com/en-us/dotnet/standard/assembly/ section that will include this information, and change refout/refonly articles to link info this new article, instead of directly including it in remarks.

[terrajobst]

I suggest to create a new Reference assemblies article under https://docs.microsoft.com/en-us/dotnet/standard/assembly/ section that will include this information, and change refout/refonly articles to link info this new article, instead of directly including it in remarks.

👍