When should copy-local be set to true and when should it not?

I am wondering if there are any heuristics for when to set copy-local=true for references?

If referenced types are only used internally can I set copy-local to true but if referenced types are exposed as parameters or return values I set copy-local to false and indicate that a specific version of the dependency should be referenced when my library should be used?

Can anyone clarify this for me?

Copy local is important for deployment scenarios and tools. As a general rule you should use CopyLocal=True if the reference is not contained within the GAC.

Copy Local essentially means I must manually deploy this DLL in order for my application to work. When it's false it essentially means "I depend on another component which must be installed separately or chained, the DLL will just be there already".

Copy local was implemented really to support local debugging. When you perpare your application for package and deployment you should build your projects to the same output folder and make sure you have all the references you need there.

CopyLocal is especially a pain when building large source trees. There was a related question about how to disable CopyLocal here on SO you can see it at How do I override CopyLocal (Private) setting for references in .NET from MSBUILD. As well as Best practices for large solutions in Visual Studio (2008).

I have written about how to deal with building large source trees in the article MSBuild: Best Practices For Creating Reliable Builds, Part 2.

So in short I would say disable CopyLocal when the file copying is causing your builds to take more time then you are willing to spend for every build.

It's really about the target environment. If copy local is false, you're saying that the assembly will already exist in the target environment (normally in the GAC). Setting it to true ensures it will appear in the output of your build, so makes it easier to deploy to the target environment.

Check out the following MSDN reference which explains CopyLocal behavior in detail.

Project References

Unfortunately there are some quirks and CopyLocal won't necessary work as expected for assembly references in secondary assemblies structured as shown below.

• MainApp.exe
  • MyLibrary.dll
    • ThirdPartyLibrary.dll (if in the GAC CopyLocal won't copy to MainApp bin folder)

This makes xcopy deployments difficult if you don't plan on installing the third party assembly into the GAC on the target machine.

This option only affects build phase. It just copies the reference to local directory of the built assembly.

If another assembly (T) wants to use a method from the assembly you are building (A) which has return type or parameters from another referenced assembly (R), it (T) should be able to access that assembly (R). It might be able to do so without doing anything special if the referenced assembly (R) is installed in GAC. Otherwise, it needs a local copy of that.

Set CopyLocal=false will improve build time, but can cause different issues during deployment time.

My experience with setting CopyLocal=false wasn't successfull. See summary of pro and cons in my blog post "Do NOT Change "Copy Local” project references to false, unless understand subsequences."

Conservative way to set CopyLocal false is to check that the reference is found in the output path of the project. This should allow you to dodge some nasty runtime issues, while still reducing the amount of IO.

In the process I created CopyLocalFixer, which you can run for a folder. I tried this with one large build, but the results weren't that impressive to be honest. I guess it comes down to the folder structure of the project.