Choosing a CopyToOutputDirectory Mode
Overview
The
metadata (and its publish counterpart
) controls whether an item —
,
,
, or
— is copied next to your build output, and under what conditions the copy happens. Picking the wrong mode causes either stale files in
or an unnecessary per-build performance hit.
As of MSBuild 17.13 / .NET SDK 9.0.2xx there are four values:
| Mode | Copies when… | Incremental cost | Typical use |
|---|
| (default) | Never | None | Files not needed at runtime |
| Source is newer than destination (or destination missing) | Cheap (timestamp check) | The common case — source files you edit |
| Every build, unconditionally | Expensive — copies on every build even in no-op builds | Legacy workaround; avoid (see below) |
| Source differs from destination in either direction (newer or older, or size differs, or destination missing) | Cheap (timestamp + size check) | Destination may be mutated between builds |
xml
<ItemGroup>
<None Include="appsettings.json" CopyToOutputDirectory="PreserveNewest" />
<None Include="testdata\seed.db" CopyToOutputDirectory="IfDifferent" />
</ItemGroup>
You can use either the attribute form shown above or the child-element form:
xml
<None Include="testdata\seed.db">
<CopyToOutputDirectory>IfDifferent</CopyToOutputDirectory>
</None>
Why is usually the wrong choice
re-copies the file on
every build, including otherwise-clean incremental/no-op builds. On projects with many or large content files this is a measurable, recurring cost and a common cause of "why is my no-op build not instant?" reports.
Historically
was the only way to handle a specific scenario:
the destination file can change between builds — for example an SQLite database, a storage/state file, or a config file that a test run mutates. With
, if the destination is modified (making its timestamp
newer than the source) MSBuild will
not restore the original source file, because the source is no longer newer. People reached for
to force the file back into a known-good state — paying the copy cost on every build as a side effect.
: copy when different, in either direction
is the targeted fix for that scenario. It copies the source over the destination whenever MSBuild considers the two
different — whether the source is newer
or older than the destination, whether the size differs, or the destination is missing — and skips the copy when the destination is unchanged per MSBuild's heuristic.
Under the hood the
_CopyDifferingSourceItemsToOutputDirectory
target uses the
task with
SkipUnchangedFiles="true"
. That "unchanged" check is a
heuristic: it compares
last-write timestamp and file size only — not a content hash — so a destination that was edited to the same size and timestamp as the source is treated as unchanged and is
not re-copied. In practice this restores a mutated destination back to the source version on the next build (the reason people reached for
) while avoiding the unconditional per-build copy.
- A test run or the app itself writes to the copied file (databases, caches, state/storage files, editable config) and you want each build to reset it to the source version.
- You were using purely as a "keep the output in sync with the source" mechanism, not because you truly need a copy on every single build.
xml
<ItemGroup>
<!-- Reset the fixture DB to the source copy whenever it has drifted,
but don't pay a copy on every no-op build. -->
<None Include="fixtures\catalog.db" CopyToOutputDirectory="IfDifferent" />
</ItemGroup>
Globally softening with $(SkipUnchangedFilesOnCopyAlways)
If you have an existing codebase full of
CopyToOutputDirectory="Always"
items and want the performance benefit without editing every item, set the property:
xml
<PropertyGroup>
<SkipUnchangedFilesOnCopyAlways>true</SkipUnchangedFilesOnCopyAlways>
</PropertyGroup>
This makes the
_CopyOutOfDateSourceItemsToOutputDirectoryAlways
target pass
SkipUnchangedFiles="true"
to its
task, so
items are only copied when they actually differ — effectively giving
the same skip-unchanged behavior as
.
- Default is for backwards compatibility (classic = copy every build).
- Set it in to opt an entire repo in at once.
- Prefer converting individual items to when you can; use this property when a bulk, non-invasive opt-in is more practical.
How the modes flow through the build
GetCopyToOutputDirectoryItems
buckets each item by its
value. Three copy targets then do the work as dependencies of
_CopySourceItemsToOutputDirectory
(which is itself invoked by
CopyFilesToOutputDirectory
):
_CopyOutOfDateSourceItemsToOutputDirectory
_CopyOutOfDateSourceItemsToOutputDirectoryAlways
$(SkipUnchangedFilesOnCopyAlways)
_CopyDifferingSourceItemsToOutputDirectory
SkipUnchangedFiles="true"
All copied files are registered in
, so
removes them.
Transitive copy: items marked
,
, or
also flow to referencing projects through
(via
_CopyToOutputDirectoryTransitiveItems
).
items do not.
participates in ClickOnce publish item collection alongside
/
.
Version requirement
and
$(SkipUnchangedFilesOnCopyAlways)
require
MSBuild 17.13 or later (
.NET SDK 9.0.2xx+ / Visual Studio 2022 17.13+). On older toolsets the value is not recognized: it will not match the
/
/
conditions in the common targets, so the item is silently
not copied. Gate usage on the toolset if you must support older SDKs, or require the minimum SDK via
.
Quick decision guide
- Don't need the file at runtime → (or omit — it's the default).
- Normal source file you edit → .
- Destination gets mutated between builds and must be reset to the source → .
- You truly need a fresh copy on literally every build → (rare).
- Stuck with lots of legacy and want the perf win without edits → keep but set
$(SkipUnchangedFilesOnCopyAlways)=true