Whats the deal with Infragistics.WebUI.Shared.dll and the CopyLocal property?

When developers first get started withing with the NetAdvantage web controls, invariably one of the first issues they run into is not having the Infragistics.WebUI.Shared.dll assemblies CopyLocal property set to True.  If you forget to do this, then you get a runtime exception that looks something like this:

Additionally, once a developer learns that they need to set the assemblies CopyLocal property to True, there is often confusion as to which assemblies need to have this property set.  In fact, the only assembly should ever have its CopyLocal property set to True is the Infragistics.WebUI.Shared.dll assembly.  If you set any other of the NetAdvantage assemblies CopyLocal property to True, then you may potentially see abnormal design-time behavior from any controls that reside in the assembly if the assembly has also been installed into the GAC (which all NetAdvantage controls are by default).

So the question is, why must you set the CopyLocal property to True on the WebUI.Shared assembly? It roots back to the way an ASPX page is served up in IIS. The ASPX page is compiled when the page is requested, and the ControlBuilder must parse through the ASPX and create valid objects. The first obstacle in this process are the tag prefixes resident in the ASPX page. If the assembly that corresponds to a tag prefix is in the GAC, the @Register directive which defines the TagPrefix attribute will contain a PublicKeyToken and AssemblyVersion string. This allows the ControlBuilder to load the control assembly from the GAC at runtime, and since by default, NetAdvantage installs all of the control assemblies in the GAC, when you add a control to the VS design surface, the @Register directives will indeed include the PublicKeyToken and Assembly version in the @register directive.  If these attributes are not present in the @Register directives TagPrefix attribute, you will get an error when you try to build the page.

So now the ControlBuilder knows what assembly it is looking for when it hits a specified TagPrefix. However, when the control builder walks the dependency chain of said assembly, it does not know where to load Infragistics.WebUI.Shared from (which is referenced by every Infragistics web assembly). One would hope that since it loaded the main assembly from the GAC, it would attempt to load Infragistics.WebUI.Shared form there as well, unfortunately that is not the case.

When the ControlBuilder hits the dependency on WebUI.Shared, it searches the applications bin directory only. This is where the CopyLocal property comes in. By setting the property to True on the WebUI.Shared assembly, you are telling the project to copy the assembly into the applications bin directory, ensuring that it is in the default probe path for the application.

Thankfully, messing with the CopyLocal property is not the only option.  Now that you understand the problem, you’ll see that you simply need to get Infragistics.WebUI.Shared into the appdomain somehow.  This can be done a couple of other ways.

1. Add a Assembly directive to each page in your web application that uses an Infragistics NetAdvantage control:

<%@ Assembly Name="Infragistics.WebUI.Shared.v5.3, Version=5.3.20053.49, Culture=neutral, PublicKeyToken=7dd5c3163f2cd0cb" %>

Force the applications web.config to load the assembly by adding it to the compilation section:

<COMPILATION defaultLanguage="c#" debug="true">
    <ASSEMBLIES>
        <ADD assembly="Infragistics.WebUI.Shared.v5.3, Version=5.3.20053.49, Culture=neutral, PublicKeyToken=7dd5c3163f2cd0cb" />
    </ASSEMBLIES>
</COMPILATION>

Note that this problem is unique to users using Visual Studio 2002/2003 only. This is because in Visual Studio 2005 the ASPX is compiled into the assembly for the web application. As a result, Visual Studio must add all assembly references in the web.config file, which it does automatically.

Thanks to our ASP.NET Product Manager Tony Lombardo for helping me with this post.