# ASP.NET Core Root Configuration Files: Essential Build and Project Setup

> Discover essential ASP.NET Core root configuration files like global.json, Directory.Build.props, and targets. Understand how they control the build system and SDK versioning for dotnet aspnetcore.

- Repository: [.NET Platform/aspnetcore](https://github.com/dotnet/aspnetcore)
- Tags: how-to-guide
- Published: 2026-08-01

---

**The ASP.NET Core repository root contains 15+ critical configuration files—including [`global.json`](https://github.com/dotnet/aspnetcore/blob/main/global.json), `Directory.Build.props`, and `Directory.Build.targets`—that govern the entire `dotnet/aspnetcore` build system, SDK versioning, and development environment.**

Understanding the aspnetcore root configuration files is essential for contributors and advanced users working with the `dotnet/aspnetcore` source code. These files form the backbone of the .NET Arcade tooling infrastructure, ensuring deterministic builds across Windows, macOS, and Linux. Every project under `src/` inherits settings from these root-level definitions, making them the central authority for MSBuild properties, code style enforcement, and CI pipeline configuration.

## Core Build Configuration Files

### global.json (SDK Version Pinning)

The **[`global.json`](https://github.com/dotnet/aspnetcore/blob/main/global.json)** file pins the .NET SDK version—currently `11.0.100-preview.6…`—and specifies additional SDK paths. This guarantees that every contributor builds with the same SDK, preventing version-skew breakages.

When you run [`./restore.sh`](https://github.com/dotnet/aspnetcore/blob/main/./restore.sh) or `restore.cmd` from the repository root, the build scripts read this file to bootstrap the exact SDK version required:

```bash

# From the repo root

./restore.sh          # Runs `dotnet restore` using the SDK version from global.json

dotnet --version      # → 11.0.100-preview.6…

```

### Directory.Build.props (Repository-Wide Properties)

**`Directory.Build.props`** is a repo-wide MSBuild properties file that centralizes common settings. It defines critical variables such as `RepoRoot`, `PackageProjectUrl`, `EnableNETAnalyzers`, and `SupportedRuntimeIdentifiers`.

This file also establishes conventions for unit-test detection, packaging metadata, and shared-framework settings. Because it automatically imports into every project, individual `.csproj` files remain minimal. You can override properties locally without modifying the shared file:

```xml
<!-- In a project's .csproj file -->
<PropertyGroup>
  <!-- Turn off AOT analysis for a single project -->
  <EnableAOTAnalyzer>false</EnableAOTAnalyzer>
</PropertyGroup>

```

### Directory.Build.targets (Build Extensions)

The companion **`Directory.Build.targets`** file adds repository-wide build steps that execute during the build graph evaluation. It imports the .NET Arcade SDK (`Sdk.targets`) and defines custom tasks such as trimming logs, copying symbols, and removing internal package references.

For example, the target `_CopySymbolsToArtifacts` is defined here and copies generated PDB files into the artifact folder:

```bash
dotnet build /t:_CopySymbolsToArtifacts

```

## Development Environment Configuration

### .editorconfig (Code Style Enforcement)

The **`.editorconfig`** file defines coding-style rules for C#, including indentation, naming conventions, and IDE diagnostics. Visual Studio, VS Code, and the `dotnet format` tool consult this file to enforce a uniform code style across thousands of source files.

### .vsconfig (Visual Studio Workloads)

**`.vsconfig`** lists the Visual Studio workload IDs required to develop the repository locally, such as .NET desktop, ASP.NET Core, and Azure development components. New contributors can install the correct VS components with a single click by opening this file in the Visual Studio Installer.

### .vscode/ (VS Code Workspace Settings)

The **`.vscode/`** directory contains [`tasks.json`](https://github.com/dotnet/aspnetcore/blob/main/tasks.json), [`settings.json`](https://github.com/dotnet/aspnetcore/blob/main/settings.json), [`launch.json`](https://github.com/dotnet/aspnetcore/blob/main/launch.json), and [`extensions.json`](https://github.com/dotnet/aspnetcore/blob/main/extensions.json). These files provide VS Code workspace configuration and debugging launch profiles, enabling tasks for building, debugging, and linting that respect the root configuration:

```json
{
  "label": "build",
  "type": "process",
  "command": "./restore.sh && dotnet build",
  "problemMatcher": "$msCompile"
}

```

## Dependency and Package Management

### package.json and package-lock.json (Node.js Tooling)

**[`package.json`](https://github.com/dotnet/aspnetcore/blob/main/package.json)** declares Node-based tooling—including npm scripts, linting, and formatting—used by the repository's front-end components and `eng` scripts. The accompanying **[`package-lock.json`](https://github.com/dotnet/aspnetcore/blob/main/package-lock.json)** locks exact npm package versions, guaranteeing reproducible Node builds and CI runs.

### .gitmodules (Submodule Dependencies)

**`.gitmodules`** declares submodule dependencies, such as those embedded in `src/submodules/`. This allows the repository to include external projects like `googletest` while keeping them versioned separately.

## Repository Maintenance Files

### .gitignore and .gitattributes

**`.gitignore`** lists generated artifacts—`bin/`, `obj/`, `.dotnet/`, `node_modules/`—that must not be tracked in Git, preventing binary file pollution. **`.gitattributes`** controls text/binary handling, end-of-line normalization, and diff settings to ensure consistent line endings across platforms.

### .config/ (CI Security Configuration)

The **`.config/`** directory stores [`tsaoptions.json`](https://github.com/dotnet/aspnetcore/blob/main/tsaoptions.json) and [`CredScanSuppressions.json`](https://github.com/dotnet/aspnetcore/blob/main/CredScanSuppressions.json), which configure Technical Security Assurance (TSA) and credential-scanning suppressions for automated pipelines.

## Documentation and Legal Files

- **[`README.md`](https://github.com/dotnet/aspnetcore/blob/main/README.md)** provides the high-level overview, get-started links, and badges—the first place newcomers look for documentation.
- **[`CONTRIBUTING.md`](https://github.com/dotnet/aspnetcore/blob/main/CONTRIBUTING.md)** establishes guidelines for filing issues, creating pull requests, and coding standards.
- **[`LICENSE.txt`](https://github.com/dotnet/aspnetcore/blob/main/LICENSE.txt)** contains the MIT license granting permission to use, modify, and distribute the code.

## How the Build System Consumes Root Files

When a developer runs [`./restore.sh`](https://github.com/dotnet/aspnetcore/blob/main/./restore.sh) or `dotnet build`, the SDK reads [`global.json`](https://github.com/dotnet/aspnetcore/blob/main/global.json) first. MSBuild then automatically imports `Directory.Build.props` before evaluating any individual project, followed by `Directory.Build.targets` to append custom build steps.

The root files work hierarchically: properties flow from `Directory.Build.props` down to individual projects, while targets from `Directory.Build.targets` execute after project-specific targets. This architecture ensures that the aspnetcore root configuration files serve as the single source of truth for build behavior across the entire repository.

## Summary

- **[`global.json`](https://github.com/dotnet/aspnetcore/blob/main/global.json)** pins the .NET SDK version to ensure deterministic builds across all contributors.
- **`Directory.Build.props`** centralizes MSBuild properties like `RepoRoot` and `EnableNETAnalyzers` for all projects.
- **`Directory.Build.targets`** extends the build graph with custom tasks and imports the Arcade SDK.
- **`.editorconfig`** and **`.vsconfig`** enforce consistent code style and Visual Studio setup.
- **[`package.json`](https://github.com/dotnet/aspnetcore/blob/main/package.json)** and **`.gitmodules`** manage Node.js tooling and external dependencies.
- **`.config/`** houses security scanning configuration for CI compliance.

## Frequently Asked Questions

### What is the purpose of global.json in the ASP.NET Core repository?

The [`global.json`](https://github.com/dotnet/aspnetcore/blob/main/global.json) file pins the exact .NET SDK version required to build the repository—currently `11.0.100-preview.6`—and specifies additional SDK paths. This ensures every contributor and CI pipeline uses the same SDK, preventing build breakages caused by version mismatches.

### How do Directory.Build.props and Directory.Build.targets differ?

`Directory.Build.props` sets repository-wide MSBuild properties that are imported before individual project files are evaluated, while `Directory.Build.targets` defines targets and tasks that are imported after project files. The props file configures settings like `PackageProjectUrl`, whereas the targets file adds build steps such as `_CopySymbolsToArtifacts`.

### Why does ASP.NET Core use package.json at the root?

The root [`package.json`](https://github.com/dotnet/aspnetcore/blob/main/package.json) declares Node.js-based tooling—including npm scripts, linting, and formatting—used by front-end components and engineering scripts in the `eng/` folder. The accompanying [`package-lock.json`](https://github.com/dotnet/aspnetcore/blob/main/package-lock.json) ensures reproducible Node builds by locking exact dependency versions.

### What configuration is stored in the .vscode directory?

The `.vscode/` directory contains [`tasks.json`](https://github.com/dotnet/aspnetcore/blob/main/tasks.json), [`settings.json`](https://github.com/dotnet/aspnetcore/blob/main/settings.json), [`launch.json`](https://github.com/dotnet/aspnetcore/blob/main/launch.json), and [`extensions.json`](https://github.com/dotnet/aspnetcore/blob/main/extensions.json). These files provide VS Code-specific workspace settings, build tasks, debugging launch profiles, and recommended extensions, enabling a consistent development experience that respects the repository's root configuration.