Add IsAncestorSiteInDesignMode for Control

[KlausLoeffelmann]

Rationale

WinForms Developers need a more reliable way to check, if a custom control is currently in DesignMode. The Problem is that the DesignMode property of Control does only return true, if that control is a) actually sited, and b) then returns the DesignMode property of the Site.

In many cases, DesignMode that does not help: Whenever a control is part of a constituent control (like the TextBox control in NumericUpDown) or a UserControl, the individual controls making up the UserControl (constituent control) never get sited, and although there is a Site technically which could return true for DesignMode, from the perspective of that control, that never happens.

IMPORTANT NOTE: This API's purpose is not to provide a way to check, if a control is currently hosted by a Designer for License purposes, so for them to decide, if for example the Designer UI can be made accessible, if a necessary license is present. We would need a different infrastructure for that.

Proposed API:

Add a read-only property to Control, which returns a boolean:

public bool IsAncestorSiteInDesignMode

IsAncestorSiteInDesignMode would find the first sited root (parent/ancestor) control, test for that being sited and return DesignMode, thus a rather reliable way for a control to decide if according to its context it is considering itself to be in design mode (per the WinForms definition for DesignMode).

Will this feature affect UI controls?

No.

Practically, it could be looking something like this:

        protected bool IsAncestorSiteInDesignMode =>
            GetSitedParentSite(this) is ISite parentSite ? parentSite.DesignMode : false;

        private ISite GetSitedParentSite(Control control) =>
            control is null
                ? throw new ArgumentNullException(nameof(control))
                : control.Site != null || control.Parent is null
                    ? control.Site
                    : GetSitedParentSite(control.Parent);

Real World Scenario

Let's assume we have a custom control, which uses resources, but those resources should only be used at runtime (like connections to a database, or a connection to a web service).

That means, when ever not only this custom control is in its DesignMode...

...but also one of it's parents is in their DesignMode...

...it should not touch those resources.

As soon, however, as it detects that none of its ancestors is sited (or their sites are not reporting they are in DesignMode) it can assume it's safe to use those runtime-only resources:

From the custom control's point of view, such an implementation would look like this:

    class CustomControl : Control
    {
        private Brush _cashedBackColorBrush = new SolidBrush(Color.DarkGray);
        private bool _allowRunTimeOnlyResources;

        protected override void OnHandleCreated(EventArgs e)
        {
            base.OnHandleCreated(e);
            if (!IsAncestorSiteInDesignMode) 
            {
                _allowRunTimeOnlyResources = true;
            }
        }

        protected override void OnPaint(PaintEventArgs e)
        {
            string drawText;

            base.OnPaint(e);

                e.Graphics.FillRectangle(_cashedBackColorBrush, ClientRectangle);
                var canOrNot = _allowRunTimeOnlyResources ? "can" : "should not";

                drawText = $"{this.Name} {canOrNot} use runtime resources currently.";
                CenterString(drawText);

            void CenterString(string paintText)
            {
                var textSize = e.Graphics.MeasureString(paintText, Font);

                e.Graphics.DrawString(paintText,
                    Font,
                    Brushes.Black,
                    ClientSize.Width / 2 - textSize.Width / 2,
                    ClientSize.Height / 2 - textSize.Height / 2);
            }
        }
    }

Note, that the test for being sited or not cannot be done in the custom control's constructor. Because at that time, neither the control nor its ancestor can be sited (or rather, it will probably not have ancestors at the time, since it has not been added to any control collection). So, the earliest point in time, when a custom control should check if it has been sited is after its handle got created. And since its handle gets created once the control should display its contends, in most of the cases this is an early enough point in time to decide, whether to use certain (runtime-only) types of resources or not.

[RussKie]

I think this closely relates to #3300. In my opinion the key problem with "design-time" check is that everyone has different understanding of "design time". @weltkante has laid it out nicely in #3300 (comment).

With this I think we need to break down different user scenarios, and walk from there:

1. A user control is being designed - this is what DesignMode does. We definitely need to improve the docs to clearly articulate the purpose of this property, and describe how to use it.
2. A user control has been placed on another control in the designer - a lot of user (myself included until recently) expect DesignMode to return true, but generally this returns false. This is what Design Mode check #3300 is asking for, and IIUIC this is what your proposal is for.
3. A user control is shown when an app is run (added this for completeness).

I don't think a lot of users will have a clear idea what Site is (our docs are pretty useless if we try to find out more about it), and this makes the name IsRootSiteInDesignMode almost meaningless for an average Joe developer.

[KlausLoeffelmann]

I struggled a bit with the name as well, but in the end I thought it also not a typical Joe developer scenario to begin with. Those who need it know what they are missing, and the name is honest. On top of that, I think the new API would get around comparatively quickly.

[RussKie]

it also not a typical Joe developer scenario to begin with

I disagree here, in my experience developers quite often want to do something funky at the runtime but not in the designer. GitHub shows 70K+ hits: https://github.com/search?l=C%23&q=DesignMode&type=code

[RussKie]

Browsing the GitHub I stumbled upon an implementation which is doing the same what you are proposing here - https://github.com/k3ralas/Zoo.Serialization/blob/0734d54f005f2d677d350bef2269ff4818085938/ZooRunner/ZooRunner.GUI/ControlExtensions.cs#L3

There are quite a few copies of this file in multiple repos.

[weltkante]

While the API you suggest is easy to implement it won't quite cover the use cases from #3300, namely checking DesignMode in the constructor. Many people already want to know in the constructor if the control is going to be created for the designer or for the runtime and currently were using the licensing API for that as a workaround, but apparently this workaround broke in .NET 5.

As I mentioned in the issue other .NET UI Frameworks have an API for a static design time check not relying on siting, so I'd strongly suggest WinForms to follow the precedence and not invent yet another semantic, otherwise you still have to face the problem that the workaround using the licensing system design time flag is broken.

[KlausLoeffelmann]

namely checking DesignMode in the constructor.

What people think they want is one thing, what they need another. There could be a high chance that the wrong didactic in the documentation and discoverability is the real issue here.

So, let’s discuss the actual scenarios where people need this in the constructor, so the „and I need this because...“ cases:

[IrinaPykhova]

I need it to determine that arbitrary control regardless of whether it is used by its own or inside other control is used in IDE designer, not in running application. Maybe I want to initialize some control properies differently in designer and runtime. Or maybe I don't want to run timers or background workers which only make sense for runtime. There are a lot of different scenarios. Currently I need to do the check before control is sited and finished with crazy code like this:
string ent = Assembly.GetEntryAssembly().FullName;
if ((ent.StartsWith("DesignToolsServer") && ent.EndsWith("PublicKeyToken=31bf3856ad364e35")) // VS designer

Why don' have something like this https://docs.microsoft.com/en-us/dotnet/api/system.componentmodel.designerproperties.getisindesignmode?view=netcore-3.1 in WinForms?

[KlausLoeffelmann]

Why don' have something like this https://docs.microsoft.com/en-us/dotnet/api/system.componentmodel.designerproperties.getisindesignmode?view=netcore-3.1 in WinForms?

Because we have the concept of a DesignerHost, which means we don't have the WinForms Designer per se, which is in VS, but we could have many different designers. Also, we cannot or shouldn't break existing scenarios, so detecting if the Control is sited and if that Site is in DesignMode should still be the way to go in principle.

There are a lot of different scenarios.

Sure. Let's find and discuss the important ones in particular, and let's then find out, if we really need to know already in the constructor, if a control is in design mode. My assumption is that things will work...

• by having lazy properties.
• by defining Design Time or Shadow Properties with a dedicated Designer.
• by testing only in OnPaint (probably more than 50% of the cases need a IsDesignTime property for just that.)
• by determining if the control is in Design Mode in OnHandleCreated.

Let's not be vague, but concrete in the discussion.

Currently I need to do the check before control is sited and finished with crazy code like this:
string ent = Assembly.GetEntryAssembly().FullName;
if ((ent.StartsWith("DesignToolsServer") && ent.EndsWith("PublicKeyToken=31bf3856ad364e35"))

I don't think that this is necessary, but we would need to discuss the concrete use case.

Currently I need to do the check before control is sited and finished with crazy code like this:

                string ent = Assembly.GetEntryAssembly().FullName;
                if ((ent.StartsWith("DesignToolsServer") && ent.EndsWith("PublicKeyToken=31bf3856ad364e35")) // VS designer

You should be aware, that this code has a chance to break in the future, because we cannot guaranty that that name will stay the same. (I think you know this already, I just want to point it out, since it's important.)

[KlausLoeffelmann]

Browsing the GitHub I stumbled upon an implementation which is doing the same what you are proposing here - https://github.com/k3ralas/Zoo.Serialization/blob/0734d54f005f2d677d350bef2269ff4818085938/ZooRunner/ZooRunner.GUI/ControlExtensions.cs#L3

@RussKie: Yes, and I think that is the reason we should have this on board. This solution also provides the Best Practice Guide, and I think having that _and _ the correct accompanying documentation, we'd be covering 90% of all use cases. The documentation pointing out the different use cases is as important, though.

[KlausLoeffelmann]

We're (WinForms Team) discussing naming.

• IsRootSiteInDesignMode (too "long" probably, but differentiate and explains difference from DesignMode)
• RootDesignMode (we like that one!)
• IsInDesignMode (too close to DesignMode)
• IsInDesigner - probably not honest, too close to DesignMode.

[weltkante]

RootDesignMode (we like that one!)

I like that one as well, but note that your implementation stops at the first site, so naming it Root is lying a bit. Sites are sometimes (very rarely) used in other scenarios than designers, and in that case you may stop early and not determine the DesignMode of the root control.

You could change your lookup code to actually compute the "root site", or leave as-is and live with the fact that it will behave weirdly if sites are used for anything but designers

Alternatively you may want to change the algorithm entirely and not look at any single site, but compute the 'logical or' of all parent sites, i.e. determine if any site in the parent chain is in DesignMode, not just the first or last site. The lookup can short-circuit and return as soon as any site is in design mode. Looping up to the root if none is in design mode is the same as would happen with the originally proposed algorithm.

[IrinaPykhova]

@KlausLoeffelmann I'm absolutely sure that my solution is bad, that's why I want to see more solid way to determine design-time environment. Suggestion about testing in OnPaint is awful. OnPaint should only paint. And what if it is UI-less component?
Personally, when I implement some control, I usually want to do heavy initialization before painting or creating handle, so that end-user doesn't see any delays or blinking UI.
But let's look at generic case, imagine that customer should have proper license to use your control. In old days MS recommended to do license check in control constructor:
https://docs.microsoft.com/en-us/dotnet/api/system.componentmodel.licenseprovider?view=netcore-3.1
We ship a lot of controls all following this logic. We changed licensing mechanism for .Net 5 but still check license in ctors. Now, I need a way to understand whether I should only check runtime license, or control is used in designer and I can check local machine file system or registry. Should I change every our control and move license checks to other places? And then test whether it makes the hole allowing using our controls without license? Do you see that as real use case?
My guess is that author of #3300 also tried to check license