What is ‘refs’ folder in ASP.NET Core app’s publish folder structure?

If your Asp.Net Core application uses MVC, you would likely be using Razor Views (*.cshtml). These views are compiled on-the-fly when the application starts up (later you will see about pre-compiling). At run-time, in order to ensure Razor view engine uses same set of assemblies as referenced during compile time, refs folder is generated during the ‘publish’ step containing all the referenced assemblies of your app and its dependencies.

If app does not use Razor views, you could prefer not to generate the ‘refs’ folder, thus reducing the size of the publish package. If Asp.Net Core project uses project.json, then look for a settings preserveCompilationContext under buildOptionsand set to it to false.

If the project is migrated to .csproj, set <PreserveCompilationContext> to false.

Reason I had to dig into this

Our Asp.Net Core app started throwing following exception on startup after applying a patch update.

System.InvalidOperationException: Can not find assembly file WindowsBase.dll at 'C:\Program Files\MyCompany\MyProd\Web\refs,C:\Program Files\MyCompany\MyProd\Web'
   at Microsoft.Extensions.DependencyModel.Resolution.AppBaseCompilationAssemblyResolver.TryResolveAssemblyPaths(CompilationLibrary library, List`1 assemblies)
   at Microsoft.Extensions.DependencyModel.Resolution.CompositeCompilationAssemblyResolver.TryResolveAssemblyPaths(CompilationLibrary library, List`1 assemblies)
   at Microsoft.Extensions.DependencyModel.CompilationLibrary.ResolveReferencePaths()
   at System.Linq.Enumerable.<SelectManyIterator>d__17`2.MoveNext()
   at Microsoft.AspNetCore.Mvc.Razor.Compilation.MetadataReferenceFeatureProvider.PopulateFeature(IEnumerable`1 parts, MetadataReferenceFeature feature)
   at Microsoft.AspNetCore.Mvc.ApplicationParts.ApplicationPartManager.PopulateFeature[TFeature](TFeature feature)
   at Microsoft.AspNetCore.Mvc.Razor.Internal.DefaultRoslynCompilationService.GetCompilationReferences()
...
...

We realized that in the patch, to implement a new feature, a new NuGet package was referenced which internally had dependency on WindowsBase.dll. As part of patch generation script, the project was published to a local build folder and a incremental package was created with only our modified application specific assemblies. Note that WindowsBase.dll reference was not in the original build as this feature is implemented only in patch. Patch generation script did not look inside the ‘refs’ folder to see if any new assemblies are present. Hence when the patch is deployed, on startup Razor view engine tried to load all referenced assemblies and failed to locate the WindowsBase.dll resulting in the exception. As soon as we copied over this DLL to ‘refs’ folder, app started successfully.

Observations:

1. Even though the new feature added in the patch was not related to any change in Razor view but instead a change in the back-end assembly, run-time engine on startup tried to resolve all referenced assemblies in the application.
2. When app was run on developer machines, from within Visual Studio, either hosted as IIS Express or <myapp>.exe, this exception was not seen. In this instance, both Debug and Release build folder did not contain ‘refs’ folder but still the startup exception was not observed! The app ran successfully. There could be some other means the Razor view engine was able to resolve the dependency in this mode.

Precompiling Razor Views

Starting from ASP.NET Core 1.1, the Razor view can be precompiled during publish time. The precompiled file will be named <Myapp>.PrecompiledViews.dll and reside in app root folder. When this option is used, ‘refs’ folder will not be generated.

Starting from ASP.NET Core 2, precompilation can done both during build as well as publish time.

See references below for more details.

Who helped me to understand this topic (a.k.a. References)?

Precompiling MVC Views in ASP.NET Core with .csproj’s

Razor file compilation and precompilation in ASP.NET Core

unexpected/unnecessary `refs` directory in published output of ASP.NET Core application · Issue…

dotnet publish does not copy refs folder · Issue #2243 · dotnet/sdk