Overview
InstallOptions provides comprehensive control over package installation behavior. These options apply to both InstallPackageAsync and UpgradePackageAsync operations.
Class Definition
runtimeclass InstallOptions
{
InstallOptions();
// Version selection
PackageVersionId PackageVersionId;
// Installation behavior
String PreferredInstallLocation;
PackageInstallScope PackageInstallScope;
PackageInstallMode PackageInstallMode;
String LogOutputPath;
Boolean AllowHashMismatch;
String ReplacementInstallerArguments;
String AdditionalInstallerArguments;
// Metadata
String CorrelationData;
String AdditionalPackageCatalogArguments;
// Architecture
IVector<ProcessorArchitecture> AllowedArchitectures { get; };
// Advanced options
Boolean AllowUpgradeToUnknownVersion;
Boolean Force;
Boolean AcceptPackageAgreements;
Boolean BypassIsStoreClientBlockedPolicyCheck;
Boolean SkipDependencies;
PackageInstallerType InstallerType;
// Authentication
AuthenticationArguments AuthenticationArguments;
}
Properties
PackageVersionId
Specifies which version to install. If not set, uses DefaultInstallVersion.
var options = new InstallOptions();
// Install specific version
var versionId = new PackageVersionId()
{
PackageCatalogId = "winget",
Version = "1.5.0",
Channel = ""
};
options.PackageVersionId = versionId;
// Or leave null for latest version
options.PackageVersionId = null; // Uses package.DefaultInstallVersion
PackageInstallScope
Specifies whether to install for current user or system-wide.
Any - Installer determines scope (default)User - Install for current user onlySystem - Install system-wide (requires admin)UserOrUnknown - User or unknown scope allowedSystemOrUnknown - System or unknown scope allowed
var options = new InstallOptions()
{
PackageInstallScope = PackageInstallScope.User
};
// For system-wide install (requires elevation)
var systemOptions = new InstallOptions()
{
PackageInstallScope = PackageInstallScope.System
};
PackageInstallMode
Controls installer UI behavior.
Default - Installer’s default experience (may show UI)Silent - Suppress UI where possibleInteractive - Show full installer UI
// Silent installation (no UI)
var options = new InstallOptions()
{
PackageInstallMode = PackageInstallMode.Silent
};
// Interactive installation
var interactiveOptions = new InstallOptions()
{
PackageInstallMode = PackageInstallMode.Interactive
};
PreferredInstallLocation
Alternate installation location (if supported by installer).
var options = new InstallOptions()
{
PreferredInstallLocation = @"D:\Programs\MyApp"
};
// Note: Not all installers support custom locations
LogOutputPath
Path to write installation log file.
var logPath = Path.Combine(
Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
"WinGet", "Logs", $"install-{DateTime.Now:yyyyMMdd-HHmmss}.log"
);
var options = new InstallOptions()
{
LogOutputPath = logPath
};
Console.WriteLine($"Install log will be written to: {logPath}");
AllowHashMismatch
Continue installation even if installer hash doesn’t match catalog.
Use with caution. Hash mismatches may indicate corrupted or tampered installers.
// Only use when absolutely necessary
var options = new InstallOptions()
{
AllowHashMismatch = true
};
ReplacementInstallerArguments
ReplacementInstallerArguments
Custom arguments that replace default installer arguments.
// Override ALL installer arguments
var options = new InstallOptions()
{
ReplacementInstallerArguments = "/S /D=C:\\CustomPath"
};
// Equivalent to: winget install --override "/S /D=C:\CustomPath"
AdditionalInstallerArguments
AdditionalInstallerArguments
Additional arguments appended to default installer arguments.
// Add to default arguments
var options = new InstallOptions()
{
AdditionalInstallerArguments = "/NORESTART /LOG=install.log"
};
// Equivalent to: winget install --custom "/NORESTART /LOG=install.log"
AcceptPackageAgreements
Automatically accept package agreements and license terms.
var options = new InstallOptions()
{
AcceptPackageAgreements = true
};
// Check agreements before accepting
var package = match.CatalogPackage;
var version = package.DefaultInstallVersion;
var metadata = version.GetCatalogPackageMetadata();
if (metadata.Agreements.Count > 0)
{
Console.WriteLine("Package requires accepting agreements:");
foreach (var agreement in metadata.Agreements)
{
Console.WriteLine($"- {agreement.Label}");
Console.WriteLine($" {agreement.Text}");
Console.WriteLine($" URL: {agreement.Url}");
}
// User confirms acceptance
options.AcceptPackageAgreements = true;
}
AllowedArchitectures
AllowedArchitectures
IVector<ProcessorArchitecture>
Allowed architectures in preference order.
using Windows.System;
var options = new InstallOptions();
// Prefer ARM64, fall back to x64
options.AllowedArchitectures.Clear();
options.AllowedArchitectures.Add(ProcessorArchitecture.Arm64);
options.AllowedArchitectures.Add(ProcessorArchitecture.X64);
// Or prefer native architecture
var arch = Package.Current.Id.Architecture;
options.AllowedArchitectures.Add(arch);
Force
Force installation, bypassing non-security related checks.
var options = new InstallOptions()
{
Force = true // Override non-critical failures
};
SkipDependencies
Skip installing package dependencies.
var options = new InstallOptions()
{
SkipDependencies = true
};
// Install only the main package, not dependencies
InstallerType
Force specific installer type when multiple are available.
Unknown - Auto-detectMsix - MSIX/AppX installerMsi - MSI installerExe - Executable installerInno - Inno SetupNullsoft - NSIS installerWix - WiX installerBurn - WiX Burn bundlePortable - Portable application
var options = new InstallOptions()
{
InstallerType = PackageInstallerType.Msi
};
// Force MSI installer if multiple types available
AllowUpgradeToUnknownVersion
AllowUpgradeToUnknownVersion
Allow upgrading to packages with unknown version.
var options = new InstallOptions()
{
AllowUpgradeToUnknownVersion = true
};
// Used for upgrade operations when version comparison isn't possible
CorrelationData
JSON-encoded correlation data returned in result.
using System.Text.Json;
var correlationData = new
{
SessionId = Guid.NewGuid().ToString(),
UserId = "user123",
Timestamp = DateTime.UtcNow
};
var options = new InstallOptions()
{
CorrelationData = JsonSerializer.Serialize(correlationData)
};
var result = await manager.InstallPackageAsync(package, options);
// Retrieve correlation data from result
Console.WriteLine($"Correlation: {result.CorrelationData}");
AuthenticationArguments
Authentication arguments for package download.
var authArgs = new AuthenticationArguments()
{
AuthenticationMode = AuthenticationMode.SilentPreferred,
AuthenticationAccount = "[email protected]"
};
var options = new InstallOptions()
{
AuthenticationArguments = authArgs
};
// Used when downloading from authenticated sources
Common Scenarios
Silent Installation
var options = new InstallOptions()
{
PackageInstallMode = PackageInstallMode.Silent,
AcceptPackageAgreements = true,
PackageInstallScope = PackageInstallScope.User
};
System-Wide Installation with Logging
var options = new InstallOptions()
{
PackageInstallMode = PackageInstallMode.Silent,
PackageInstallScope = PackageInstallScope.System,
LogOutputPath = @"C:\Logs\install.log",
AcceptPackageAgreements = true
};
// Requires administrator privileges
Custom Install Location
var options = new InstallOptions()
{
PreferredInstallLocation = @"D:\Apps\MyApplication",
PackageInstallMode = PackageInstallMode.Silent,
AdditionalInstallerArguments = "/NORESTART"
};
// Note: Not all installers support custom locations
Upgrade with Version Control
var options = new InstallOptions()
{
PackageInstallMode = PackageInstallMode.Silent,
AllowUpgradeToUnknownVersion = true,
Force = true,
LogOutputPath = Path.Combine(
Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
"Logs", $"upgrade-{DateTime.Now:yyyyMMdd-HHmmss}.log"
)
};
var result = await manager.UpgradePackageAsync(package, options);
Development/Testing Installation
var options = new InstallOptions()
{
PackageInstallMode = PackageInstallMode.Silent,
AllowHashMismatch = true, // Allow testing pre-release builds
Force = true,
SkipDependencies = false,
LogOutputPath = @"C:\Dev\Logs\install.log"
};