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

Question

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?

score 75 · Answer 1 · answered Mar 02 '09 at 15:35

75

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

answered Mar 02 '09 at 15:35

JaredPar

733,204
149
1,241
1,454

1

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? – Fadeproof Mar 02 '09 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? – Fadeproof Mar 02 '09 at 18:29

score 24 · Answer 2 · edited May 23 '17 at 12:18

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.

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."? — Michael Freidgeim, Mar 20 '13 at 20:11

score 16 · Answer 3 · edited Dec 20 '11 at 23:07

16

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.

edited Dec 20 '11 at 23:07

Dan J

16,319
7
50
82

answered Mar 02 '09 at 15:35

Kent Boogaart

175,602
35
392
393

jpierson · Answer 4 · 2018-08-11T11:19:05.697

8

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.

edited Aug 11 '18 at 11:19

answered Jun 10 '09 at 05:40

jpierson

16,435
14
105
149

1

Updated the link, I wish Microsoft would have redirected after moving stuff around. – jpierson Aug 11 '18 at 11:24

score 2 · Answer 5 · answered Mar 02 '09 at 15:34

2

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.

answered Mar 02 '09 at 15:34

Mehrdad Afshari

414,610
91
852
789

4

It does a bit more than that. It heavily affects deployment scenarios. – JaredPar Mar 02 '09 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. – Mehrdad Afshari Mar 02 '09 at 15:39
@Mehrad, it will affect build scenarios but it's also at least equally aimed at deployment. – JaredPar Mar 02 '09 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. – Mehrdad Afshari Mar 02 '09 at 16:14

score 1 · Answer 6 · answered Dec 09 '12 at 02:26

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

score 1 · Answer 7 · answered Feb 21 '18 at 18:23

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.

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

7 Answers7

Linked

Related