Introduction

If you build a .NET 5 project and notice a ref folder inside bin/Debug/net5.0 or bin/Release/net5.0, that folder is not a duplicate you should delete. It contains reference assemblies, which are meant for compilation, while the main output directory contains the runtime assemblies that the application actually executes.

What the ref folder contains

A reference assembly exposes the public API of a library without carrying the full implementation details needed to run it. The compiler only needs metadata such as type names, method signatures, and attributes. It does not need the IL that executes at runtime.

That is why the SDK may produce output like this:

1bin/
2  Debug/
3    net5.0/
4      MyLibrary.dll
5      MyLibrary.pdb
6      ref/
7        MyLibrary.dll

At first glance, it looks strange that there are two files with the same name. They serve different purposes:

• 'bin/Debug/net5.0/MyLibrary.dll is the runtime assembly'
• 'bin/Debug/net5.0/ref/MyLibrary.dll is the reference assembly'

The runtime assembly contains executable implementation. The reference assembly contains the compile-time shape of the API.

Why the SDK generates reference assemblies

Reference assemblies help the build system keep project-to-project references efficient and correct. If project App references project Library, the compiler for App can use the reference assembly from Library instead of reading the full runtime binary.

That separation has several benefits:

• it reduces accidental coupling to implementation details
• it makes incremental builds more predictable
• it avoids recompiling downstream projects when only internal implementation changed

Here is a simple example with two projects:

1<!-- App.csproj -->
2<Project Sdk="Microsoft.NET.Sdk">
3  <PropertyGroup>
4    <TargetFramework>net5.0</TargetFramework>
5  </PropertyGroup>
6
7  <ItemGroup>
8    <ProjectReference Include="..\\Library\\Library.csproj" />
9  </ItemGroup>
10</Project>

If Library changes a private helper method but keeps the public API the same, the reference assembly can remain effectively unchanged. That means App may not need a full recompilation based on API shape alone.

Why the ref folder is not used at runtime

A common misconception is that the ref folder must be deployed with the application. It should not be. The runtime does not load reference assemblies to execute your code.

For deployment, publishing, and normal program execution, the important files are the runtime assemblies in the main output or publish directory.

dotnet build
dotnet run
dotnet publish -c Release

After dotnet publish, you should focus on the publish output, not on the ref folder inside bin.

When you will notice it most

You are most likely to notice the ref folder when:

• inspecting build artifacts manually
• writing custom build scripts
• copying files into a container image
• debugging why a project reference behaves differently from a package reference

If a script copies everything from bin recursively, it may pick up the ref folder even though it is unnecessary. That is not usually fatal, but it creates noise and can confuse anyone inspecting the final artifact.

A practical way to think about it

Treat the ref folder as part of the SDK's build plumbing. It exists to support compilation and dependency tracking, not as a destination for runtime loading.

If you want to inspect the difference directly, tools such as ildasm or decompilers will show that the runtime assembly has method bodies while the reference assembly exposes only the contract surface. The names match because they represent the same library from two different perspectives.

Common Pitfalls

• Assuming the ref assembly is a duplicate file that can be deleted from every build process.
• Copying the ref folder into deployment artifacts and thinking the application depends on it at runtime.
• Pointing reflection or plugin-loading code at the reference assembly instead of the runtime assembly.
• Confusing bin output with publish output. Deployment should generally come from dotnet publish.
• Treating identical file names as proof that both files do the same job.

Summary

• The ref folder in a .NET 5 build contains reference assemblies, not runtime binaries.
• Reference assemblies describe the public API needed for compilation.
• The main assembly in bin/net5.0 is the one used for execution.
• The SDK uses reference assemblies to improve build correctness and incremental compilation.
• You normally do not deploy the ref folder with your application.