{"record":{"id":"b4eac523cca58d8e","repo":"dotnet/wpf","slug":"sr-visual-argumentoutofrange-annotationadorner","errorCode":null,"errorMessage":"SR.Visual_ArgumentOutOfRange","messagePattern":"SR\\.Visual_ArgumentOutOfRange","errorType":"exception","errorClass":"ArgumentOutOfRangeException","httpStatus":null,"severity":"error","filePath":"src/Microsoft.DotNet.Wpf/src/PresentationFramework/MS/Internal/Annotations/Component/AnnotationAdorner.cs","lineNumber":104,"sourceCode":"\n        #endregion Public Methods\n\n        #region Protected Methods\n\n        /// <summary>\n        ///   Derived class must implement to support Visual children. The method must return\n        ///    the child at the specified index. Index must be between 0 and GetVisualChildrenCount-1.\n        ///\n        ///    By default a Visual does not have any children.\n        ///\n        ///  Remark: \n        ///       During this virtual call it is not valid to modify the Visual tree. \n        /// </summary>\n        protected override Visual GetVisualChild(int index)\n        {\n            if (index != 0 || _annotationComponent == null)\n            {\n                throw new ArgumentOutOfRangeException(nameof(index), index, SR.Visual_ArgumentOutOfRange);\n            }\n\n            return (UIElement)_annotationComponent;\n        }\n\n        /// <summary>\n        ///  Derived classes override this property to enable the Visual code to enumerate \n        ///  the Visual children. Derived classes need to return the number of children\n        ///  from this method.\n        ///\n        ///    By default a Visual does not have any children.\n        ///\n        ///  Remark: During this virtual method the Visual tree must not be modified.\n        /// </summary>        \n        protected override int VisualChildrenCount\n        {\n            get { return _annotationComponent != null ? 1 : 0; }\n        }","sourceCodeStart":86,"sourceCodeEnd":122,"githubUrl":"https://github.com/dotnet/wpf/blob/81131a70a4c573cd62748a5c36908fc4d662daa9/src/Microsoft.DotNet.Wpf/src/PresentationFramework/MS/Internal/Annotations/Component/AnnotationAdorner.cs#L86-L122","documentation":"AnnotationAdorner hosts exactly one visual child — the wrapped annotation component. GetVisualChild overrides the Visual contract and throws ArgumentOutOfRangeException when index is not 0 or when the component is null. This is a defensive check ensuring WPF's visual-tree enumeration stays consistent with VisualChildrenCount.","triggerScenarios":"WPF layout/visual enumeration calls GetVisualChild with an index outside [0, VisualChildrenCount); or enumeration races the constructor before _annotationComponent is assigned. Rarely triggered directly by user code — usually via corrupted visual bookkeeping.","commonSituations":"Custom code that overrides VisualChildrenCount inconsistently with GetVisualChild; deleting the child component while the visual tree is still being enumerated (modification during the GetVisualChild virtual call, which the framework forbids).","solutions":["Never mutate the visual tree during layout passes or inside GetVisualChild/VisualChildrenCount overrides.","Ensure VisualChildrenCount returns 1 exactly when _annotationComponent != null and 0 otherwise.","Keep the wrapped component alive for the adorner's full lifetime; don't null it out while attached.","If hit inside framework code, capture a WPF layout/visual-tree dump and report; work around by rebuilding the adorner."],"exampleFix":"// before\nprotected override int VisualChildrenCount => _annotationComponent == null ? 0 : 2; // inconsistent\n// after\nprotected override int VisualChildrenCount => _annotationComponent == null ? 0 : 1;","handlingStrategy":"validation","validationCode":"int count = adorner.VisualChildrenCount;\nbool safeIndex = count == 1; // only index 0 is valid when a component is present","typeGuard":"bool CanGetChild(AnnotationAdorner a, int i) => i == 0 && a.VisualChildrenCount == 1;","tryCatchPattern":"try { var child = adorner.GetVisualChild(i); }\ncatch (ArgumentOutOfRangeException) { /* index outside the single-child contract */ }","preventionTips":["Keep VisualChildrenCount and GetVisualChild consistent in custom adorners","Never modify the visual tree during layout/enumeration passes","Hold the wrapped component for the adorner's full lifetime"],"tags":["wpf","visual-tree","argument-out-of-range","internal-invariant"],"backgroundTag":"argument-out-of-range","analyzedSha":"81131a70a4c573cd62748a5c36908fc4d662daa9","analyzedAt":"2026-09-14T10:12:48.479Z","contentChangedAt":"2026-09-14T10:12:48.479Z","schemaVersion":2},"datasetVersion":"2026-09-22T01:17:13.364Z"}