{"record":{"id":"802fc91854fe0fac","repo":"dotnet/wpf","slug":"sr-annotationadorner-notuielement","errorCode":null,"errorMessage":"SR.AnnotationAdorner_NotUIElement","messagePattern":"SR\\.AnnotationAdorner_NotUIElement","errorType":"exception","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"src/Microsoft.DotNet.Wpf/src/PresentationFramework/MS/Internal/Annotations/Component/AnnotationAdorner.cs","lineNumber":43,"sourceCode":"\n        /// <summary>\n        /// Return an initialized annotation adorner\n        /// </summary>\n        /// <param name=\"component\">The annotation component to wrap in the annotation adorner</param>\n        /// <param name=\"annotatedElement\">element being annotated</param>\n        public AnnotationAdorner(IAnnotationComponent component, UIElement annotatedElement) : base(annotatedElement)\n        {\n            //The summary on top of the file says:-\n            //The wrapped component must be at least a UIElement\n            if (component is UIElement)\n            {\n                _annotationComponent = component;\n                // wrapped annotation component is added as visual child\n                this.AddVisualChild((UIElement)_annotationComponent);\n            }\n            else\n            {\n                throw new ArgumentException(SR.AnnotationAdorner_NotUIElement, nameof(component));\n            }\n        }\n\n        #endregion Constructors\n\n        #region Public Methods\n\n        /// <summary>\n        /// Forwarded to the annotation component to get desired transform relative to the annotated element\n        /// </summary>\n        /// <param name=\"transform\">Transform to adorned element</param>\n        /// <returns>Transform to annotation component </returns>\n        public override GeneralTransform GetDesiredTransform(GeneralTransform transform)\n        {\n            //if the component is not visual we do not need this\n            if (!(_annotationComponent is UIElement))\n                return null;\n","sourceCodeStart":25,"sourceCodeEnd":61,"githubUrl":"https://github.com/dotnet/wpf/blob/81131a70a4c573cd62748a5c36908fc4d662daa9/src/Microsoft.DotNet.Wpf/src/PresentationFramework/MS/Internal/Annotations/Component/AnnotationAdorner.cs#L25-L61","documentation":"The AnnotationAdorner constructor wraps an annotation component as its visual child and therefore requires it to be a UIElement. When the passed IAnnotationComponent is not a UIElement, an ArgumentException with SR.AnnotationAdorner_NotUIElement is thrown. Annotation adorners are Visual-layer wrappers, so only visual elements can be hosted.","triggerScenarios":"Calling new AnnotationAdorner(component) where component is an IAnnotationComponent implementation that does not derive from UIElement (e.g. a custom non-visual annotation component).","commonSituations":"Writing a custom IAnnotationComponent that implements the interface without inheriting from a UIElement base class (such as TextPanel/ContentPresenter-based components used by the built-in HighlightComponent); casting/refactoring code that changed a component's base class away from UIElement.","solutions":["Make the custom annotation component derive from a UIElement-based class before wrapping it in AnnotationAdorner.","Validate component is UIElement before constructing the adorner and fail fast with a clear message.","Use one of the framework-provided components (e.g. TextHighlightComponent) which are UIElements.","If the component genuinely cannot be visual, wrap its visuals in a UIElement host rather than the component itself."],"exampleFix":"// before\nIAnnotationComponent comp = new MyNonVisualComponent();\nvar adorner = new AnnotationAdorner(comp); // ArgumentException\n// after\nif (comp is not UIElement)\n    throw new ArgumentException(\"Annotation component must be a UIElement\");\nvar adorner = new AnnotationAdorner(comp);","handlingStrategy":"validation","validationCode":"if (component is not UIElement)\n    throw new ArgumentException(\"Annotation component must be a UIElement\", nameof(component));","typeGuard":"bool IsWrappable(IAnnotationComponent c) => c is UIElement;","tryCatchPattern":"try { var adorner = new AnnotationAdorner(component); }\ncatch (ArgumentException) { /* component is not a UIElement */ }","preventionTips":["Derive custom IAnnotationComponent implementations from UIElement-based classes","Assert UIElement-ness at component construction time, not adorner time","Prefer framework-provided annotation components when possible"],"tags":["wpf","annotations","type-mismatch","argument"],"backgroundTag":"type-mismatch","analyzedSha":"81131a70a4c573cd62748a5c36908fc4d662daa9","analyzedAt":"2026-09-14T10:12:48.479Z","contentChangedAt":"2026-09-14T10:12:48.479Z","schemaVersion":2},"datasetVersion":"2026-09-21T21:30:21.729Z"}