This page shows the source for this entry, with WebCore formatting language tags and attributes highlighted.
Removing unwanted references to .NET 4.6.1 from web applications
<n>Note: this article was originally published at <a href="https://encodo.com/latest/developer-blogs/removing-unwanted-references-to-net-461-from-web-applications/">Encodo.com</a> in July, 2018.</n> <hr> The title is a bit specific for this blog post, but that's the gist of it: we ended up with a bunch of references to an in-between version of .NET (4.6.1) that was falsely advertising itself as a more optimal candidate for satisfying 4.6.2 dependencies. This is a known issue; there are several links to MS GitHub issues below. In this blog, I will discuss direct vs. transient dependencies as well as internal vs. runtime dependencies. <h><abbr title="too long; didn't read">tl;dr</abbr></h> If you've run into problems with an application targeted to .NET Framework 4.6.2 that does not compile on certain machines, it's possible that the binding redirects Visual Studio has generated for you use versions of assemblies that aren't installed anywhere but on a machine with Visual Studio installed. How I solved this issue: <ul> Remove the <c>C:\Program Files (x86)\Microsoft Visual Studio\2017\BuildTools\MSBuild\Microsoft\Microsoft.NET.Build.Extensions\net461\</c> directory Remove all System* binding redirects Clean out all <c>bin/</c> and <c>obj/</c> folders Delete the <c>.vs</c> folder (may not be strictly necessary) Build in Visual Studio Observe that a few binding-redirect warnings appear Double-click them to re-add the binding redirects, but this time <i>to actual 4.6.2 versions</i> (you may need to add <c><autogeneratebindingredirects>true</autogeneratebindingredirects></c> to your project) Rebuild and verify that you have no more warnings </ul> The product should now run locally and on other machines. For more details, background and the story of how I ran into and solved this problem, read on. <n>Note: I published a recent article, <a href="https://dev.earthli.com/news/view_article.php?id=3637">.NET Tips and Resources</a>, containing a link to a video by Immo Landwerth, in which says <iq>If you want to be compatible with .NET Core 1.5 or lower, then you can use .NET Framework 4.6.1. For .NET Standard compatibility, you should definitely use .NET Framework 4.7.2 instead.</iq> That will probably fix the problem as well. Moving to .NET Core will also fix the problem, as all binding is handled automatically there.</n> <h>Building Software</h> What do we mean when we say that we "build" an application? Building is the process of taking a set of <i>inputs</i> and producing an artifact <i>targeted</i> at a certain runtime. Some of these inputs are <i>included directly</i> while others are <i>linked externally</i>. <ul> Examples of direct inputs are the binary artifacts produced from the source code that comprises your application Examples of external inputs are OS components and runtime environments </ul> The machine does exactly what you tell it to, so it's up to you to make sure that your instructions are as precise as possible. However, you also want your application to be flexible so that it can run on as wide an array of environments as possible. Your source code consists of <i>declarations</i>. We've generally got the direct inputs under control. The code compiles and produces artifacts as expected. It's the external-input declarations where things go awry. What kind of external inputs does our application have? <ul> System dependencies in the runtime target (assemblies like System.Runtime, System.Data, etc.), each with a minimum version Third-party dependencies pulled via NuGet, each with a minimum version </ul> How is this stitched together to produce the application that is executed? <ul> The output folder contains our application, our own libraries and the assemblies from NuGet dependencies All other dependencies (e.g. system dependencies) are pulled from the <i>environment</i> </ul> The NuGet dependencies are resolved at <i>build time</i>. All resources are pulled and added to the release on the build machine. There are no run-time decisions to make about which versions of which assemblies to use. Dependencies come in two flavors: <ul> <b>Direct</b>: A reference in the project itself <b>Transient</b>: A <i>direct</i> reference inherited from another <i>direct</i> or <i>transient</i> reference </ul> It is with the transient references that we run into issues. The following situations can occur: <ul> A transient dependency is referenced one or more times with the same version. This is no problem, as the builder simply uses that version or substitutes a newer version if that version is no longer available (rare, but possible) A transient dependency is referenced in different versions. In this case, the builder tries to substitute a single version for all requirements. This generally works OK since most dependencies require a given version <i>or higher</i>. It may be that one or another library cannot work with all newer versions, but this is also rare. In this case, the top-level assembly (the application) must include a hint (an assembly-binding redirect) that indicates that the substitution is OK. More on these below. A transient dependency requires a lower version than the version that is directly referenced. This is also not a problem, as the transient dependency is satisfied by the direct dependency with the higher version. In this case, the top-level application must also include an assembly-binding redirect to allow the substitution without warning. A transient dependency requires a higher version than the version that is directly referenced. This is an error (no longer just a warning) that must be solved by either downgrading the dependency that leads to the problematic transient dependency <i>or</i> upgrading the direct dependency. Generally, the application will upgrade the direct dependency. </ul> <h>Assembly-Binding Redirects</h> An application generally includes an <c>app.config</c> (desktop applications or services) or <c>web.config</c> XML file that includes a section where binding redirects are listed. A binding redirect indicates the range of versions that can be mapped (or <i>redirected</i>) to a certain fixed version (which is generally also included as a direct dependency). A redirect looks like this (a more-complete form is further below): <code><bindingredirect oldVersion="0.0.0.0-188.8.131.52" newVersion="184.108.40.206"></code> When the direct dependency is updated, the binding redirect must be updated as well (generally by updating the maximum version number in the range and the version number of the target of the redirect). NuGet does this for you when you're using <c>package.config</c>. If you're using Package References, you must update these manually. This situation is currently not so good, as it increases the likelihood that your binding redirects remain too restrictive. <h>NuGet Packages</h> NuGet packages are resolved at <i>build time</i>. These dependencies are delivered as part of the deployment. If they could be resolved on the build machine, then they are unlikely to cause issues on the deployment machine. <h>System Dependencies</h> Where the trouble comes in is with dependencies that are resolved at <i>execution time</i> rather than <i>build time</i>. The .NET Framework assemblies are resolved in this manner. That is, an application that targets .NET Framework expects certain versions of certain assemblies to be available on the deployment machine. We mentioned above that the algorithm sometimes chooses the desired version <i>or higher</i>. This is not the case for dependencies that are in the assembly-binding redirects. Adding an explicit redirect <i>locks</i> the version that can be used. This is generally a <i>good idea</i> as it increases the likelihood that the application will only run in a deployment environment that is extremely close or identical to the development, building or testing environment. <h>Aside: Other Bundling Strategies</h> How can we avoid these pesky run-time dependencies? There are several ways that people have come up with, in increasing order of flexibility: <ul> Deliver hardware and software together. This is common in industrial applications and used to be much more common for businesses, as well. Nearly bulletproof. If it worked in the factory, it will work for the customer. Deliver a VM (virtual machine) as your application. This includes the entire execution environment right down to the hardware. Safe, but inefficient. Use a container (e.g. Docker) to deliver a description of the execution environment. The image is built to match the declaration. This is also quite stable and can avoid many of the substitution errors outlined above. If components are outdated, the machine fails to start and the definition must first be updated (and, presumably, tested). This type of deployment is getting more reliable but is also overkill for many applications. Deliver the runtime with the application instead of <i>describing</i> the runtime you'd like to have. Targeting .NET Core instead of .NET Framework includes the runtime. This seems like a nice alternative and it's not surprising that Microsoft went in this direction with .NET Core. It's a good solution to the external-dependency issues outlined above. </ul> To sum up: <ul> A VM delivers the OS, runtime and application. A Container delivers a description of the OS and runtime as well as the application itself. .NET Core includes the runtime and application and is OS-agnostic (within reason). .NET Framework includes only the application and some directives on the remaining components to obtain from the runtime environment. </ul> Our application targets .NET Framework (for now). We're looking into .NET Core, but aren't ready to take that step yet. <h>Where can the deployment go wrong?</h> To sum up the information from above, problems arise when the build machine contains components that are not available on the deployment machine. How can this happen? Won't the deployment machine just use the best match for the directives included in the build? Ordinarily, it would. However, if you remember our discussion of assembly-binding redirects above, those are set in stone. What if you included binding redirects that <i>required</i> versions of system dependencies that are only available on your build machine ... or even your developer machine? <h>Special Tip for Web Applications</h> We actually discovered an issue in our deployment because the API server was running, but the Authentication server was not. The Authentication server was crashing because it couldn't find the runtime it needed in order to <i>compile</i> its Razor views (it has ASP.Net MVC components). We only discovered this issue on the deployment server because the views were only ever compiled on-the-fly. To catch these errors earlier in the deployment process, you can enable pre-compiling views in release mode so that the build server will fail to compile instead of a producing a build that will sometimes fail to run. Add the <c><mvcbuildviews>true</mvcbuildviews></c> to any MVC projects in the <c>PropertyGroup</c> for the release build, as shown in the example below: <code><propertygroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' "> <debugtype>pdbonly</debugtype> <optimize>true</optimize> <outputpath>bin</outputpath> <defineconstants>TRACE</defineconstants> <errorreport>prompt</errorreport> <warninglevel>4</warninglevel> <langversion>6</langversion> <mvcbuildviews>true</mvcbuildviews> </propertygroup></code> <h>How do I create a redirect?</h> We mentioned above that NuGet is capable of updating these redirects when the target version changes. An example is shown below. As you can see, they're not very easy to write: <code> <configuration> <runtime> <assemblybinding xmlns="urn:schemas-microsoft-com:asm.v1"> <dependentassembly> <assemblyidentity name="System.Reflection.Extensions" publicKeyToken="B03F5F7F11D50A3A" culture="neutral"> <bindingredirect oldVersion="0.0.0.0-220.127.116.11" newVersion="18.104.22.168"> </dependentassembly> </assemblybinding> </runtime> </configuration></code> Most bindings are created automatically when MSBuild emits a warning that one would be required in order to avoid potential runtime errors. If you compile with MSBuild in Visual Studio, the warning indicates that you can double-click the warning to automatically generate a binding. If the warning doesn't indicate this, then it will tell you that you should add the following to your project file: <code><autogeneratebindingredirects>true</autogeneratebindingredirects></code> After that, you can rebuild to show the new warning, double-click it and generate your assembly-binding redirect. <h>How did we get the wrong redirects?</h> When MSBuild generates a redirect, it uses the highest version of the dependency <i>that it found on the build machine</i>. In most cases, this will be the developer machine. A developer machine tends to have more versions of the runtime targets installed than either the build or the deployment machine. A Visual Studio installation, in particular, includes myriad runtime targets, including many that you're not using or targeting. These are available to MSBuild but are ordinarily ignored in favor of more appropriate ones. That is, unless there's a bit of a bug in one or more of the assemblies included with one of the SDKs...as there is with the net461 distribution in Visual Studio 2017. Even if you are targeting .NET Framework 4.6.2, MSBuild will still sometimes reference assemblies from the 461 distribution because the assemblies are incorrectly marked as having a higher version than those in 4.6.2 and are taken first. I found the following resources somewhat useful in explaining the problem (though none really offer a solution): <ul> <a href="https://github.com/dotnet/corefx/issues/26456">.dll in Microsoft.NET.Build.Extensions\net461 targets .NET Framework 4.6.1</a> <a href="https://github.com/Microsoft/msbuild/issues/2527">ImplicitlyExpandNETStandardFacades option on MSBuild Extensions corrupts build</a> (GitHub issue) <a href="https://social.msdn.microsoft.com/Forums/vstudio/en-US/51dc828b-43ca-4177-b68e-7a6a9cf81db5/ms-build-extensions-file-corrupt-my-bin-web-api-folder?forum=msbuild">MS Build Extensions file corrupt my bin (Web API) folder</a> </ul> How can you fix the problem if you're affected? You'll generally have a crash on the deployment server that indicates a certain assembly could not be loaded (e.g. <c>System.Runtime</c>). If you show the properties for that reference in your web application, do you see the path <c>C:\Program Files (x86)\Microsoft Visual Studio\2017\BuildTools\MSBuild\Microsoft\Microsoft.NET.Build.Extensions\net461</c> somewhere in there? If so, then your build machine is linking in references to this incorrect version. If you let MSBuild generate binding redirects with those referenced paths, they will refer to versions of runtime components that do not generally exist on a deployment machine. Tips for cleaning up: <ul> Use MSBuild to debug this problem. R# Build is nice, but not as good as MSBuild for this task. Clean and Rebuild to force all warnings Check your output carefully.<ul> Do you see warnings related to package conflicts? Ambiguities? Do you see the path <c>C:\Program Files (x86)\Microsoft Visual Studio\2017\BuildTools\MSBuild\Microsoft\Microsoft.NET.Build.Extensions\net461</c> in the output?</ul> </ul> A sample warning message: <warning>[ResolvePackageFileConflicts] Encountered conflict between <c>Platform:System.Collections.dll</c> and <c>CopyLocal:C:\Program Files (x86)\Microsoft Visual Studio\2017\BuildTools\MSBuild\Microsoft\Microsoft.NET.Build.Extensions\net461\lib\System.Collections.dll</c>. Choosing <c>CopyLocal:C:\Program Files (x86)\Microsoft Visual Studio\2017\BuildTools\MSBuild\Microsoft\Microsoft.NET.Build.Extensions\net461\lib\System.Collections.dll</c> because AssemblyVersion <c>22.214.171.124</c> is greater than <c>126.96.36.199</c>.</warning> <h>The Solution</h> As mentioned above, but reiterated here, this what I did to finally stabilize my applications: <ul> Remove the <c>C:\Program Files (x86)\Microsoft Visual Studio\2017\BuildTools\MSBuild\Microsoft\Microsoft.NET.Build.Extensions\net461\</c> directory Remove all System* binding redirects Clean out all <c>bin/</c> and <c>obj/</c> folders Delete the <c>.vs</c> folder (may not be strictly necessary) Build in Visual Studio Observe that a few binding-redirect warnings appear Double-click them to re-add the binding redirects, but this time <i>to actual 4.6.2 versions</i> (you may need to add <c><autogeneratebindingredirects>true</autogeneratebindingredirects></c> to your project) Rebuild and verify that you have no more warnings Deploy and TADA! </ul> <h>One more thing</h> When you install any update of Visual Studio, it will silently <i>repair</i> these missing files for you. So be aware and check the folder after any installations or upgrades to make sure that the problem doesn't creep up on you again.