DotnetInstallException.cs

// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.

namespace Microsoft.Dotnet.Installation;

/// <summary>
/// Error codes for .NET installation failures.
/// </summary>
public enum DotnetInstallErrorCode
{
    /// <summary>Unknown error.</summary>
    Unknown,

    /// <summary>The requested version was not found in the releases index.</summary>
    VersionNotFound,

    /// <summary>The requested release was not found.</summary>
    ReleaseNotFound,

    /// <summary>No matching file was found for the platform/architecture.</summary>
    NoMatchingReleaseFileForPlatform,

    /// <summary>Failed to download the archive.</summary>
    DownloadFailed,

    /// <summary>Archive hash verification failed.</summary>
    HashMismatch,

    /// <summary>Failed to extract the archive.</summary>
    ExtractionFailed,

    /// <summary>The channel or version format is invalid.</summary>
    InvalidChannel,

    /// <summary>Network connectivity issue.</summary>
    NetworkError,

    /// <summary>Insufficient permissions.</summary>
    PermissionDenied,

    /// <summary>Disk space issue.</summary>
    DiskFull,

    /// <summary>Failed to fetch the releases manifest from Microsoft servers.</summary>
    ManifestFetchFailed,

    /// <summary>Failed to parse the releases manifest (invalid JSON or schema).</summary>
    ManifestParseFailed,

    /// <summary>The archive file is corrupted or truncated.</summary>
    ArchiveCorrupted,

    /// <summary>Another installation process is already running.</summary>
    InstallationLocked,

    /// <summary>Failed to read/write the dotnetup installation manifest.</summary>
    LocalManifestError,

    /// <summary>The dotnetup installation manifest is corrupted.</summary>
    LocalManifestCorrupted,

    /// <summary>The dotnetup installation manifest was modified externally and is now corrupted.</summary>
    LocalManifestUserCorrupted,

    /// <summary>A user-managed configuration file contains malformed dotnetup state.</summary>
    UserConfigurationCorrupted,

    /// <summary>The install path points to an existing file instead of a directory.</summary>
    InstallPathIsFile,

    /// <summary>The install path is a system-managed admin path that dotnetup cannot write to.</summary>
    AdminPathBlocked,

    /// <summary>Failed to resolve the workflow context (path resolution, global.json, etc.).</summary>
    ContextResolutionFailed,

    /// <summary>The installation execution failed (download, extraction, or post-install steps).</summary>
    InstallFailed,

    /// <summary>The requested feature is not supported on the current platform.</summary>
    PlatformNotSupported,

    /// <summary>The uninstall target (install spec or tracked root) was not found.</summary>
    UninstallTargetNotFound,

    /// <summary>
    /// The install path already contains a .NET installation that is not tracked in the
    /// dotnetup manifest. The user can pass <c>--untracked</c>, point at a different path,
    /// or remove the existing install. Distinct from <see cref="Unknown"/> so the
    /// telemetry classifier can route this to the User category (it's an expected
    /// pre-existing-environment condition, not a product failure).
    /// </summary>
    InstallPathHasUntrackedArtifacts,

    /// <summary>
    /// Failed to start a child <c>dotnet</c> process (Process.Start returned null
    /// or threw). Distinct from <see cref="Unknown"/> so the telemetry classifier
    /// can route this to the Product category with a stable signal name.
    /// </summary>
    ProcessStartFailed,

    /// <summary>
    /// A release lookup against the releases index failed for an unclassified reason
    /// (the catch-all fallback after <see cref="ManifestFetchFailed"/> and
    /// <see cref="ManifestParseFailed"/>). Inner exception carries the underlying
    /// cause; this code exists so the telemetry signal isn't literally "Unknown".
    /// </summary>
    ReleaseLookupFailed,
    /// <summary>The detached CMS signature on a release manifest JSON failed verification.</summary>
    SignatureVerificationFailed,

    /// <summary>The release manifest is missing a SHA-512 hash for the archive, breaking the signed-manifest → hash → archive trust chain.</summary>
    ArchiveHashMissing,

    /// <summary>Failed to download the detached CMS signature (.p7s) sibling for a release manifest. Network-related; distinct from <see cref="SignatureVerificationFailed"/> which covers crypto / policy violations.</summary>
    SignatureDownloadFailed,

    /// <summary>An IT-managed policy requires code-signed downloads, so the install was blocked before falling back to the blob feed where only SHA-512 verification is performed.</summary>
    UnsignedDownloadBlockedByPolicy,

    /// <summary>
    /// The user supplied invalid or mutually-exclusive command-line arguments (for example
    /// combining <c>--dotnetup-only</c> with <c>--dotnet</c>/<c>--dotnetup</c>, or invoking a
    /// command that requires an argument with none provided and no stored default). Distinct from
    /// <see cref="Unknown"/> so the telemetry classifier routes it to the User category — it's
    /// bad input, not a product failure.
    /// </summary>
    InvalidArguments,

    /// <summary>
    /// The release exists for the platform but publishes no archive that dotnetup can install
    /// at the user level with only non-installable artifacts such as .exe installers.
    /// Distinct from <see cref="NoMatchingReleaseFileForPlatform"/>
    /// </summary>
    NoUserInstallableArtifact,

    /// <summary>
    /// An access mode reached a workflow that does not support it, indicating inconsistent
    /// product state rather than invalid user input.
    /// </summary>
    InvalidModeSelection,

    /// <summary>A self update holds the activity lock.</summary>
    DotnetupUpdateInProgress,

    /// <summary>The loaded executable no longer matches the installed release.</summary>
    DotnetupExecutableChanged,

    /// <summary>The installed executable's identity cannot be established.</summary>
    DotnetupIdentityUnavailable,

    /// <summary>Another self-update held the update lock beyond its timeout.</summary>
    DotnetupBusyWithUpdateOrCleanup,

    /// <summary>A non-safe command held the activity lock beyond its timeout.</summary>
    DotnetupBusyWithAnotherCommand,

    /// <summary>The replacement executable could not be verified.</summary>
    DotnetupVerificationFailed,

    /// <summary>Self-update could not restore its original executable.</summary>
    DotnetupRollbackFailed,

    /// <summary>The dotnetup executable path contains a symbolic link, junction, or other reparse point.</summary>
    DotnetupUnsupportedInstallLocation,

    /// <summary>The user declined confirmation of an operation.</summary>
    OperationCancelled,

    /// <summary>The invoked command is not supported while dotnetup is in admin mode.</summary>
    AdminModeCommandNotSupported,

    /// <summary>An option or argument passed to the command is not supported while dotnetup is in admin mode.</summary>
    AdminModeSymbolNotSupported,

    /// <summary>The operation requires <c>--untracked</c> while dotnetup is in admin mode.</summary>
    AdminModeRequiresUntracked,

    /// <summary>Admin mode could not be enabled or disabled because elevation was declined or failed, or the policy could not be written.</summary>
    AdminModeChangeFailed,

    /// <summary>Another Windows Installer (MSI) installation is in progress (exit code 1618).</summary>
    InstallerBusy,

    /// <summary>The Windows installer bundle returned a failure exit code.</summary>
    InstallerFailed,

    /// <summary>The Windows installer bundle reported success, but the expected installation could not be verified afterwards.</summary>
    InstallerPostInstallVerificationFailed,
}

/// <summary>
/// Exception thrown when a .NET installation operation fails.
/// </summary>
public class DotnetInstallException : Exception
{
    /// <summary>
    /// Gets the error code for this exception.
    /// </summary>
    public DotnetInstallErrorCode ErrorCode { get; }

    /// <summary>
    /// Gets the version that was being installed, if applicable.
    /// </summary>
    public string? Version { get; }

    /// <summary>
    /// Gets the component being installed (SDK, Runtime, etc.).
    /// </summary>
    public string? Component { get; }

    /// <summary>Standard parameterless constructor.</summary>
    public DotnetInstallException()
    {
    }

    /// <summary>Standard message constructor.</summary>
    public DotnetInstallException(string message)
        : base(message)
    {
    }

    /// <summary>Standard message + inner exception constructor.</summary>
    public DotnetInstallException(string message, Exception innerException)
        : base(message, innerException)
    {
    }

    public DotnetInstallException(DotnetInstallErrorCode errorCode, string message)
        : base(message)
    {
        ErrorCode = errorCode;
    }

    public DotnetInstallException(DotnetInstallErrorCode errorCode, string message, Exception innerException)
        : base(message, innerException)
    {
        ErrorCode = errorCode;
    }

    public DotnetInstallException(DotnetInstallErrorCode errorCode, string message, string? version = null, string? component = null)
        : base(message)
    {
        ErrorCode = errorCode;
        Version = version;
        Component = component;
    }

    public DotnetInstallException(DotnetInstallErrorCode errorCode, string message, Exception innerException, string? version = null, string? component = null)
        : base(message, innerException)
    {
        ErrorCode = errorCode;
        Version = version;
        Component = component;
    }

}