. Net

.NET Reference assembly in

Intro

stay .NET There is a special assembly called ReferenceAssembly( Reference assembly ), Reference assembly （Reference Assemblies） Is a special type of assembly , It contains only the public that represents the library API The minimum amount of metadata required . They include declarations of all the members needed to reference the assembly in the build tool , But it does not include all member implementations and their API Declaration of private members whose agreement has no significant impact . Compare with , Regular assemblies are called “ Implementation assembly ” （implementation assemblies）.

Why

Now that we have an implementation assembly , Why reference assemblies ？

Use reference assemblies , Developers can generate programs that target specific library versions , Instead of having the full implementation assembly for that version . Because there is no implementation , The reference assembly is smaller , Loading and parsing will be faster .

This is similar to what we have agreed with third-party developers API standard , We can give API Requests and responses without providing an implementation to avoid block Progress of third-party developers , After all, they only care API What it is and not care about implementation .

To use some of the API, You must add a reference to its assembly . You can add references to implementation assemblies , You can also add it to a reference assembly . It is recommended to use the reference assembly when it is available . This ensures that only supported in the target version are used API member , Immediate supply API Designers use . Using reference assemblies ensures that you are not dependent on implementation details .

How

stay .NET Core 3.0 Before, many assemblies were released NuGet Bag , about .NET Core 3.0 And later , The reference assembly for the core framework is located in Microsoft.NETCore.App.Ref In bag , In general, it is not necessary , Because the reference assembly will follow .NET SDK Release together , You can SDK Under the installation directory of packs Directory to find the reference assembly of the corresponding framework version

Here is my computer SDK An example of a framework reference assembly in

Reference assemblies can only be used to compile , This procedural assembly has some special , Decompile and you will see a ReferenceAssembly Assembly of Attribute, Here is what I found in the above directory System.Text.Json The decompilation result of , You can see there's one ReferenceAssembly Of attribute

Reference Assembly

Look again. JsonNode The implementation of the

Let's find an implementation assembly to compare

Implementation assembly

Because they do not contain any implementation , Therefore, the reference assembly cannot be loaded for execution . If you try to do this , Will lead to System.BadImageFormatException, May come across Reference assemblies can only be loaded in the Reflection-only loader context. Such a mistake .

If you want to check the contents of the referenced assembly , You can load it into .NET Framework In the reflection only context （ Use Assembly.ReflectionOnlyLoad Method ）, Or load into .NET Core Medium MetadataLoadContext.

More

Often see the source code of children's shoes , Be sure to notice ,dotnet/runtime The structure of many class libraries in are similar to the following

runtime library structure

You will see that the first directory is ref, Which is used to generate reference assemblies ,src Is the project source code that contains the implementation ,test Some test cases https://github.com/dotnet/runtime/blob/89962a54d60e4d9c9837012d1729c5a72ec748cd/src/libraries/Microsoft.Extensions.Configuration/

ref Other projects referenced by the project are also directly referenced ref project https://github.com/dotnet/runtime/blob/89962a54d60e4d9c9837012d1729c5a72ec748cd/src/libraries/Microsoft.Extensions.Configuration/ref/Microsoft.Extensions.Configuration.csproj

see ref Project code , It can be found that the effect of decompilation is the same , Are empty implementations or throw null https://github.com/dotnet/runtime/blob/89962a54d60e4d9c9837012d1729c5a72ec748cd/src/libraries/Microsoft.Extensions.Configuration/ref/Microsoft.Extensions.Configuration.cs#L7

Recently doing dotnet-exec This gadget has encountered the problem of referencing assemblies , At first, I didn't understand the reference assembly , Reference assemblies are used when compiling code , Reference assemblies are also used when executing code , When executed load When the assembly is running, the above-mentioned

BadImageException Reference assemblies can only be loaded in the Reflection-only loader context.

See Youtube On this introduction Reference Assembly In the video （https://www.youtube.com/watch?v=EBpY1UMHDY8&list=PLRAdsfhKI4OX1cBGL2IXuEq1yzpDyKlwf&index=1&t=3s） Then it dawned on me , So that's it ... Although the video is based on .NET Framework As an example ,.NET Core Also similar , You can have a look at what you are interested in

stay VS We often meet in F12 All the implementations you see later are throw null, Guess that's why , At compile time VS Reference assemblies are used to improve performance

Finally, do you have any curiosity ref The project and src What are the differences between the projects ？ On the surface ref There seems to be nothing special in the project file , Using what we mentioned before Directory.Build.props For most projects , Interested students can explore by themselves according to the following links

https://github.com/dotnet/runtime/blob/89962a54d60e4d9c9837012d1729c5a72ec748cd/src/libraries/Directory.Build.props#L8

https://github.com/dotnet/runtime/blob/89962a54d60e4d9c9837012d1729c5a72ec748cd/eng/referenceAssemblies.props#L22

References

• https://github.com/dotnet/docs/pull/14393

• https://github.com/dotnet/docs/issues/2638

• https://github.com/dotnet/roslyn/blob/main/docs/features/refout.md

• https://docs.microsoft.com/en-us/dotnet/standard/assembly/reference-assemblies

• https://docs.microsoft.com/zh-cn/dotnet/standard/assembly/reference-assemblies

• https://www.youtube.com/watch?v=EBpY1UMHDY8&list=PLRAdsfhKI4OX1cBGL2IXuEq1yzpDyKlwf&index=1&t=3s