{"record":{"id":"faaca9b9ec9420a6","repo":"PrismLibrary/Prism","slug":"the-view-must-inherit-from-visualelement","errorCode":null,"errorMessage":"The view must inherit from VisualElement.","messagePattern":"The view must inherit from VisualElement\\.","errorType":"exception","errorClass":"UpdateRegionsException","httpStatus":null,"severity":"error","filePath":"src/Maui/Prism.Maui/Navigation/Regions/Region.cs","lineNumber":267,"sourceCode":"    /// <summary>\n    /// Adds a new view to the region.\n    /// </summary>\n    /// <param name=\"view\">The view to add.</param>\n    /// <param name=\"viewName\">The name of the view. This can be used to retrieve it later by calling <see cref=\"IRegion.GetView\"/>.</param>\n    /// <param name=\"createRegionManagerScope\">When <see langword=\"true\"/>, the added view will receive a new instance of <see cref=\"IRegionManager\"/>, otherwise it will use the current region manager for this region.</param>\n    /// <returns>The <see cref=\"IRegionManager\"/> that is set on the view if it is a <see cref=\"VisualElement\"/>.</returns>\n    public virtual IRegionManager Add(object view, string viewName, bool createRegionManagerScope)\n    {\n        IRegionManager manager = createRegionManagerScope ? RegionManager.CreateRegionManager() : RegionManager;\n        InnerAdd(view, viewName, manager);\n        return manager;\n    }\n\n    private void InnerAdd(object view, string viewName, IRegionManager scopedRegionManager)\n    {\n        if (view is not VisualElement visualElement)\n        {\n            throw new UpdateRegionsException(\"The view must inherit from VisualElement.\");\n        }\n\n        if (ItemMetadataCollection.FirstOrDefault(x => x.Item == view) != null)\n        {\n            throw new InvalidOperationException(Resources.RegionViewExistsException);\n        }\n\n        var itemMetadata = new ItemMetadata(visualElement);\n        if (!string.IsNullOrEmpty(viewName))\n        {\n            if (ItemMetadataCollection.FirstOrDefault(x => x.Name == viewName) != null)\n            {\n                throw new InvalidOperationException(string.Format(CultureInfo.InvariantCulture, Resources.RegionViewNameExistsException, viewName));\n            }\n            itemMetadata.Name = viewName;\n        }\n\n        Xaml.RegionManager.SetRegionManager(visualElement, scopedRegionManager);","sourceCodeStart":249,"sourceCodeEnd":285,"githubUrl":"https://github.com/PrismLibrary/Prism/blob/358118cd640d9a22ff8cf21c8ad197fa038b7990/src/Maui/Prism.Maui/Navigation/Regions/Region.cs#L249-L285","documentation":"Region.InnerAdd throws UpdateRegionsException when a view added to a region does not derive from VisualElement (the MAUI base class for anything with visual layout). Regions track, name, activate and deactivate views, and all of that bookkeeping requires a VisualElement. Any non-VisualElement object passed to IRegion.Add is rejected immediately.","triggerScenarios":"Calling region.Add(someObject) or region.Add(someObject, \"name\") where someObject is not a Microsoft.Maui.Controls.VisualElement (e.g. a plain ViewModel, a string, or a non-visual service object).","commonSituations":"Registering ViewModels instead of Views for region navigation; registering a plain class as a view; MAUI bindings/registration mistakes where the container resolves the wrong type; porting WPF Prism code where objects that were not UIElement were tolerated by custom adapters.","solutions":["Make sure the type registered for the region is a MAUI Page, ContentView, Layout or other VisualElement subclass, not the ViewModel.","Check your RegisterForRegionNavigation / RegisterForNavigation<T> registration: T must be a VisualElement-derived view.","If you need a ViewModel in the region, use ViewModelLocator (ViewModelLocator.AutowireViewModel) on a VisualElement view rather than adding the ViewModel itself.","Wrap non-visual content in a ContentView/ContentPage that hosts it before adding to the region."],"exampleFix":"// before\nregion.Add(myViewModel);\n\n// after\nvar view = new MyContentView(); // MyContentView : ContentView\nViewModelLocator.SetAutowireViewModel(view, true);\nregion.Add(view);","handlingStrategy":"type-guard","validationCode":"if (view is not VisualElement) throw new InvalidOperationException($\"Cannot add {view?.GetType().Name} to region: must be a VisualElement\");","typeGuard":"static bool IsValidRegionView(object v) => v is Microsoft.Maui.Controls.VisualElement;","tryCatchPattern":"try { region.Add(view); } catch (UpdateRegionsException ex) { logger.LogError(ex, \"View is not a VisualElement\"); }","preventionTips":["Always register view types (VisualElement subclasses) for region navigation, never ViewModels","Use ViewModelLocator autowiring instead of adding ViewModels directly","Add a unit test asserting registered region view types derive from VisualElement"],"tags":["prism","maui","regions","type-mismatch"],"backgroundTag":"type-mismatch","analyzedSha":"358118cd640d9a22ff8cf21c8ad197fa038b7990","analyzedAt":"2026-09-15T15:00:31.079Z","contentChangedAt":"2026-09-15T15:00:31.079Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}