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?
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.
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".
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 false ensures it will appear in the output of your build, so makes it easier to deploy to the target environment.
HTH, Kent
Check out the following MSDN reference which explains CopyLocal behavior in detail.
Unfortunately there are some quirks and CopyLocal won't necessary work as expected for assembly references in secondary assemblies structured as shown below.
This makes xcopy deployments difficult if you don't plan on installing the third party assembly into the GAC on the target machine.
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.