Custom Target Authoring Patterns

Canonical patterns from

Microsoft.Common.CurrentVersion.targets

in the MSBuild repository.

The Three-Level Target Chain

Every major entry point (Build, Rebuild, Clean) delegates to a property listing its dependencies, which chains through Before → Core → After:

xml

<PropertyGroup>
  <BuildDependsOn>
    BeforeBuild;
    CoreBuild;
    AfterBuild
  </BuildDependsOn>
</PropertyGroup>

<Target Name="Build"
    Condition=" '$(_InvalidConfigurationWarning)' != 'true' "
    DependsOnTargets="$(BuildDependsOn)"
    Returns="@(TargetPathWithTargetPlatformMoniker)" />

<!-- Empty extensibility targets — users override these -->
<Target Name="BeforeBuild" />
<Target Name="AfterBuild" />

CoreBuild

delegates to

$(CoreBuildDependsOn)

and includes error handlers:

xml

<Target Name="CoreBuild" DependsOnTargets="$(CoreBuildDependsOn)">
  <OnError ExecuteTargets="_TimeStampAfterCompile;PostBuildEvent"
      Condition="'$(RunPostBuildEvent)' == 'Always'" />
  <OnError ExecuteTargets="_CleanRecordFileWrites" />
</Target>

Rules

Delegate to a property (
```
DependsOnTargets="$(MyTargetDependsOn)"
```
), not hardcoded targets.
```
OnError
```
goes inside the orchestrating target to ensure cleanup runs even on failure.
Empty Before/After targets are extensibility points. Users override them; SDKs never put logic in them.

Chain Extension — Append, Never Overwrite

When adding a custom target to an existing chain, append to the

DependsOn

property:

xml

<!-- GOOD: Append to existing chain -->
<PropertyGroup>
  <CompileDependsOn>$(CompileDependsOn);MyCodeGenTarget</CompileDependsOn>
</PropertyGroup>

<!-- BAD: Overwrites the entire chain, dropping SDK targets -->
<PropertyGroup>
  <CompileDependsOn>MyCodeGenTarget</CompileDependsOn>
</PropertyGroup>

DependsOnTargets vs BeforeTargets vs AfterTargets

Mechanism	Defined in	Best for
`DependsOnTargets`	The target that needs deps	Target explicitly requires others
`BeforeTargets`	The injecting target	Insert before a target you don't own
`AfterTargets`	The injecting target	Insert after a target you don't own

Validation targets use

BeforeTargets

to intercept all entry points:

xml

<Target Name="_CheckForInvalidConfigurationAndPlatform"
    BeforeTargets="$(BuildDependsOn);Build;$(RebuildDependsOn);Rebuild;$(CleanDependsOn);Clean">
</Target>

Rules:

Use
```
DependsOnTargets
```
when your target needs specific prerequisites.
Use
```
BeforeTargets
```
/
```
AfterTargets
```
when injecting into a pipeline you don't own.
Prefer
```
BeforeTargets="CoreCompile"
```
over modifying
```
$(CompileDependsOn)
```
when you don't control the targets file.

Returns vs Outputs

xml

<!-- Build returns items for consumption by referencing projects -->
<Target Name="Build"
    DependsOnTargets="$(BuildDependsOn)"
    Returns="@(TargetPathWithTargetPlatformMoniker)" />

<!-- GetTargetPath is a lightweight query target -->
<Target Name="GetTargetPath" Returns="@(TargetPathWithTargetPlatformMoniker)" />

Returns
specifies what the MSBuild task receives when calling this project. Use for inter-project communication.
Outputs
on inner targets is for incrementality (timestamp checks). Use for up-to-date detection.
Never mix the two purposes. Query targets (
```
GetTargetPath
```
,
```
GetTargetFrameworks
```
) should use
```
Returns
```
, not
```
Outputs
```
.

Target Naming Conventions

Pattern	Meaning	Example
`_PrefixedName`	Internal/private target	`_TimeStampBeforeCompile`
`CoreXxx`	The actual implementation	`CoreBuild` , `CoreCompile`
`BeforeXxx` / `AfterXxx`	Empty extensibility hooks	`BeforeBuild` , `AfterCompile`
`PrepareXxx`	Setup/validation phase	`PrepareForBuild`
`ResolveXxx`	Discovery/resolution phase	`ResolveReferences`
`GetXxx`	Lightweight query (no side effects)	`GetTargetPath`

Complete Custom Target Template

xml

<!-- 1. Define the DependsOn chain for extensibility -->
<PropertyGroup>
  <MyFeatureDependsOn>
    _ValidateMyFeatureInputs;
    BeforeMyFeature;
    CoreMyFeature;
    AfterMyFeature
  </MyFeatureDependsOn>
</PropertyGroup>

<!-- 2. Outer target with Returns for inter-project communication -->
<Target Name="MyFeature"
    DependsOnTargets="$(MyFeatureDependsOn)"
    Returns="@(MyFeatureOutput)" />

<!-- 3. Empty extensibility points -->
<Target Name="BeforeMyFeature" />
<Target Name="AfterMyFeature" />

<!-- 4. Core implementation with Inputs/Outputs for incrementality -->
<Target Name="CoreMyFeature"
    Inputs="$(MSBuildAllProjects);@(MyFeatureInput)"
    Outputs="$(IntermediateOutputPath)myfeature.generated.cs">
  <Exec Command="my-tool.exe -o $(IntermediateOutputPath)myfeature.generated.cs" />
  <!-- 5. Register outputs for clean tracking -->
  <ItemGroup>
    <Compile Include="$(IntermediateOutputPath)myfeature.generated.cs" />
    <FileWrites Include="$(IntermediateOutputPath)myfeature.generated.cs" />
  </ItemGroup>
</Target>

<!-- 6. Validation target runs first in the dependency chain -->
<Target Name="_ValidateMyFeatureInputs">
  <Error Text="MyFeatureInput items are required."
         Condition="'@(MyFeatureInput)' == ''" />
</Target>

Common Pitfalls

Overwriting
DependsOn
properties drops SDK targets silently. Always include
```
$(ExistingProperty)
```
when appending.
Using
Outputs
on query targets causes MSBuild to skip them when "up to date," returning stale data. Use
```
Returns
```
.
Defining targets in
.props
means
```
BeforeTargets
```
on SDK targets have nothing to hook into yet. Move targets to
```
.targets
```
.
Forgetting
OnError
in orchestrating targets means file tracking fails on build errors, breaking subsequent incremental builds.

target-authoring

NPX Install

Tags

SKILL.md Content