Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/microsoft/winget-cli/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The PackageManager class is the primary entry point for the Windows Package Manager COM API. It provides methods for:
  • Installing, upgrading, uninstalling, and repairing packages
  • Searching for packages across catalogs
  • Managing package catalogs (sources)
  • Tracking installation progress
  • Downloading packages without installation

​
Class Definition

runtimeclass PackageManager
{
    PackageManager();
    
    // Catalog management
    IVectorView<PackageCatalogReference> GetPackageCatalogs();
    PackageCatalogReference GetPredefinedPackageCatalog(PredefinedPackageCatalog catalog);
    PackageCatalogReference GetLocalPackageCatalog(LocalPackageCatalog catalog);
    PackageCatalogReference GetPackageCatalogByName(String catalogName);
    PackageCatalogReference CreateCompositePackageCatalog(CreateCompositePackageCatalogOptions options);
    
    IAsyncOperationWithProgress<AddPackageCatalogResult, Double> 
        AddPackageCatalogAsync(AddPackageCatalogOptions options);
    IAsyncOperationWithProgress<RemovePackageCatalogResult, Double> 
        RemovePackageCatalogAsync(RemovePackageCatalogOptions options);
    EditPackageCatalogResult EditPackageCatalog(EditPackageCatalogOptions options);
    
    // Package operations
    IAsyncOperationWithProgress<InstallResult, InstallProgress> 
        InstallPackageAsync(CatalogPackage package, InstallOptions options);
    IAsyncOperationWithProgress<InstallResult, InstallProgress> 
        UpgradePackageAsync(CatalogPackage package, InstallOptions options);
    IAsyncOperationWithProgress<UninstallResult, UninstallProgress> 
        UninstallPackageAsync(CatalogPackage package, UninstallOptions options);
    IAsyncOperationWithProgress<RepairResult, RepairProgress> 
        RepairPackageAsync(CatalogPackage package, RepairOptions options);
    IAsyncOperationWithProgress<DownloadResult, PackageDownloadProgress> 
        DownloadPackageAsync(CatalogPackage package, DownloadOptions options);
    
    // Progress tracking
    IAsyncOperationWithProgress<InstallResult, InstallProgress> 
        GetInstallProgress(CatalogPackage package, PackageCatalogInfo catalogInfo);
    IAsyncOperationWithProgress<UninstallResult, UninstallProgress> 
        GetUninstallProgress(CatalogPackage package, PackageCatalogInfo catalogInfo);
    IAsyncOperationWithProgress<DownloadResult, PackageDownloadProgress> 
        GetDownloadProgress(CatalogPackage package, PackageCatalogInfo catalogInfo);
    
    // Version info
    String Version { get; };
}

​
Constructor

​
PackageManager()

Creates a new instance of the PackageManager. 
var manager = new PackageManager();

​
Catalog Methods

​
GetPackageCatalogs()

Retrieves all available package catalogs (sources).
​
Returns
IVectorView<PackageCatalogReference>
A collection of package catalog references
var manager = new PackageManager();
var catalogs = manager.GetPackageCatalogs();

foreach (var catalogRef in catalogs)
{
    if (!catalogRef.IsComposite)
    {
        var info = catalogRef.Info;
        Console.WriteLine($"{info.Name}: {info.Type}");
        Console.WriteLine($"  Last Updated: {info.LastUpdateTime}");
        Console.WriteLine($"  Origin: {info.Origin}");
    }
}

​
GetPredefinedPackageCatalog()

Gets a reference to a predefined catalog.
​
predefinedPackageCatalog
PredefinedPackageCatalog
required
The predefined catalog to retrieve
​
Returns
PackageCatalogReference
Reference to the predefined catalog
PredefinedPackageCatalog enum values:
  • OpenWindowsCatalog - The official WinGet community repository
  • MicrosoftStore - Microsoft Store catalog
  • DesktopFrameworks - Desktop framework packages
  • OpenWindowsCatalogFont - Font packages catalog
var manager = new PackageManager();
var catalogRef = manager.GetPredefinedPackageCatalog(
    PredefinedPackageCatalog.OpenWindowsCatalog
);

var connectResult = await catalogRef.ConnectAsync();
if (connectResult.Status == ConnectResultStatus.Ok)
{
    var catalog = connectResult.PackageCatalog;
    // Use catalog for searches
}

​
GetLocalPackageCatalog()

Gets a reference to a local package catalog.
​
localPackageCatalog
LocalPackageCatalog
required
The local catalog to retrieve
LocalPackageCatalog enum values:
  • InstalledPackages - Catalog of installed packages
  • InstallingPackages - Catalog of packages currently being installed
var manager = new PackageManager();
var catalogRef = manager.GetLocalPackageCatalog(
    LocalPackageCatalog.InstalledPackages
);

var connectResult = await catalogRef.ConnectAsync();
if (connectResult.Status == ConnectResultStatus.Ok)
{
    // Search installed packages
    var options = new FindPackagesOptions();
    var result = await connectResult.PackageCatalog.FindPackagesAsync(options);
    
    Console.WriteLine($"Installed packages: {result.Matches.Count}");
}

​
GetPackageCatalogByName()

Gets a package catalog by its registered name.
​
catalogName
String
required
Name of the catalog (e.g., “winget”, “msstore”)
var manager = new PackageManager();
var catalogRef = manager.GetPackageCatalogByName("winget");

if (catalogRef != null)
{
    var info = catalogRef.Info;
    Console.WriteLine($"Found catalog: {info.Name}");
    Console.WriteLine($"Source: {info.Argument}");
}

​
CreateCompositePackageCatalog()

Creates a composite catalog that combines multiple catalogs for unified searching.
​
options
CreateCompositePackageCatalogOptions
required
Options for creating the composite catalog
var manager = new PackageManager();

var options = new CreateCompositePackageCatalogOptions()
{
    CompositeSearchBehavior = CompositeSearchBehavior.AllCatalogs
};

// Add winget and installed catalogs
options.Catalogs.Add(
    manager.GetPredefinedPackageCatalog(PredefinedPackageCatalog.OpenWindowsCatalog)
);
options.Catalogs.Add(
    manager.GetLocalPackageCatalog(LocalPackageCatalog.InstalledPackages)
);

var compositeCatalog = manager.CreateCompositePackageCatalog(options);
var connectResult = await compositeCatalog.ConnectAsync();

if (connectResult.Status == ConnectResultStatus.Ok)
{
    // Search across all catalogs
    var findOptions = new FindPackagesOptions();
    var result = await connectResult.PackageCatalog.FindPackagesAsync(findOptions);
}

​
AddPackageCatalogAsync()

Adds a new package catalog to the system.
​
options
AddPackageCatalogOptions
required
Options for the new catalog
​
Returns
IAsyncOperationWithProgress<AddPackageCatalogResult, Double>
Async operation with progress (0-100)
var manager = new PackageManager();

var options = new AddPackageCatalogOptions()
{
    Name = "contoso",
    SourceUri = "https://contoso.com/packages",
    Type = "Microsoft.PreIndexed.Package",
    TrustLevel = PackageCatalogTrustLevel.Trusted
};

var operation = manager.AddPackageCatalogAsync(options);
operation.Progress = (op, progress) =>
{
    Console.WriteLine($"Progress: {progress}%");
};

var result = await operation;
if (result.Status == AddPackageCatalogStatus.Ok)
{
    Console.WriteLine("Catalog added successfully");
}
else
{
    Console.WriteLine($"Failed: {result.Status}");
    Console.WriteLine($"Error: 0x{result.ExtendedErrorCode:X}");
}

​
Package Operation Methods

​
InstallPackageAsync()

Installs a package with the specified options.
​
package
CatalogPackage
required
The package to install
​
options
InstallOptions
required
Installation options
​
Returns
IAsyncOperationWithProgress<InstallResult, InstallProgress>
Async operation with installation progress
See Install Options for detailed options documentation. 
var manager = new PackageManager();

// Assume 'package' was found via search
var options = new InstallOptions()
{
    PackageInstallMode = PackageInstallMode.Silent,
    PackageInstallScope = PackageInstallScope.User,
    AcceptPackageAgreements = true,
    LogOutputPath = @"C:\Logs\install.log"
};

var operation = manager.InstallPackageAsync(package, options);

operation.Progress = (op, progress) =>
{
    Console.WriteLine($"State: {progress.State}");
    
    switch (progress.State)
    {
        case PackageInstallProgressState.Downloading:
            Console.WriteLine($"Download: {progress.DownloadProgress * 100:F1}%");
            Console.WriteLine($"Downloaded: {progress.BytesDownloaded} / {progress.BytesRequired}");
            break;
            
        case PackageInstallProgressState.Installing:
            Console.WriteLine($"Install: {progress.InstallationProgress * 100:F1}%");
            break;
    }
};

var result = await operation;

if (result.Status == InstallResultStatus.Ok)
{
    Console.WriteLine("Installation successful!");
    if (result.RebootRequired)
    {
        Console.WriteLine("Reboot required to complete installation");
    }
}
else
{
    Console.WriteLine($"Installation failed: {result.Status}");
    Console.WriteLine($"Extended Error: 0x{result.ExtendedErrorCode:X8}");
    
    if (result.Status == InstallResultStatus.InstallError)
    {
        Console.WriteLine($"Installer returned: 0x{result.InstallerErrorCode:X}");
    }
}

​
UpgradePackageAsync()

Upgrades an installed package to a newer version.
​
package
CatalogPackage
required
The package to upgrade
​
options
InstallOptions
required
Upgrade options (uses InstallOptions)
var manager = new PackageManager();

// Get composite catalog to check for updates
var compositeOptions = new CreateCompositePackageCatalogOptions();
compositeOptions.Catalogs.Add(
    manager.GetPredefinedPackageCatalog(PredefinedPackageCatalog.OpenWindowsCatalog)
);
compositeOptions.Catalogs.Add(
    manager.GetLocalPackageCatalog(LocalPackageCatalog.InstalledPackages)
);
compositeOptions.CompositeSearchBehavior = CompositeSearchBehavior.RemotePackagesFromAllCatalogs;

var compositeCatalog = manager.CreateCompositePackageCatalog(compositeOptions);
var connectResult = await compositeCatalog.ConnectAsync();

// Find packages with updates
var findOptions = new FindPackagesOptions();
var findResult = await connectResult.PackageCatalog.FindPackagesAsync(findOptions);

foreach (var match in findResult.Matches)
{
    var package = match.CatalogPackage;
    if (package.IsUpdateAvailable)
    {
        Console.WriteLine($"Upgrading {package.Name}...");
        
        var upgradeOptions = new InstallOptions()
        {
            PackageInstallMode = PackageInstallMode.Silent,
            AllowUpgradeToUnknownVersion = true
        };
        
        var result = await manager.UpgradePackageAsync(package, upgradeOptions);
        Console.WriteLine($"Result: {result.Status}");
    }
}

​
UninstallPackageAsync()

Uninstalls a package from the system.
​
package
CatalogPackage
required
The package to uninstall
​
options
UninstallOptions
required
Uninstallation options
See Uninstall Options for details. 
var manager = new PackageManager();

// Find installed package
var catalogRef = manager.GetLocalPackageCatalog(
    LocalPackageCatalog.InstalledPackages
);
var connectResult = await catalogRef.ConnectAsync();

var findOptions = new FindPackagesOptions();
findOptions.Selectors.Add(new PackageMatchFilter()
{
    Field = PackageMatchField.Id,
    Value = "Microsoft.PowerToys",
    Option = PackageFieldMatchOption.Equals
});

var findResult = await connectResult.PackageCatalog.FindPackagesAsync(findOptions);

if (findResult.Matches.Count > 0)
{
    var package = findResult.Matches[0].CatalogPackage;
    
    var uninstallOptions = new UninstallOptions()
    {
        PackageUninstallMode = PackageUninstallMode.Silent
    };
    
    var result = await manager.UninstallPackageAsync(package, uninstallOptions);
    
    if (result.Status == UninstallResultStatus.Ok)
    {
        Console.WriteLine("Uninstallation successful");
    }
}

​
DownloadPackageAsync()

Downloads a package installer without installing it.
​
package
CatalogPackage
required
The package to download
​
options
DownloadOptions
required
Download options
var manager = new PackageManager();

var downloadOptions = new DownloadOptions()
{
    DownloadDirectory = @"C:\Downloads\Packages",
    AcceptPackageAgreements = true,
    SkipDependencies = false
};

var operation = manager.DownloadPackageAsync(package, downloadOptions);

operation.Progress = (op, progress) =>
{
    if (progress.State == PackageDownloadProgressState.Downloading)
    {
        Console.WriteLine($"Downloaded: {progress.BytesDownloaded} / {progress.BytesRequired}");
        Console.WriteLine($"Progress: {progress.DownloadProgress * 100:F1}%");
    }
};

var result = await operation;

if (result.Status == DownloadResultStatus.Ok)
{
    Console.WriteLine($"Download complete. Files saved to: {downloadOptions.DownloadDirectory}");
}

​
Properties

​
Version

Gets the version of the Windows Package Manager.
​
Type
String
Version string (e.g., “1.7.10514”)
var manager = new PackageManager();
Console.WriteLine($"WinGet version: {manager.Version}");

Build docs developers (and LLMs) love

Get started for freeTalk to us