Choosing a CopyToOutputDirectory Mode

copy-to-output-directory

Choosing an MSBuild CopyToOutputDirectory / CopyToPublishDirectory mode: Never, PreserveNewest, Always, and IfDifferent (MSBuild 17.13+), plus $(SkipUnchangedFilesOnCopyAlways). USE FOR: removing the per-build Always copy perf hit; resetting output files mutated between builds. DO NOT USE FOR: general incremental-build diagnosis (use incremental-build); non-MSBuild build systems.

dotnet/skills·1.9Kinstalls5.6Kstars

SKILL.md

Full skill instructions

Choosing a CopyToOutputDirectory Mode

Overview

The CopyToOutputDirectory metadata (and its publish counterpart CopyToPublishDirectory) controls whether an item — Content, None, EmbeddedResource, or Compile — is copied next to your build output, and under what conditions the copy happens. Picking the wrong mode causes either stale files in bin/ 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
`Never` (default)	Never	None	Files not needed at runtime
`PreserveNewest`	Source is newer than destination (or destination missing)	Cheap (timestamp check)	The common case — source files you edit
`Always`	Every build, unconditionally	Expensive — copies on every build even in no-op builds	Legacy workaround; avoid (see below)
`IfDifferent`	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

<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:

<None Include="testdata\seed.db">
  <CopyToOutputDirectory>IfDifferent</CopyToOutputDirectory>
</None>

Why `Always` is usually the wrong choice

Always 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 Always 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 PreserveNewest, 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 Always to force the file back into a known-good state — paying the copy cost on every build as a side effect.

`IfDifferent`: copy when different, in either direction

IfDifferent 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 Copy 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 Always) while avoiding the unconditional per-build copy.

Use IfDifferent when:

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 Always purely as a "keep the output in sync with the source" mechanism, not because you truly need a copy on every single build.

<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 `Always` 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:

<PropertyGroup>
  <SkipUnchangedFilesOnCopyAlways>true</SkipUnchangedFilesOnCopyAlways>
</PropertyGroup>

This makes the _CopyOutOfDateSourceItemsToOutputDirectoryAlways target pass SkipUnchangedFiles="true" to its Copy task, so Always items are only copied when they actually differ — effectively giving Always the same skip-unchanged behavior as IfDifferent.

Default is false for backwards compatibility (classic Always = copy every build).
Set it in Directory.Build.props to opt an entire repo in at once.
Prefer converting individual items to IfDifferent 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 CopyToOutputDirectory value. Three copy targets then do the work as dependencies of _CopySourceItemsToOutputDirectory (which is itself invoked by CopyFilesToOutputDirectory):

_CopyOutOfDateSourceItemsToOutputDirectory — PreserveNewest items (incremental via Inputs/Outputs timestamp comparison).
_CopyOutOfDateSourceItemsToOutputDirectoryAlways — Always items (unconditional copy unless $(SkipUnchangedFilesOnCopyAlways) is true).
_CopyDifferingSourceItemsToOutputDirectory — IfDifferent items (SkipUnchangedFiles="true").

All copied files are registered in FileWrites, so dotnet clean removes them.

Transitive copy: items marked Always, PreserveNewest, or IfDifferent also flow to referencing projects through ProjectReference (via _CopyToOutputDirectoryTransitiveItems). Never items do not. IfDifferent participates in ClickOnce publish item collection alongside Always/PreserveNewest.

Version requirement

IfDifferent 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 Always/PreserveNewest/IfDifferent 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 global.json.

Quick decision guide

Don't need the file at runtime → Never (or omit — it's the default).
Normal source file you edit → PreserveNewest.
Destination gets mutated between builds and must be reset to the source → IfDifferent.
You truly need a fresh copy on literally every build → Always (rare).
Stuck with lots of legacy Always and want the perf win without edits → keep Always but set $(SkipUnchangedFilesOnCopyAlways)=true.

Install skill

Copy and run in your terminal

npx -y skills add https://github.com/dotnet/skills --skill copy-to-output-directory

View on GitHub

plugins/dotnet-msbuild/skills/copy-to-output-directory

create-skill
create skill
2.6K installs
assertion-quality
Analyzes the variety and depth of assertions across test suites in any language. Use when the user asks to evaluate assertion quality, find shallow tests, identify assertion-free tests (no assertions or only trivial ones like Assert.IsNotNull / toBeTruthy()), flag self-referential or tautological assertions, measure assertion diversity, or audit whether tests verify different facets of behavior. Polyglot: .NET, Python, TS/JS, Java, Go, Ruby, Rust, Swift, Kotlin, PowerShell, C++. DO NOT USE FOR: writing new tests (use code-testing-agent / writing-mstest-tests), mutation reasoning about whether tests would catch a bug (use test-gap-analysis), or a general severity-ranked anti-pattern audit (use test-anti-patterns), fixing or rewriting assertions, or writing, fixing, or modernizing MSTest tests, assertions, or attributes (use writing-mstest-tests).
2.6K installs
test-gap-analysis
Performs pseudo-mutation analysis on production code in any language to find gaps in existing tests. Use when the user asks to find weak or shallow tests, discover untested edge cases, or check whether tests would catch a bug — e.g. "would my tests catch it if someone changed the code", "would a subtle logic or boundary change slip past the current tests", "are my tests strong enough to catch a subtle bug". Evaluates test effectiveness through mutation-style reasoning: analyzes mutation points (boundaries, boolean flips, null returns, exception removal, arithmetic changes) and checks whether tests would detect each. Polyglot: .NET, Python, TS/JS, Java, Go, Ruby, Rust, Swift, Kotlin, PowerShell, C++. DO NOT USE FOR: writing new tests (use code-testing-agent, or writing-mstest-tests for MSTest), detecting anti-patterns (use test-anti-patterns), measuring assertion diversity (use assertion-quality), or running actual mutation testing tools (Stryker, mutmut, PIT, cargo-mutants).
2.6K installs
create-custom-agent
create custom agent
2.4K installs

More skills from dotnet

dotnet/skills

create-skill-test

create skill test

5.6K 2.4K

View

dotnet/skills

test-tagging

Analyzes test suites in any language and tags each test with standardized traits (positive, negative, critical-path, boundary, smoke, regression, integration, performance, security). Use when the user wants to categorize, audit, or label tests with traits. Works across .NET (MSTest/xUnit/NUnit/TUnit), Python (pytest), TS/JS (Jest/Vitest), Java, Go, Ruby, Rust, Swift, Kotlin, PowerShell, and C++ — auto-editing when the framework has canonical tag syntax, otherwise report-only. Do not use for writing new tests, running tests, or migrating frameworks.

5.6K 2.3K

View

dotnet/skills

configure-auth

Add authentication and authorization to a Blazor Web App, accounting for the app's render mode. USE WHEN the user needs [Authorize] on pages, AuthorizeView, role or policy-based access, login/logout Identity pages, or AuthenticationStateProvider. Also USE WHEN auth state is null after WebAssembly loads, SignInManager throws in an interactive component, <NotAuthorized> content never renders in static SSR, or HttpContext.User is null in an interactive component. DO NOT USE for general component authoring (see author-component), for prerendering concerns unrelated to auth (see support-prerendering), or for managing non-auth cascading state (see coordinate-components).

5.6K 2.2K

View

dotnet/skills

create-blazor-project

Create a new ASP.NET Core web application or web site using Blazor. USE FOR: creating a new Blazor web app, scaffolding a new web project, starting a new web site, choosing render modes (Static SSR, Interactive Server, Interactive WebAssembly, Auto), running dotnet new blazor with the right options, setting up initial project structure. DO NOT USE FOR: adding features to existing projects, changing how an existing app renders, or component authoring (use author-component).

5.6K 2.2K

View

dotnet/skills

property-patterns

MSBuild property definition patterns: conditional defaults, composition/concatenation, path normalization, trailing-slash handling, TFM detection helpers, and evaluation order. USE FOR: diagnosing and fixing property definition issues and shared-property anti-patterns in .props/.csproj; DefineConstants or NoWarn overwritten instead of appended; unconditional assignments that block project-level overrides; unquoted conditions that fail on empty properties; hardcoded paths that break cross-platform builds; setting overridable defaults; property evaluation order and last-write-wins semantics. DO NOT USE FOR: props vs targets placement (use directory-build-organization), item operations (use item-management), target structure (use target-authoring), general anti-patterns (use msbuild-antipatterns), non-MSBuild build systems.

5.6K 2.2K

View

dotnet/skills

coordinate-components

Share state between components that don't have a direct parent-child parameter relationship, using cascading values, scoped services with change events, or CascadingValueSource via DI. USE WHEN the user needs a CascadingParameter or CascadingValue that works across render mode boundaries, a shopping cart or notification count accessible from multiple pages, a theme or user preference cascaded app-wide, or when components in different parts of the tree must react when shared data changes. Also USE WHEN cascading values aren't reaching interactive children in per-page interactivity mode, or when the user needs to understand scoped vs singleton service lifetime for state on Blazor Server. DO NOT USE for direct parent-child parameter passing or EventCallback (see author-component), for persisting state across prerender-to-interactive transitions (see support-prerendering), or for service abstractions for data fetching in Auto/WebAssembly (see fetch-and-send-data).

5.6K 2.2K

View

dotnet/skills

item-management

Patterns for managing MSBuild item groups: Include/Remove/Update semantics, item metadata, batching with %(Metadata), transforms, per-item filtering, and cross-product batching pitfalls. USE FOR: diagnosing and fixing item group anti-patterns in .csproj files, reviewing item management for correctness, fixing CS2002 duplicate file warnings from SDK globbing, fixing targets that run more times than expected due to cross-product batching, fixing Include vs Update misuse on SDK-globbed items, fixing FileWrites registration for generated file clean support, moving generated files to IntermediateOutputPath. DO NOT USE FOR: target chain architecture (use target-authoring), property patterns (use property-patterns), incrementality (use incremental-build), general anti-patterns (use msbuild-antipatterns), non-MSBuild build systems.

5.6K 2.1K

View

dotnet/skills

extension-points

Guide for MSBuild extensibility: CustomBefore/CustomAfter hooks, wildcard imports with alphabetic ordering, import gating with control properties, NuGet package build extension layout (build/buildTransitive), and the MicrosoftCommonPropsHasBeenImported guard. USE FOR: diagnosing and fixing MSBuild import and hook patterns, reviewing and fixing extension point anti-patterns in Directory.Build files, fixing missing Exists() guards on imports that break fresh clones, fixing NuGet package hooks being silently dropped instead of appended, making build targets extensible for other projects, injecting custom logic into the build pipeline, creating NuGet packages that extend the build, conditionally disabling imports. DO NOT USE FOR: target authoring patterns (use target-authoring), props vs targets placement (use directory-build-organization), general anti-patterns (use msbuild-antipatterns), non-MSBuild build systems.

5.6K 2.1K

View

dotnet/skills

target-authoring

Canonical patterns for writing custom MSBuild targets. USE FOR: diagnosing and fixing custom target authoring anti-patterns; broken SDK target chains across files (e.g., Directory.Build.targets silently redefining SDK targets); targets that replace CompileDependsOn instead of extending it with $(CompileDependsOn); query targets returning stale results from Outputs vs Returns misuse; missing Inputs/Outputs causing unnecessary rebuilds; missing FileWrites registration. Covers DependsOnTargets vs BeforeTargets vs AfterTargets, the Build→CoreBuild three-level pattern, and the $(XxxDependsOn) chain-extension pattern. DO NOT USE FOR: incremental build tuning (use incremental-build), parallelization (use build-parallelism), general anti-patterns (use msbuild-antipatterns), non-MSBuild build systems.

5.6K 2.1K

View

dotnet/skills

support-prerendering

Make interactive Blazor components work correctly with prerendering. USE FOR fixing duplicate data loads, UI flicker during prerender-to-interactive handoff, null references during prerender, persisting state across prerender, disabling prerendering, excluding pages from interactive routing, or detecting whether a component is currently prerendering. DO NOT USE for choosing which render mode to use (see create-blazor-project) or general component authoring (see author-component).

5.6K 2.1K

View

dotnet/skills

setup-local-sdk

Install a .NET SDK locally for safe preview testing, specific-version pinning, or reproducible team setups — without modifying the system-wide installation. USE FOR: trying .NET previews safely, testing specific SDK versions, installing MAUI or other workloads on a preview, updating or replacing an existing local SDK, creating reproducible team/CI install scripts, configuring global.json paths. DO NOT USE FOR: system-wide SDK installs, .NET hosts older than 10, runtime-only installs, or projects not using SDK-style commands.

5.6K 2.1K

View

dotnet/skills

template-comparison

Compares two or more dotnet new templates side by side to help users choose between them based on parameters, feature support, frameworks, and classifications. USE FOR: deciding between similar templates (webapi vs webapp, blazor vs blazorwasm, console vs worker), producing a side-by-side comparison of parameters and feature support, understanding how templates differ before creating a project. DO NOT USE FOR: creating a project from a template (use template-instantiation), authoring or validating custom templates (use template-authoring and template-validation), general single-template discovery (use template-discovery).

5.6K 2K

View