skills.rest
dotnet
dotnetOFFICIAL
Explore all skills by this author →
Website𝕏@dotnetfdnGitHub

copy-to-output-directory

Selects the correct MSBuild CopyToOutputDirectory mode for build output file copying.

5.3k|403|Updated Feb 3, 2026
Search Tags:#msbuild#build performance#project files#incremental build#DotNet#copytooutputdirectory#ifdifferent
One-click install
npx skills add https://github.com/dotnet/skills --skill copy-to-output-directory
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: copy-to-output-directory
Source: https://github.com/dotnet/skills/tree/main/plugins/dotnet-msbuild/skills/copy-to-output-directory
Command: npx skills add https://github.com/dotnet/skills --skill copy-to-output-directory

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Choosing the wrong CopyToOutputDirectory mode causes either stale files in the output directory or an unnecessary copy on every build, slowing down incremental and no-op builds.

Core Features & Use Cases

  • Mode Selection Guidance: Explains the four modes — Never, PreserveNewest, Always, and IfDifferent (MSBuild 17.13+) — and when each applies.
  • Performance Optimization: Shows how to eliminate the per-build copy cost of Always using IfDifferent or the $(SkipUnchangedFilesOnCopyAlways) property.
  • Mutated Output Reset: Covers the scenario where a destination file (database, config, state file) is modified between builds and must be reset to the source version.
  • Use Case: A test suite mutates a copied SQLite fixture database; switching from Always to IfDifferent restores the fixture on each build without paying a copy cost on no-op builds.

Quick Start

Ask the agent which CopyToOutputDirectory mode to use for a file that gets modified between builds and how to avoid the Always copy performance hit.

Frequently Asked Questions about copy-to-output-directory

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I choose between PreserveNewest, Always, and IfDifferent in MSBuild?▼

Use PreserveNewest for normal source files you edit, IfDifferent when the destination file gets mutated between builds and must be reset to the source, and Always only when you truly need a copy on every build. Never is the default for files not needed at runtime.

Why is CopyToOutputDirectory Always slowing down my build?▼

Always re-copies the file on every build, including no-op incremental builds, which is a measurable recurring cost with many or large content files. Switch to IfDifferent or set SkipUnchangedFilesOnCopyAlways to true so copies only happen when files actually differ.

What MSBuild version supports CopyToOutputDirectory IfDifferent?▼

IfDifferent and SkipUnchangedFilesOnCopyAlways require MSBuild 17.13 or later, which ships with .NET SDK 9.0.2xx and Visual Studio 2022 17.13. On older toolsets the value is not recognized and the item is silently not copied.

How do I reset a copied file that my tests modify between builds?▼

Set CopyToOutputDirectory to IfDifferent on the item, such as a test database or config file. MSBuild then copies the source over the destination whenever they differ in timestamp or size, restoring the original without copying on every build.

Does IfDifferent compare file contents when deciding to copy?▼

No, the unchanged check is a heuristic comparing only last-write timestamp and file size, not a content hash. A destination edited to the same size and timestamp as the source is treated as unchanged and is not re-copied.

Related Skills

Explore More Software Engineering Skills→
1k-off1k-off
1

including-generated-files

Add build-generated files to MSBuild item groups with correct timing.

Community
Intermediate
rudironsonirudironsoni

dotnet-build-optimization

Diagnose .NET build performance issues using MSBuild binary logs and caching strategies.

Community
Intermediate
ojrojasojrojas

build-perf-diagnostics

Analyze MSBuild binary logs to identify performance bottlenecks and optimization areas.

Community
Advanced
bjornslibbjornslib

setup-harness

Copy the Claude Code harness into a project Git repository.

Community
Advanced