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

Asked 2/3, 2009 at 15:32 Answered 21/2, 2018 at 18:23

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?

Motch answered 2/3, 2009 at 15:32 Comment(0)

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".

Rostock answered 2/3, 2009 at 15:35 Comment(2)

How about in the case of where I have a utility library MyUtils that uses LibX (not in gac) internally and does not expose any LibX specific types. There I would set copy-local to true. If however I expose LibX types from MyUtils I would have to ref. LibX as well from ProjectA which uses MyUtils no? – Motch 2/3, 2009 at 18:28

Should I in that case set copy-local to false as I would have to ref LibX as well as MyUtils from ProjectA? – Motch 2/3, 2009 at 18:29

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.

Hackbut answered 7/1, 2010 at 21:57 Comment(2)

Would it better to say "disable CopyLocal ONLY when you change the output to build your projects to the same output folder and make sure you have all the references you need there."? – Doubtful 20/3, 2013 at 20:11

@MichaelFreidgeim: Did you find an answer to your question? – Spurling 4/5, 2015 at 19:8

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.

Procambium answered 2/3, 2009 at 15:35 Comment(0)

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.

Lauretta answered 10/6, 2009 at 5:40 Comment(1)

Updated the link, I wish Microsoft would have redirected after moving stuff around. – Lauretta 11/8, 2018 at 11:24

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.

Champerty answered 2/3, 2009 at 15:34 Comment(4)

It does a bit more than that. It heavily affects deployment scenarios. – Rostock 2/3, 2009 at 15:35

I believe it does not affect the build except just a simple file copy process. Please correct me if it's not true. – Champerty 2/3, 2009 at 15:39

@Mehrad, it will affect build scenarios but it's also at least equally aimed at deployment. – Rostock 2/3, 2009 at 15:44

@JaredPar: Oh of course. I didn't dispute that. I thought it might be something special done in the assembly that I didn't know about. Thanks anyway. – Champerty 2/3, 2009 at 16:14

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."

Doubtful answered 9/12, 2012 at 2:26 Comment(0)

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.

Flyboat answered 21/2, 2018 at 18:23 Comment(0)

Recommended topics

Hot tags