Summary

Currently the IDE does not offer built-in support for configuring headers (aka file banners or copyright headers) expected to appear in source files. This proposal defines a simple analyzer and code fix combination to support a majority of cases used in practice.

When configured, Roslyn would be responsible for adding a file header to newly-created source files it recognizes. Other language services would have access to the .editorconfig configuration and could follow suit (the property is defined in a manner that others could follow).

Variables

The following built-in variables may be used in defining the expected file header content.

Configuration

The expected header content is provided as a template. Substitution variables may be referenced in curly braces, such as {fileName}. The sequence \n may be used for a single newline in the document.

Header forms

File headers in C# source files are allowed to have any of the following forms. The first form is preferred, meaning it is used when the code fix inserts a new comment into a file which did not previously have one.

// line 1
// line 2
// line 3
// ...

/* line 1
 * line 2
 * line 3
 * ...
 */

/* line 1
   line 2
   line 3
   ... */

Examples

Single-line header

The following configuration could be used for the code in this repository prior to #25423:

file_header_template = Copyright (c) Microsoft.  All Rights Reserved.  Licensed under the Apache License, Version 2.0.  See License.txt in the project root for license information.

Files would be expected to start with the comment:

// Copyright (c) Microsoft.  All Rights Reserved.  Licensed under the Apache License, Version 2.0.  See License.txt in the project root for license information.

Multi-line header

The following could be used to implement the three-line header requested in #25423:

file_header_template = Licensed to the .NET Foundation under one or more agreements.\nThe .NET Foundation licenses this file to you under the MIT license.\nSee the LICENSE file in the project root for more information.

Files would be expected to start with the comment:

// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
// See the LICENSE file in the project root for more information.

StyleCop-compatible header

The following could be used to define a simple StyleCop-compatible XML header:

file_header_template = <copyright file="{fileName}" company="Your Company Here">\nYour copyright text here\n</copyright>

The file MyFile.cs would be expected to start with the comment:

// <copyright file="MyFile.cs" company="Your Company Here">
// Your copyright text here
// </copyright>

Frequently asked questions

What about a {currentYear} variable?

tl;dr: The currentYear variable is not required. Simply replace {currentYear} in your template with the year you expect to appear in file headers.

Implementing validation using the year as a variable is highly problematic in practice for two reasons:

1. The success of the build depends on when the build runs. It is impossible to create commits which will build successfully a year later.
2. Forcing the header to a later date via analysis would result in a post-dated copyright notice for the code. Depending on the specific country, this is likely to result in an invalid copyright date, a situation which can result in the loss of certain types of copyright protection otherwise afforded to projects.

Fixed dates in the file header template support headers with the strongest copyright protections. Projects which require other approaches may not be able to use this analyzer, but please feel free to use the code for the built-in analyzer under its open source licensing terms to implement a package supporting other specific scenarios.

Notable changes

The following are notable changes to this proposal as a result of comments in the thread below.

• Changed dotnet_style_file_header_template to file_header_template (per Proposal: File header validation analyzer and fix #33012 (comment))
• Clarify that Roslyn would automatically apply the header to new source files (per Proposal: File header validation analyzer and fix #33012 (comment))