WinForms Designer SDK FAQ, Best Practices, News and Roadmap.

[bairog]

.NET 5/6 has an out-of-process WinForms Designer and docs for its SDK were promised for the first quarter of 2022:

There is a breaking change difference in how Designers work in Framework and .NET, so neither is this a bug, nor is it supposed to work this way.

To create a Designer for VS and .NET, you would need to use the WinForms Designer SDK. The reason is (simplified), that the Designer needs to run in the context of the Form (or the UserControl), which is .NET and not Framework. But VS is Framework. So, for the .NET Designer, there are two processes: The Client Process (Visual Studio, Framework) and a dedicated Server process (.NET) which is called the DesignToolsServer. So principally, and depending on what you need to do, you'd need to provide a NuGet which VS picks up, which holds the code for both the Server and the Client Process. And since the control and most part of the Designer logic is created in the Server process, anything Dialog-UI related needs to be marshalled from the Server process, which is not supposed to handle any dialogs due to potential dead lock concerns, back to the VS-Client.

Docs for the SDK are in the making, they are on our roadmap for the first quarter of this year.
Originally posted by @KlausLoeffelmann in #4451 (comment)

@KlausLoeffelmann First quarter of 2022 is over. Are docs for .NET WinForms Designer SDK ready?

[janseris]

The whole idea of this out-of-process designer for .NET Core (5/6) is terrible because it doesn't work properly in real use cases. I am glad to hear about any updates on it, as well.

[merriemcgaw]

@bairog , @janseris , We're working on those docs, but they're taking a bit longer than expected. We'll be getting them out to everyone as soon as we can, I promise 😄

@janseris - we didn't have any other choice as far as making an out of process designer for .NET 5+ apps. Previously WinForms Designer was running in the same process as VS, devenv.exe, which runs on .NET Framework. We had to pull the designer out into it's own .NET 5(or whatever is targeted) process and create a communication channel back to the .NET Framework process that is VS.

[janseris]

@merriemcgaw meanwhile I discovered that it might be the VS Professional version instead of Community (I am always working on the latest previe of VS 2022) working well or the problem lies solely in third party control vendors (DevExpress) designer because I have created very complicated layout without using any DevExpress controls in a new WinForms project to test this again and surprisingly everything worked very smoothly.
Thank you and your team for all your work on WinForms.
I will test this again with DevExpress controls soon.

[bairog]

@bairog , @janseris , We're working on those docs, but they're taking a bit longer than expected. We'll be getting them out to everyone as soon as we can, I promise 😄

@merriemcgaw Hope you will drop us a link as soon as docs (or at least a part of them) will be ready.
Also tagging @chris-steema as this docs will help him with .NET 5.0 OnCreateHandle override isn't called issue #4451 (and me personally is waiting for a fix in his awesome charting control library 😄)

[KlausLoeffelmann]

@bairog: Good news is, a really comprehensive demo for the SDK is 99% complete. I am in the process of documenting it, and it covers

• Simple (Server-only) Control Designers, which don't have a custom UI (Custom Type Editors), so they "only" need the SDK-ref to work like before with the most common scenarios (Adorners, Actions). Editors based on Type Converters will be possible with that (they wouldn't even need a SDK reference). Custom CodeDom Serializers are possible in this scenario, also (although they will be demo'd in the next scenario).
• Client/Server Control Designers, for Designers which have a custom UI. Those will need to have a Client, a Server, a Protocol and Package Project next to the actual Control library. The resulting assemblies (.NET Framework and .NET) need to be packed in a NuGet, and then picked up by the Designer for design time purposes. Here, we'll cover custom adorner painting, actions, Server-side type-discovery, Custom Collection Editors, Custom Type Editors, CodeDomSerializers and CollectionCodeDomSerializers. Custom Editors here is the biggest and most considerable breaking change which will need effort to rewrite existing Designers, but it's necessary to avoid deadlocks between the (.NET Framework based) Visual Studio process and the (.NET based) Server Process, which shows and manages the actual control at Design time.

We've decided to go public with that sample and a blog post first, so that folks will be able to start migrating, even with the docs not completed. Then, we'll be adding to the docs over time.

As soon I will be able to provide further info, I'll make sure to post them here.

[kirsan31]

The resulting assemblies (.NET Framework and .NET) need to be packed in a NuGet, and then picked up by the Designer for design time purposes.

This part raises the most questions... If I have a local control - can I do without nuget?

[KlausLoeffelmann]

What do you mean by local control?

[RussKie]

I presume scenarios here could be:

• a developer is building a control, and that control is located in the same project as a form, where this control is hosted, and
• a developer is building a control, and that control is located in another project within the same solution.

[KlausLoeffelmann]

Ah, OK, yes, that makes sense.

Well, if your Control Library includes controls that need a dedicated UI via custom Type Editors, then you are required to pack into a NuGet. The reason is, that the Client part needs to be loaded in the context of VS, and the Server part into the context of the DesignToolsServer. If not, so, if the Control needs let's say just custom adorners, action lists or custom CodeDom serializers, then no. You still need to build the Control Designers against the SDK, though, and you should have it in a dedicated project. But as soon as you need a custom UI for a Control Designer of the Library, those three assemblies/four projects, so the Client Part, the Server Part, the code for RPCs from Client to Server and the Packaging become a requirement.

[kirsan31]

Well, if your Control Library includes controls that need a dedicated UI via custom Type Editors, then you are required to pack into a NuGet.

Yes, this is exactly what I was afraid of :( But let's hope this is the worst thing that awaits us 😆

[KlausLoeffelmann]

While the work on the blog post is in progress, the complete SDK docs will take a while due to a shift in internal prios.
We know you're eager for sample code and starting points, so please take a look here for an early access to our SDK sample candidate:

https://github.com/KlausLoeffelmann/NetControlDesigners

[kirsan31]

@KlausLoeffelmann
I've spend some time on studying this. My thots / questions:

• At this moment everything are very confusing. The most problems I faced are absent of editors ArrayEditor, ColorEditor, FileNameEditor etc. And their methods for override EditValue, ShowHelp, CreateCollectionForm etc. The code itself for these overridden methods looks very simple in my case. Do I need to go the hard way?
• Another funny fact is that if you decide to abandon the .net framework and migrate an old project to a new designer (.net), you need to write a client in .net framework! I understand the reason behind this, BUT It evokes a sense of betrayal any way.
• All of this somehow does not inspire optimism 😥 Maybe it will become easier when the full documentation appears? 🤷‍♂️ And examples of converting old projects is defiantly needed.
• When reference a control by project reference and adding it from toolbar to the form, the exception appears (when reference a control by dll reference - all work good).

exception

Failed to create component 'Chart'.  The error message follows:

'Microsoft.DotNet.DesignTools.Client.DesignToolsServerException: Method not found: 'System.CodeDom.CodeExpression Microsoft.DotNet.DesignTools.Serialization.CodeDomSerializerBase.SerializeToExpression(System.ComponentModel.Design.Serialization.IDesignerSerializationManager, System.Object)'.

   at Microsoft.DotNet.DesignTools.Client.DesignToolsClient.<SendRequestAsync>d__49`1.MoveNext()

--- End of stack trace from previous location where exception was thrown ---

   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()

   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)

   at Microsoft.VisualStudio.Threading.JoinableTask.CompleteOnCurrentThread()

   at Microsoft.VisualStudio.Threading.JoinableTask`1.CompleteOnCurrentThread()

   at Microsoft.DotNet.DesignTools.Protocol.Endpoints.DesignToolsEndpoints.DesignerHostsImpl.CreateComponent(SessionId sessionId, TypeIdentity type, String name, NameValuePairs defaultValues)

   at Microsoft.WinForms.DesignTools.Client.Toolbox.WinFormsToolboxItem.CreateComponentsCore(IDesignerHost host, IDictionary defaultValues)

   at System.Drawing.Design.ToolboxItem.CreateComponents(IDesignerHost host, IDictionary defaultValues)

   at Microsoft.DotNet.DesignTools.Client.Designers.ParentControlProxyDesigner.CreateTool(ToolboxItem tool, IComponent parent, Nullable`1 location, Nullable`1 size, ObjectProxy toolboxSnapArgs)'

[merriemcgaw]

Maybe it will become easier when the full documentation appears? 🤷‍♂️ And examples of converting old projects is defiantly needed.

Yes, we're hoping it will make things a lot easier. And we will be investigating ways to simplify the building of controls as well as converting old controls. It's a process for sure.

[KlausLoeffelmann]

The most problems I faced are absent of editors ArrayEditor, ColorEditor, FileNameEditor etc. And their methods for override...

They are still part of both the .NET and the .NET Framework runtime, although those types as a base for derived Editors in a Server-only scenario don't make sense, since they are never deployed: The .NET types cannot run in the context of VS, and the .NET Framework types lack the infrastructure to be deployed in a server-only scenario. What you can do though in a server-only scenario is to invoke the client-types. In this case the communication between Server (the DesignToolsServer) and Client (Visual Studio) is handled automatically in the background, but only for the respective data types. So, for just using the existing editors, you currently need to include their assembly qualified type names with the Editor attribute for the respective property, and you should be good to go. Like this as an example, to enable a FileNameEditor for any property of type string:

        [Editor("System.Windows.Forms.Design.FileNameEditor, System.Design, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a",
                "System.Drawing.Design.UITypeEditor, System.Drawing, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a")]
        public string? Filename { get; set; }

Now, if you want to change the behavior of one of those editors in any way (or create new ones completely from scratch). then, yes, those editors must be running in the context of the Client. As long as you don't change the data types they are handling, you can just modify the editors in an assembly that targets the same TF version as the client, and the rest should work out of the box. But also yes, in that case your overridden types need to be loaded into the context of VS, and so you'd need to have the NuGet package deployment for that in place, even if you - in most cases - would not need to implement or change the underlaying communication between the DesignToolsServer and the client. Except you're handling different types.

Can you, just for my own understanding of the use case, provide a description of what part of the editor you want to change and to what end? That would be helpful!

[...] BUT It evokes a sense of betrayal any way

Can you clarify what you mean? What confuses me is that strong statement of yours, while you write at the same time "I understand the reason behind this".

For a bit more explanation, and that may be helping also in the understanding of our motivation to do this, because this enormous effort that we're doing with rewriting the Designer is really, really not out of some "arbitrary good idea" someone from our team had. It's a real and urgent necessity: Because we are not only addressing the .NET/.NET Framework type-resolution problem with it, so that VS runs in the context of .NET Framework and cannot resolve types from a WinForms .NET app. Rather, we cannot change but need to address the fact that Visual Studio is only one Framework and one Bitness at a time. (So, 64-Bit and .NET Framework in the case of Visual Studio 2022.) Out of that fact, please be clear about this: We will also take the Framework Designer out of process to address the problem, that we cannot - for example - host certain 32-Bit-only .NET Framework components in the 64-bit-.NET-Framework-process running Visual Studio 2022+. So, the whole effort we're doing here does not have anything to do with abandoning any .NET (Framework) version over another. On the contrary! This is a rewrite to make sure, that no matter what bitness and version Visual Studio runs in, it will always be able to host any completely different bitness/.NET version combination of the WinForms app it's providing the Designer for!

The documentation will certainly help to understand this better, but to finalize the documentation in a somewhat sane time frame, it needs more than just me working on that, so, we will be publishing not in one peace, but more and more of it over time.

And all this said - please, by any means:
Those questions of yours are really, really helpful for us and for others, and I appreciate your contribution and engagement A LOT! Please, keep those questions coming!

Best

Klaus

[KlausLoeffelmann]

Oh, and sorry, I missed your last point!

When reference a control by project reference and adding it from toolbar to the form, the exception appears (when reference a control by dll reference - all work good).

Can you provide a small sample project for this?
I would need to debug into that to see exactly what's going on.

[kirsan31]

@KlausLoeffelmann thank you for detailed answer. Especially the part about x86/x64 is something that is not quite obvious at first glance

Can you clarify what you mean? What confuses me is that strong statement of yours, while you write at the same time "I understand the reason behind this".

I will try to...

• .Net core WinForms come out.
  • WoW I want to port my control to it!
  • You can't - new designer is not ready yet.
• Waiting ~2 years...
• New designer is almost ready and usable.
  • WoW can I now to port my control?
  • You can't - we have no sdk for it.
• Waiting ~1 year...
• Preview of designer sdk come out.
  • WoW can I now to port my control? .Net is too good, I already want to completely abandon and forget about .Net Framework!
  • You can try, but if your have complex control you can't because of we have no docs how to do it...
• Waiting...
• We have some example about design user control in .Net!
  • WoW can I now to port my control and forget about .Net Framework?
  • I'm afraid - NO because you need to code client side in .Net Framework 😁
  • 😭

And the short version:

• Can I port my complex control to .Net?
• Yes, but your still need to code in .Net Framework for it :)

But perhaps this is purely my subjective perception caused by the fact that over the years I had to keep legacy .Net Framework just for the sake of the designer's work...

Can you provide a small sample project for this?
I would need to debug into that to see exactly what's going on.

Unfortunately I can't provide small project, because it's about System.Windows.Forms.DataVisualization. You can get my fork here. Everything you need for debug is already there: draft designer port and DesignerTest project (with project reference to ChartWin) with empty form.

Can you, just for my own understanding of the use case, provide a description of what part of the editor you want to change and to what end? That would be helpful!

Here is commit with my draft port: kirsan31/winforms-datavisualization@17698a2. All places that raise questions are marked with #warning designer.

[RussKie]

@kirsan31 I took your port for a spin, and it worked! Great job!

[KlausLoeffelmann]

Well,

I think from what your write, it's best to address 3 major issues, which might also be good to hear about for the rest of the community, so, again, what you write is very valuable!

I already want to completely abandon and forget about .Net Framework!

I can't share this idea.

• .NET Framework vs. .NET: Framework .NET is not at all something to label as to "give up" or "abandon". Framework will of course continue to receive updates. It certainly is and also can continue to be a great choice as a Platform especially for Desktop apps - after all it is part of the Windows OS since a really long time. Said that, yes, major functional updates are not very likely. And in that sense, it of course makes real good sense to migrate Apps from Framework to .NET long term. But that doesn't mean there is an immediate necessity to migrate everything to .NET right now. In fact, both eco systems can live together just fine, and multitargeting will certainly help to migrate Apps (not only WinForms!) over time, where it makes sense for the customer. Let me be CRYSTAL clear: As a Control Vendor you need to be ready to support .NET Framework for a long time. Not only because of the technical necessities of the Visual Studio Designer. But because our Customer's LOB Apps are of typical WinForms size are therefore often so huge and complex, that there is NO WAY that they are able to migrate those apps within months. It will only happen over a longer period of time, and that's what our support for our customers is predominantly targeted at.

• Necessity for .NET Framework in the OOP Designer That is also the reason, you need to enable to target the Client-Part of your Control Designers to a different version than the server part. Visual Studio is written in a certain Framework version, and it is therefore targeting a version which will be most likely different from the Plattform/Bitness combination you are designing an App in it for. What versions/version combinations this will be, is completely irrelevant. The relevant part is, that the Designer is OOP, not matter what the respective parts are targeted against. Please don't get too much focused that you need to provide a dedicated Framework assembly for the client, even if that is the case. The important part is, you should structure your Control Designers in a way, so they can be targeting different assembly versions, no matter what versions that actually will be. These days, we have to take different processor architectures like ARM, x86, X64, 32-/64-Bitness .NET Framework, .NET into account. So yes, Framework will be a part, at least for a long time, but the combination-ability is key here, not so much a particular combination. As I said: Even for Framework projects there is already a necessity for OOP, because type instantiation of certain 32-Bit COM types is problematic in a 64-Bit Framework process. And BTW, since you also wrote:

We have some example about design user control in .Net! WoW can I now to port my control and forget about .Net Framework? I'm afraid - NO because you need to code client side in .Net Framework 😁

The sample has both the Client (.NET Framework)/Server (.NET) and the Server-only version in it. So, is the only fact that I might be missing here, that you don't like to support .NET Framework anymore?

• Methodology of the Designer Development: I completely stand behind our approach to show results of our effort to take the Designer out of process as soon as possible, and no matter what its "ready-state" is or was, so that folks could and can start testing it. Surely, we could have developed completely behind closed doors, and would have gone public only when we would have had a "classic" first public beta. I, for once, like it better this way. And that means patients in certain areas, granted. Also keep in mind that releasing the first version of WinForms .NET doesn't mean that we need to necessarily release the .NET Designer along with it. Of course, it would have been nice, if just a recompile just did it. But that wasn't the case. But at the same time, holding of the release of the WinForms .NET Runtime would have been a much worse idea. Again, my 2 cents.

One way or the other, we can of course discuss forever the "Ifs" and "Wetheres" - but that doesn't bring us one inch/cm closer to our goals. I'd suggest concentrating on solving immediate problems now, with the person-power which we all have at our disposal. And given the work, we need to do, it is of course limited, so, prioritizing, being agile, and also being able to pivot the direction for taking on the next issue area if necessary, is something, which is good and will happen once in a while. This might be leading to decisions which not everyone always likes. But if that happens, I think the most important part is to explain decisions as much as possible and keep the dialog alive. I think this will get the best results for all of us.

[KlausLoeffelmann]

I also took the liberty to rename this issue, so people could easier assume to find answers to questions here, they are looking for. I think this is more inclusive.

[KlausLoeffelmann]

@bairog, @kirsan31, @janseris, @merriemcgaw:
What do you think about the idea to add the initial post by an [Update] section, where we add links to resources about the Designer SDK?

[merriemcgaw]

Sounds good to me. And we should work on creating that public repo with the SDK samples and official docs (and templates) for a permanent public place to direct folks to.

[weltkante]

Was anything ever released yet? I've seen it being mentioned a few times that there was going to be a blog post eventually for how you can code custom controls with designer support, but I never found one. If this was/is ready for usage, yes, discoverability needs to be improved significantly. (May be my fault for not repeatedly checking exhaustively though, I only check a few key spots regularly and hope I'll notice when something is announced.)

[kirsan31]

Was anything ever released yet? I've seen it being mentioned a few times that there was going to be a blog post eventually for how you can code custom controls with designer support, but I never found one. If this was/is ready for usage, yes, discoverability needs to be improved significantly.

No - nothing new here :(

[KlausLoeffelmann]

Well, unfortunately (and again, yes, I know!) the team has been tasks with other priorities in the meantime in the context of releasing .NET 7, and also, we're still thinking about in what scope we want to additionally address the considerable bigger effort that control libraries authors have, when we need to implement custom modal-dialog based type editors (let alone collection editors).

So, I will be back (almost) full-time this week on working on this (@merriemcgaw, @RussKie: FYI). Please also note, that samples are still available here. Please also note the different branches in that repo, reflecting different levels of completion of the examples and documentation.

In the meantime, if you have specific question or are blocked in any way, please feel free to reach out to me directly (Klaus Loeffelmann) via email firstname.lastname@microsoft.com.

[kirsan31]

@KlausLoeffelmann
Any new on this problem? I provided the necessary data for analysis here (near to the bottom of the post).
This issue also raises the question - is it possible to add user control to the controls toolbar if it was referenced by dll? Like this:

<ItemGroup>
    <Reference Include="System.Windows.Forms.DataVisualization">
        <HintPath>..\winforms-datavisualization\src\System.Windows.Forms.DataVisualization\bin\$(Configuration)\$(TargetFramework)\System.Windows.Forms.DataVisualization.dll</HintPath>
    </Reference>
</ItemGroup>

Also @paul1956 reported about new problem ( you can't drop Chart on the form in any way) in VS 17.4.0 Preview 2.0 :(

[KlausLoeffelmann]

In the context of updating the Designer SDK, we are also working on a new experience as we speak.
Again, there are a few issues which are to be addressed behind the scenes, like to synchronize with the WPF team to have a unified experience, so this is nothing to appear tomorrow-ish, but rather in the upcoming weeks. But: The current planning is to extend this setting to easier scope what leads to toolbox population and what not. NuGet packages will definitely work, so that will always be the way to go when there are libraries in external assemblies involved.

The templates and docs I am working on in particular currently will be focussing on the setup when there are Designers with Type Editors required, so they will be setting up Client-part, Server-part, the actual Control Library, the Protocol .Net Standard Assembly for communicating between client and server, and of course the NuGet packaging (which will also lead to toolbox population).

The plan is also that we will a bit later also be having simpler templates, which will include just a combined Control/Designer library for those tasks, where no type- or collection editors (or more complicated scenarios) are involved. Those, we think, should also come with a packaging project, which will again generate the required NuGet, which will then again lead to ToolBox population.

Here are a few screenshots for how the Type Editor templates can be configured from VS (command line is also possible):

Oh, and @paul1956:
Yes, the plan is to have them both for C# and VB.

[kirsan31]

Thanks @KlausLoeffelmann , but what you can tell about original questions? Mostly about bugs?

[KlausLoeffelmann]

Sorry, you mean the Serialization issue?
What other bugs, since you talk about bugs.

Do you have a simple repro for that which you could create a dedicated issue for? (I missed this one in the long thread, even with you pointing to that, so others will also.)

[kirsan31]

Do you have a simple repro for that which you could create a dedicated issue for? (I missed this one in the long thread, even with you pointing to that, so others will also.)

• The 1 problem from April 15.

  When reference a control by project reference and adding it from toolbar to the form, the exception appears (when reference a control by dll reference - all work good).

exception

Failed to create component 'Chart'.  The error message follows:

'Microsoft.DotNet.DesignTools.Client.DesignToolsServerException: Method not found: 'System.CodeDom.CodeExpression Microsoft.DotNet.DesignTools.Serialization.CodeDomSerializerBase.SerializeToExpression(System.ComponentModel.Design.Serialization.IDesignerSerializationManager, System.Object)'.

   at Microsoft.DotNet.DesignTools.Client.DesignToolsClient.<SendRequestAsync>d__49`1.MoveNext()

--- End of stack trace from previous location where exception was thrown ---

   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()

   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)

   at Microsoft.VisualStudio.Threading.JoinableTask.CompleteOnCurrentThread()

   at Microsoft.VisualStudio.Threading.JoinableTask`1.CompleteOnCurrentThread()

   at Microsoft.DotNet.DesignTools.Protocol.Endpoints.DesignToolsEndpoints.DesignerHostsImpl.CreateComponent(SessionId sessionId, TypeIdentity type, String name, NameValuePairs defaultValues)

   at Microsoft.WinForms.DesignTools.Client.Toolbox.WinFormsToolboxItem.CreateComponentsCore(IDesignerHost host, IDictionary defaultValues)

   at System.Drawing.Design.ToolboxItem.CreateComponents(IDesignerHost host, IDictionary defaultValues)

   at Microsoft.DotNet.DesignTools.Client.Designers.ParentControlProxyDesigner.CreateTool(ToolboxItem tool, IComponent parent, Nullable`1 location, Nullable`1 size, ObjectProxy toolboxSnapArgs)'

Then you asked a sample project, and my answer:

Can you provide a small sample project for this?
I would need to debug into that to see exactly what's going on.

Unfortunately I can't provide small project, because it's about System.Windows.Forms.DataVisualization. You can get my fork here. Everything you need for debug is already there: draft designer port and DesignerTest project (with project reference to ChartWin) with empty form.

And yes, I was trying to create a simple repro, but without any luck :(

Can you, just for my own understanding of the use case, provide a description of what part of the editor you want to change and to what end? That would be helpful!

Here is commit with my draft port: kirsan31/winforms-datavisualization@17698a2. All places that raise questions are marked with #warning designer.

• 2 problem is that @paul1956 reported about new problem ( you can't drop Chart on the form in any way) in VS 17.4.0 Preview 2, in Preview 1 all was good. And here are 2 posts with some details from him.

[paul1956]

@RussKie

The topic of referencing custom controls from external sources (i.e., outside the solution) has been recently discussed by the team.

My recollection of that discussion is that the direct reference of assemblies containing custom controls is not officially supported. One of the reasons is that the out-of-process designer needs to know what assemblies need to be loaded in the server process and which in the VS process (client). The designer can't possible inspect every assembly and decide where it needs to go because - it'd introduce significant perf costs.

I have the control project in my Solution.