What Scripts and Tools Are in the ASP.NET Core `eng` Directory?

The eng directory in the dotnet/aspnetcore repository contains cross-platform automation scripts—Shell for Linux/macOS, PowerShell for Windows, and Node.js modules—that handle SDK installation, dependency provisioning, Helix test orchestration, and release shipping.

The eng folder serves as the central nervous system for the ASP.NET Core build infrastructure. Located at the root of the dotnet/aspnetcore repository, this directory houses the essential scripts and tools in the eng directory that power CI/CD pipelines across Azure Pipelines, Helix, and GitHub Actions. These automation assets ensure reproducible builds and reliable testing across Linux, macOS, and Windows environments.

Build and Source Preparation Scripts

SDK Installation and Global JSON Configuration

The foundation of every build starts with proper tooling setup. The eng/common/dotnet-install.ps1 and eng/common/dotnet-install.sh scripts download and extract the required .NET SDK version, ensuring runtime consistency across agents. For source-build scenarios, eng/scripts/prepare-sourcebuild-globaljson.sh generates a pinned global.json file that locks the exact SDK version. Legacy Windows agents invoke these through eng/common/dotnet.cmd, a thin batch wrapper that forwards calls to the PowerShell implementation.

Source-Build Preparation

When building from source, maintaining exact dependency versions is critical. The prepare-sourcebuild-globaljson.sh script creates the necessary configuration files to ensure the build uses the correct toolset versions rather than floating dependencies.

Dependency and Toolset Installation Tools

Third-Party Component Setup

Integration testing requires external dependencies that must be provisioned dynamically. The repository includes platform-specific installers for these components:

• eng/scripts/install-nginx.sh installs NGINX on Linux agents for reverse proxy testing
• eng/scripts/InstallJdk.ps1 sets up the Java Development Kit on Windows for Java-based integration tests
• eng/scripts/InstallGoogleChrome.ps1 provisions Chrome for Playwright and Selenium UI automation
• eng/scripts/InstallVisualStudio.ps1 configures VS 2019 or VS 2022 build tools on Windows agents

Node.js Package Management

For the JavaScript and TypeScript components of ASP.NET Core, eng/scripts/npm/update-dependency-versions.mjs automates npm package maintenance. This Node module scans workspace package.json files and bumps versions according to repository policy, ensuring consistent frontend dependencies.

Process Management and Diagnostic Scripts

Flaky builds and hanging processes require aggressive monitoring. The diagnostic toolkit includes eng/scripts/KillProcesses.sh and eng/scripts/CaptureHangDumps.sh for Linux/macOS environments, which clean up stray processes and collect core dumps. Windows agents use eng/scripts/StartDumpCollectionForHangingBuilds.ps1 and eng/scripts/FinishDumpCollectionForHangingBuilds.ps1 to wrap dump collection around build steps. For post-mortem analysis, eng/scripts/upload-cores.sh uploads debugging cores to Azure Blob storage.

Helix Test Execution Orchestration

Distributed testing across the Helix infrastructure relies on scripts that bridge the repository and test agents. The eng/helix/content/runtests.sh and eng/helix/content/runtests.cmd scripts serve as entry points on Helix agents, while eng/scripts/RunHelix.ps1 orchestrates the entire workflow from the build machine. This PowerShell script queues jobs, manages retries, and streams logs back to the pipeline.

Release and Shipping Automation

Shipping official releases requires metadata updates and artifact management. The eng/scripts/mark-shipped.ps1 script updates version numbers and adds "shipped" metadata to mark builds as released. Supporting infrastructure includes eng/scripts/upload-cores.sh for debugging artifact retention.

Arcade Integration and Shared Tooling

Many scripts and tools in the eng directory delegate to the shared Arcade build system located in eng/common/. The eng/common/tools.sh script provides essential utility functions—including log, exec, and setvar—that other scripts source for consistent output formatting. Repository synchronization is handled by eng/common/vmr-sync.sh, which keeps the local VMR (Version-Managed Repository) aligned with upstream Arcade sources.

Practical Usage Examples

Preparing a Source Build on Linux

chmod +x eng/scripts/prepare-sourcebuild-globaljson.sh
./eng/scripts/prepare-sourcebuild-globaljson.sh

Installing Java on Windows Agents

powershell -ExecutionPolicy Bypass -File eng/scripts/InstallJdk.ps1 -Version 11.0.22

Running Helix Tests

.\eng\scripts\RunHelix.ps1 -HelixQueue "Windows.10.Arm64.VS2022" -TestCategory "runtime"

Updating npm Dependencies

node eng/scripts/npm/update-dependency-versions.mjs

Summary

• The eng directory contains Shell, PowerShell, Batch, and Node.js scripts that automate the entire ASP.NET Core development lifecycle.
• Build preparation scripts like prepare-sourcebuild-globaljson.sh and dotnet-install.ps1 ensure consistent SDK provisioning across Linux, macOS, and Windows.
• Helix test execution relies on RunHelix.ps1 and platform-specific runners in eng/helix/content/ to distribute tests across multiple machine configurations.
• Diagnostic tools including CaptureHangDumps.sh and StartDumpCollectionForHangingBuilds.ps1 help identify and resolve flaky build issues.
• Arcade integration through eng/common/ provides shared utilities and VMR synchronization for maintaining build system consistency.

Frequently Asked Questions

What is the purpose of the eng directory in ASP.NET Core?

The eng directory houses automation scripts and build tools that orchestrate CI/CD pipelines, manage dependencies, execute distributed tests via Helix, and handle release shipping for the dotnet/aspnetcore repository. It separates infrastructure concerns from product code while providing cross-platform consistency.

How do Helix test scripts work in the eng folder?

Helix scripts operate in two phases: eng/scripts/RunHelix.ps1 queues jobs and manages orchestration from the build agent, while eng/helix/content/runtests.sh (Linux/macOS) and runtests.cmd (Windows) execute the actual test harness on remote Helix agents. This architecture enables distributed testing across dozens of machine configurations simultaneously.

Which script installs the .NET SDK during CI builds?

The eng/common/dotnet-install.ps1 (Windows) and eng/common/dotnet-install.sh (Linux/macOS) scripts handle SDK acquisition. These download and extract the specific .NET version defined in the repository's global.json, ensuring all CI agents use identical tooling.

How does the repository handle cross-platform build automation?

ASP.NET Core uses platform-appropriate scripting languages: Shell scripts (.sh) for Linux and macOS agents, PowerShell (.ps1) for modern Windows environments, and Batch (.cmd) wrappers for legacy Windows compatibility. Shared logic resides in eng/common/tools.sh and equivalent PowerShell modules to maintain consistency across operating systems.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}