Add async/await support for all long-running DISM operations

[Copilot]

The DISM API is entirely synchronous, blocking the calling thread during long-running native operations. This causes UI freezes in WPF/WinForms/MAUI apps, and Task.Run alone doesn't solve it because the native progress callback fires on the calling thread.

Adds *Async counterparts for all 17 public methods that accept DismProgressCallback, using the TaskCompletionSource pattern recommended by the maintainer.

Implementation

• Pattern: TaskCompletionSource<bool> + Task.Factory.StartNew with TaskCreationOptions.LongRunning — not Task.Run, since native DISM calls are truly long-running blocking operations
• Progress: IProgress<DismProgress> instead of DismProgressCallback (standard .NET async pattern)
• Cancellation: CancellationToken wired to DismProgress.Cancel = true, which signals the native EventWaitHandle. CancellationToken.None is passed to Task.Factory.StartNew (not the caller's token) to ensure the delegate always runs — cancellation is handled inside the delegate to avoid hanging tcs.Task when the token is already cancelled.
• Target compat: Guarded with #if !NET40 since IProgress<T> requires .NET 4.5+

Methods added

Source file	Async methods
DismApi.AddPackage.cs	AddPackageAsync
DismApi.AddCapability.cs	AddCapabilityAsync
DismApi.CheckImageHealth.cs	CheckImageHealthAsync → Task<DismImageHealthState>
DismApi.CommitImage.cs	CommitImageAsync
DismApi.DisableFeature.cs	DisableFeatureAsync
DismApi.EnableFeature.cs	EnableFeatureAsync, EnableFeatureByPackageNameAsync, EnableFeatureByPackagePathAsync
DismApi.MountImage.cs	MountImageAsync (by index), MountImageAsync (by name)
DismApi.RemoveCapability.cs	RemoveCapabilityAsync
DismApi.RemovePackage.cs	RemovePackageByNameAsync, RemovePackageByPathAsync
DismApi.RestoreImageHealth.cs	RestoreImageHealthAsync
DismApi.SetEdition.cs	SetEditionAsync, SetEditionAndProductKeyAsync
DismApi.UnmountImage.cs	UnmountImageAsync

Tests added

12 test files (33 total test methods) in src/Microsoft.Dism.Tests/, following existing conventions (DismTestBase/DismInstallWimTestBase, xUnit [Fact], Shouldly assertions). Tests are guarded with #if !NETFRAMEWORK since the test project's net472 target resolves to the main library's net40 build where async methods are excluded.

Test file	Tests
CheckImageHealthAsyncTest.cs	Happy path, cancellation, progress
AddPackageAsyncTest.cs	Cancellation, progress
AddCapabilityAsyncTest.cs	Cancellation, progress
CommitImageAsyncTest.cs	Happy path, cancellation, progress
DisableFeatureAsyncTest.cs	Cancellation, progress
EnableFeatureAsyncTest.cs	Cancellation (all 3 variants), progress
MountImageAsyncTest.cs	Happy path, cancellation (by index + by name), progress
RemoveCapabilityAsyncTest.cs	Cancellation, progress
RemovePackageAsyncTest.cs	Cancellation (both variants), progress
RestoreImageHealthAsyncTest.cs	Cancellation, progress
SetEditionAsyncTest.cs	Cancellation (both variants), progress
UnmountImageAsyncTest.cs	Happy path, cancellation, progress

Usage

// Before: blocks the calling thread
DismApi.AddPackage(session, packagePath, ignoreCheck: true, preventPending: false, callback, null);

// After: non-blocking with standard IProgress/CancellationToken
await DismApi.AddPackageAsync(session, packagePath, ignoreCheck: true, preventPending: false,
    progress: new Progress<DismProgress>(p => progressBar.Value = p.Current),
    cancellationToken: cts.Token);

Builds clean (0 warnings, 0 errors) across all four targets: net40, netstandard2.0, net8.0, net10.0. Purely additive — no existing APIs or behavior modified.

Original prompt

Add async/await support for all long-running DISM operations (Issue jeffkl#82)

Summary

Add async/await versions of all long-running DISM API methods that currently accept a DismProgressCallback. This addresses Issue jeffkl#82 in the upstream repo (jeffkl/ManagedDism), which is labeled help wanted and enhancement.

Background

The current API is entirely synchronous. Every long-running method (e.g. AddPackage, EnableFeature, MountImage, etc.) blocks the calling thread while the native DISM operation runs. This causes UI freezes in WPF/WinForms/MAUI apps.

Maintainer Guidance

The maintainer @jeffkl specifically recommended using TaskCompletionSource<T> for this implementation (NOT Task.Run). From Issue jeffkl#82:

"I haven't tried it personally, but I think the TaskCompletionSource is designed just for this, wrapping synchronous code in an async call."
— @jeffkl (Feb 2025)

Reference: https://devblogs.microsoft.com/pfxteam/the-nature-of-taskcompletionsourcetresult/

Additionally, a real user @TheJoeFin reported that simply wrapping calls in Task.Run did NOT work for their WPF app — the UI still locked up. This is likely because the native DISM progress callback fires on the calling thread, so Task.Run alone doesn't solve the progress reporting problem. TaskCompletionSource<T> combined with running the native call on a background thread and marshaling progress reports properly is the correct approach.

Current Pattern (example: AddPackage)

public static void AddPackage(DismSession session, string packagePath, bool ignoreCheck, bool preventPending, DismProgressCallback? progressCallback, object? userData)
{
    DismProgress progress = new DismProgress(progressCallback, userData);
    int hresult = NativeMethods.DismAddPackage(session, packagePath, ignoreCheck, preventPending, progress.EventHandle, progress.DismProgressCallbackNative, IntPtr.Zero);
    DismUtilities.ThrowIfFail(hresult, session);
}

Key classes involved:

• DismProgress (in src/Microsoft.Dism/DismProgress.cs) — wraps the native callback, has Cancel property that signals an EventWaitHandle, has Current/Total/UserData properties
• DismProgressCallback (in src/Microsoft.Dism/DismProgressCallback.cs) — public delegate: public delegate void DismProgressCallback(DismProgress progress);
• The internal native callback delegate is: internal delegate void DismProgressCallback(UInt32 current, UInt32 total, IntPtr userData);

Requirements

1. Add *Async methods using TaskCompletionSource<T>

For each method that currently accepts a DismProgressCallback, add an async counterpart using TaskCompletionSource<T>. The async methods should:

• Follow the MethodNameAsync naming convention
• Accept IProgress<DismProgress>? instead of DismProgressCallback? for progress reporting (standard .NET pattern)
• Accept CancellationToken for cancellation (standard .NET pattern)
• Return Task (since the sync methods return void)
• Use TaskCompletionSource<bool> (or similar) to create the Task
• Run the blocking native P/Invoke call on a background thread (via Task.Factory.StartNew with TaskCreationOptions.LongRunning or Thread)
• Use IProgress<DismProgress>.Report() inside the progress callback to marshal progress updates
• Wire CancellationToken cancellation to DismProgress.Cancel = true (which signals the native EventWaitHandle)
• When the native call completes, set the result on the TaskCompletionSource
• When cancelled, set TaskCompletionSource.TrySetCanceled()
• When an exception occurs, set TaskCompletionSource.TrySetException()

2. Example of what an async method should look like

/// <summary>
/// Asynchronously adds a single .cab or .msu file to a Windows® image.
/// </summary>
public static Task AddPackageAsync(DismSession session, string packagePath, bool ignoreCheck, bool preventPending, IProgress<DismProgress>? progress = null, CancellationToken cancellationToken = default)
{
    var tcs = new TaskCompletionSource<bool>();

    // Register cancellation
    var ctsRegistration = default(CancellationTokenRegistration);

    Task.Factory.StartNew(() =>
    {
        try
        {
            var dismProgress = new DismProgress(
                progress != null ? p => progress.Report(p) : null,
                null);

            ctsRegistration = cancellationToken.Register(() => dismProgress.Cancel = true);

            int hresult = NativeMethods.DismAddPackage(session, packagePath, ignoreCheck, preventPending, dismProgress.EventHandle, dismProgress.DismProgressCallbackNative, IntPtr.Zero);

            if (cancellationToken.IsCancellationRequested)
            {
                tcs.TrySetCanceled(cancellationToken);
            }
            else
            {
                DismUtilities.ThrowIfFail(hresult, session);
                tcs.TrySetResult(true);
            }
        }
        catch (OperationCanceledExceptio...

</details>



<!-- START COPILOT CODING AGENT TIPS -->
---

⚡ Quickly spin up Copilot coding agent tasks from anywhere on your macOS or Windows machine with [Raycast](https://gh.io/cca-raycast-docs).

[Rolling2405]

Please add xUnit tests for all the new async methods you added to this PR. Add them to the existing test project at src/Microsoft.Dism.Tests/. Follow the exact same patterns and conventions as the existing tests — use DismTestBase or TestBase as the base class, use xUnit ([Fact]), and match the file/class naming convention (e.g. AddPackageAsyncTest.cs). The tests are integration tests using the install.wim file already in the project. Cover at minimum: (1) happy path — task completes successfully, (2) cancellation — already-cancelled CancellationToken throws OperationCanceledException, (3) progress — IProgress gets called. Do NOT open a new PR — commit directly to this branch.

[Rolling2405]

Please add xUnit tests for all the new async methods you added to this PR. Add them to the existing test project at src/Microsoft.Dism.Tests/. Follow the exact same patterns and conventions as the existing tests — use DismTestBase or TestBase as the base class, use xUnit ([Fact]), and match the file/class naming convention (e.g. AddPackageAsyncTest.cs). The tests are integration tests using the install.wim file already in the project. Cover at minimum: (1) happy path — task completes successfully, (2) cancellation — already-cancelled CancellationToken throws OperationCanceledException, (3) progress — IProgress gets called. Do NOT open a new PR — commit directly to this branch.

[Copilot]

Please add xUnit tests for all the new async methods you added to this PR. Add them to the existing test project at src/Microsoft.Dism.Tests/. Follow the exact same patterns and conventions as the exi...

Added 12 test files with 33 total test methods in commit 46ac78e:

• CheckImageHealthAsyncTest.cs — happy path, cancellation, progress (3 tests)
• AddPackageAsyncTest.cs — cancellation, progress (2 tests)
• AddCapabilityAsyncTest.cs — cancellation, progress (2 tests)
• CommitImageAsyncTest.cs — happy path, cancellation, progress (3 tests)
• DisableFeatureAsyncTest.cs — cancellation, progress (2 tests)
• EnableFeatureAsyncTest.cs — cancellation for all 3 variants + progress (4 tests)
• MountImageAsyncTest.cs — happy path, cancellation by index/name, progress (4 tests)
• RemoveCapabilityAsyncTest.cs — cancellation, progress (2 tests)
• RemovePackageAsyncTest.cs — cancellation for both variants + progress (3 tests)
• RestoreImageHealthAsyncTest.cs — cancellation, progress (2 tests)
• SetEditionAsyncTest.cs — cancellation for both variants + progress (3 tests)
• UnmountImageAsyncTest.cs — happy path, cancellation, progress (3 tests)

Also fixed a cancellation bug where Task.Factory.StartNew with an already-cancelled token would hang tcs.Task forever — replaced with CancellationToken.None since cancellation is handled inside the delegate. Tests are guarded with #if !NETFRAMEWORK since the test project's net472 target resolves to the main library's net40 build.

Please add xUnit tests for all the new async methods you added to this PR. Add them to the existing test project at src/Microsoft.Dism.Tests/. Follow the exact same patterns and conventions as the exi...

Done in commit 46ac78e — 12 test files, 33 tests covering all async methods. See the other reply for the full breakdown.