dotnet/wpf · error · InvalidOperationException

SR.UsesPerPixelOpacityIsObsolete

Error message

SR.UsesPerPixelOpacityIsObsolete

What it means

HwndSourceParameters.UsesPerPixelOpacity is obsolete in favor of UsesPerPixelTransparency. An application that sets both the old UsesPerPixelOpacity and the new UsesPerPixelTransparency throws InvalidOperationException (SR.UsesPerPixelOpacityIsObsolete) because the two settings conflict and the library refuses ambiguous configuration.

Solutions

1. Remove the UsesPerPixelOpacity assignment and use only UsesPerPixelTransparency
2. If legacy behavior is required, do not set UsesPerPixelTransparency on the same parameters object

Example fix

// before
var p = new HwndSourceParameters();
p.UsesPerPixelOpacity = true;
p.UsesPerPixelTransparency = true; // throws
// after
var p = new HwndSourceParameters();
p.UsesPerPixelTransparency = true;

if (p.UsesPerPixelOpacity && p.UsesPerPixelTransparency) p.UsesPerPixelOpacity = false;

try { CreateHwndSource(p); } catch (InvalidOperationException) { /* flags conflict: drop legacy property */ }

When it happens

Trigger: Setting UsesPerPixelOpacity = true (the legacy API) and then also setting UsesPerPixelTransparency on the same HwndSourceParameters struct before passing it to HwndSource construction.

Common situations: Migrating code from .NET 3.5/4.x per-pixel-opacity APIs to the newer transparency API while keeping old property assignments; copy-pasted sample code that sets both.

Understand the failure class

Background: "is deprecated and will be removed" — deprecation warnings for old API names, keywords, and options, and how to migrate before the removal release — this error's family across 29 libraries.

Related errors

• 0x80070057
• ArgumentNullException (buffer/sourceBuffer was IntPtr.Zero)
• Buffer address passed to GetText cannot be NULL.
• FormatException
• InvalidOperationException

AI-assisted analysis of dotnet/wpf@81131a70a4 (2026-09-14). Data as JSON: /api/errors/90445b51a599d1e6. Report an issue: GitHub.

Appendix: source

Thrown at src/Microsoft.DotNet.Wpf/src/PresentationCore/System/Windows/InterOp/HwndSourceParameters.cs:301

        /// <summary>
        /// Returns the effective per pixel opacity property given the style and the underlying platform
        /// </summary>
        /// <remarks>
        /// Before Windows 8, Layered child windows were not possible and UsesPerPixelOpacity was ignored when
        /// WS_CHILD was used. For compatibility reasons:
        ///   - we introduce UsesPerPixelTransparency which can be set for WS_CHILD windows
        ///   - we mark as deprecated but still honor UsesPerPixelOpacity
        /// </remarks>
        internal bool EffectivePerPixelOpacity
        {
            get
            {
                if (_usesPerPixelTransparency)
                {
                    // Applications aware of the new property should not set the old one too
                    if (_usesPerPixelOpacity)
                    {
                        throw new InvalidOperationException(SR.UsesPerPixelOpacityIsObsolete);
                    }

                    // If not running on Windows 8, we must clear the parameter for child windows
                    return PlatformSupportsTransparentChildWindows || ((WindowStyle & NativeMethods.WS_CHILD) == 0);
                }
                else
                {
                    // Application does not want transparency or else uses old API
                    // In the second case, we do not support WS_CHILD
                    return _usesPerPixelOpacity && ((WindowStyle & NativeMethods.WS_CHILD) == 0);
                }
            }
        }

        /// <summary>
        /// == operator
        /// </summary>
        /// <param name="a"></param>

View on GitHub (pinned to 81131a70a4)