The Out-Of-Process WinForms Designer<\/h2>\n
Until we added support in Visual Studio for .NET Core WinForms applications,\nthere was only a single process, devenv.exe<\/em>, that both the Visual Studio\nenvironment and the WinForms application being designed ran within. But .NET\nFramework and .NET Core can\u2019t both run together within the devenv.exe<\/em> process,\nand as a result we had to take part of the designer out of process to support\n.NET applications. Since .NET Core 3.0 started to support the WinForms .NET\nRuntime, a new WinForms designer was needed to support .NET applications. This\nwork required a near-complete re-architect of the designer as we responded to\nthe differences between .NET and the .NET Framework based WinForms designer\neveryone knows and loves. Developers need to see their Forms in the designer\nlooking precisely the way it will at runtime (WYSIWYG). Whether it is about a\n To handle the interaction with Visual Studio, we have introduced proxy classes\n(.NET Framework You can read more about the details about the concept of the two processes in\nthis blog post\nabout<\/a>\nthe state of the WinForms Designer.<\/p>\n For the design-time support, this has consequences. One principle of WinForms\ncontrols is that each control brings its own Designer: For a Depending on what type of UI-based Design time functionality your Designer\nprovides, the coding effort compared to .NET Framework maybe the same or almost the\nsame. Here is what that means exactly:<\/p>\n If your control requires a UI which is based on a type-converter and\ntherefore, shown in the context of the Property Browser (like Enums or dedicated\nitems to show in a property grid\u2019s property grid cell ComboBox), your UI will\nbe supported by the new designer model out of the box.<\/p>\n<\/li>\n If your control requires a UI, which shows up as part of the control (like\ncustom painted adorners or Action Lists) at design time, then you would need\nto write your control library against the WinForms Designer SDK, but you don\u2019t\nneed to take care about round-tripping data to the Server process. Everything\nfrom the Developer\u2019s perspective seems to actually be done server-side, and\nyou can reuse most of the existing control designer Code.<\/p>\n Note though, that in those cases you need to target the control Designer\nagainst the WinForms Designer SDK<\/em>. That means, you need to reference the\nMicrosoft.WinForms.Designer.SDK NuGet\npackage<\/a> from\nyour control library. In addition, you need to refactor the namespaces from\n If your control designer however needs to provide a custom Type Editor for a\nproperty whose type’s value need a more complex user interaction, then there is\nsome additional effort for the different processes, which you need to take into\naccount.<\/p>\n Note:<\/strong> This blog post provides a couple of samples, which you can use as a\nguidance to either create new .NET based or migrate your existing\n.NET Framework-based control designers to .NET. Section Two<\/em> .NET samples, and the\nWhy<\/a> describes those scenarios in more detail.<\/p>\n While more simple control designer scenarios like type converters, Action Lists\nor CodeDom Serializers don\u2019t need any substantial rewrites, Type\nEditors<\/a>,\nwhich are responsible for a complex dialog-based UI experience, are a different\nbeast altogether. But before we get into that, let’s recap what Type Editors in\nthe context of WinForms Control Designers are and what purpose they serve.<\/p>\n Technically speaking, a Type Editor is a mechanism which provides the front end\nfor a user to set the value for a certain control property via some data entry\ndevice. The simplest one: A string editor for a control’s property of type\n But not all properties are of type Let’s see how such a Type Editor works for a .NET Framework control in the\nIn-Proc-WinForms Designer, and then, why that approach does no longer work in\nthe context of the out-of-process WinForms Designer.<\/p>\n In our Template and Samples GitHub Repo, you find a sample WinForms\napp<\/a>\nfor this scenario. It is a picture browser, which shows the jpeg-Images of a\nfolder in a special way:<\/p>\n In our example app, those are items holding JPeg-image filenames of a folder on\ndisk. On the UI-side you have a user control which represents the template for\neach element of the data source. At runtime, for each element in the data source\none tile based on this user control template gets created. Each item of the data\nsource is then data-bound to the instance of that user control, and the user\ncontrol is responsible for rendering the content. To this end, our\n So, the data source list which holds the pictures in the list is not completely\nhomogenous. Rather, we find two types of elements in it – but we still can use a\ngeneric list, since the types built an inheritance type hierarchy.<\/p>\n DISCLAIMER<\/strong>: The Here is what happens behind the scenes at design-time when the user sets the\nvalues for The UI of the Type Editor is controlled by a ViewModel\n( The Type Editor dialog is shown on the screen by passing it to the\n To make the If you have custom Type Editors, which are displaying dedicated modal dialogs,\nthen there is some rewriting effort involved for round-tripping the required\ndata between the two processes.<\/p>\n<\/li>\n If you have Type Editors which are derived from existing Type Editors (like\n If you however just use<\/em> the editors (which again need to be provided by the\nclient process), a server-only control designer suffices. In that case though,\nyou need to state the types in the required attributes as strings, and cannot\nuse The example that you’ve seen earlier showed the approach of control\ndesigner functionality and Type Editors in .NET Framework. When we either port\nthose designers from .NET Framework to .NET, or develop new control designers\nfor .NET altogether, we’ve already discussed that different controls designers\nmight need different kind of UIs. When you use only stock Type Editors editors,\nor you just need your control designers to provide custom Adorner painting,\nAction Lists or custom CodeDOM serializers, a server-only version for the\nDesigner will do, and which is pretty much the way, you’ve developed in control designers in .NET\nFramework. Only<\/em> if your Control or your Control Library needs custom UI Type\nEditors, then you need a Client\/Server-solution for your Control library.<\/p>\n That is the reason, the sample folder for this blog post contains yet another\nversion of the sample<\/a>:<\/p>\nTextBox<\/code> and its PlaceholderText<\/code> property, Button<\/code> and its Command<\/code>, or the\nlayout of a form with the desired default font \u2013 in order for it to generate the\nWinForms code which sets up the form or UserControl at runtime in\nInitializeComponent<\/code>, the CodeDom Serializer must run in the context of the\nversion of .NET the project is targeting. And we naturally can\u2019t do that, if the\nCodeDom serialization is running in the same .NET Framework process as Visual\nStudio. To stick with the example: In .NET Framework, TextBox<\/code> does not have a\nPlaceHolder<\/code> property (introduced in .NET Core 3.0), and Button<\/code> is missing\nthe Command<\/code> property, which has been introduced in .NET\n7<\/a>.\nThe correct version of those .NET types simply cannot be resolved in the .NET\nFramework process. To solve this, we run the designer out-of-process in a new\n.NET (Core) process called DesignToolsServer<\/em>. The DesignToolsServer process\nruns the same version of .NET and the same bitness (x86, x64 or ARM64) as your\napplication.<\/p>\nObjectProxy<\/code>) for the components and controls on a form which\nare created along with the real components and controls on the form in the\nDesignToolsServer process. For each component or control on the form, an Object\nProxy is created. While the real controls live in the DesignToolsServer process,\nthe Object Proxy instances live in the client \u2013 the Visual Studio process.\nObject Proxies then talk with their actual .NET counter parts across the\nprocesses.<\/p>\nTextBox<\/code> control\nthere is TextBoxDesigner<\/code> class which provides special TextBox design-time\nsupport. For the ListBox<\/code> control, there is the ListBoxDesigner<\/code> class, which\nprovides special design-time support for that<\/em> control, and so on. Design-time\nsupport often means that there is UI-related functionality which the Designer\nneeds to provide. For example, when the user picks an item from a list for a\ncontrol’s property in the Property Browser, the control’s designer has to\nprovide that list as a Type Converter<\/em>. For more sophisticated scenarios,\ncontrol designers can also provide custom painting at design time. The handling\nof Action Lists, which provide a quick access to special design-time\nfunctionalities or properties (the feature image of this blog post is such an\nAction List) is one additional Designer feature. Ultimately, they can also\nprovide real complex UIs, which are modal dialogs, shown in the context of\nVisual Studio.<\/p>\nMigrating existing Control Designers with almost no effort<\/h3>\n
\n
System.ComponentModel.Design<\/code> to Microsoft.DotNet.DesignTools.Designers<\/code>,\nwhere it applies. Some classes are more finely granulated when it comes to\nnamespace definitions, so for example the DesignerActionList<\/code> base class,\nwhich is originally located in System.ComponentModel.Design<\/code> in the runtime,\nyou’d find in Microsoft.DotNet.DesignTools.Designers.Actions<\/code>. It’s easiest\nto let Visual Studio do the namespace lookup in those refactoring cases:<\/p>\n<\/li>\n<\/ul>\n![\"Screenshot](\"https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2022\/12\/NamespaceLookupInVisualStudio.png\")
<\/p>\nRecap: Type Editors for special control properties<\/h2>\n
string<\/code>, whose value is entered via the keyboard in the Property Browser.<\/p>\n![\"Entering](\"https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2022\/12\/EnteringValueInPropertyBrowser.png\")
<\/p>\nstring<\/code>. So, for most of the cases, a type\nconverter<\/em><\/a> will\nextend the functionality of the build-in string editor by providing a mechanism\nto convert the characters you types to the actual type’s value. For example, the\ncharacters ‘#202020’ are assumed to be hexadecimal representations for the\nRGB-color values ‘Red: 32, Green: 32, Blue: 32’ and thus converted to a color of\nvery dark gray for a background. Unfortunately, not all properties have a\nmeaningful way to convert to its native value based on a string. Or, it is way\nmore useful to interact on a visual representation of a type’s value. For a\nproperty which represents a picture for example, the respective Type Editor must\nprovide the UI to select a picture from disk, serialize the picture, store it as\na resource or file in the project, and generate the required code to assign that\npicture at runtime.<\/p>\nThe Demo scenario \u2013 the WinForms TileRepeater Control<\/h3>\n
![\"Animated](\"https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2022\/12\/PictureBrowser_FrameworkSample.gif\")
<\/p>\nTileRepeater<\/code> control has an ItemTemplate<\/code> property. This property determines,\nwhich type of an element of the data source results in what user control\ntemplate type in the UI. And to make this approach even more flexible,\nTileRepeater also has a SeparatorTemplate<\/code> property: It determines another type\nfor the items, which would serve as a visible separator at runtime.<\/p>\n![\"Data](\"https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2022\/12\/DataSourceElementList.png\")
<\/p>\nTileRepeater<\/code> control is a demo for the specific .NET\nWinForms Designer scenario – it lacks a virtual rendering mode. It works fine\nfor up to 100 elements, but more than that drains the available resources too\nmuch, and a virtual mode would be necessary to show a large number of items\nreliably.<\/p>\nHow a Type Editor works in the In-Process WinForms Designer<\/h3>\n
ItemTemplate<\/code> or SeparatorTemplate<\/code>. When they determine which of\nthe element types in the data source list should lead to what user control type\n(derived from TileRepeaterTemplate<\/code>) for the actual rendering container at\nruntime, this happens behind the scenes.<\/p>\n\n
TemplateAssignment<\/code> type of the\nItemTemplate<\/code> property of the TileRepeater control. To that end, they either\nuse a command from the Action List or the Property Browser of Visual Studio\n(by clicking on the …<\/em> button in the grid for that property).<\/li>\n<\/ol>\n![\"User](\"https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2022\/12\/InitiateEditTemplateItems.png\")
<\/p>\n\n
TemplateAssignment<\/code> type is annotated with the EditorAttribute<\/code>,\nthe Type Editor TemplateAssignmentEditor<\/code> is found and instantiated. Since\nits GetEditStyle()<\/code> method returns UITypeEditorEditStyle.Modal<\/code>, the\nWinForms Designer knows that this Type Editor as a modal WinForms Dialog. The\nDesigner calls the EditValue<\/code> method and passes the type descriptor context,\nthe service provider and the actual value to edit. The type descriptor context\nprovides information about the context in which the Type Editor has been\ncalled, e.g. if that has been the Property Browser or an Action List. The\nService Provider allows the Editor to acquire required Visual Studio services – for example the WindowsFormsEditorService<\/code> to show the actual Dialog in the\ncontext of Visual Studio. <\/li>\n<\/ol>\n![\"Class](\"https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2022\/12\/ClassEditorAnnotation.png\")
<\/p>\n\n
TemplateAssignmentViewModel<\/code>). That means that code for displaying the UI\nelements and the code for figuring out what<\/em> to display are separated from\neach other. This is the recommended architectural practice. The Dialog UI\n(TemplateAssignmentDialog<\/code>) is then instantiated and passed the ViewModel.<\/p>\n<\/li>\nShowDialog<\/code> method of Visual Studio’s editor service. In that dialog, the\nuser can now pick the two types which needs to be assigned to each other:<\/p>\n<\/li>\n<\/ol>\n![\"The](\"https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2022\/12\/TileRepeaterTypeEditor.png\")
<\/p>\n\n
OKClick<\/code> method in the ViewModel to actually create the new value for the\nproperty in its TemplateAssignment<\/code> property. The code flow returns to the\nEditValue<\/code> method, where the new property value is taken from that\nTemplateAssignment<\/code> property and returned to the Designer, which then\neventually assigned the new value to the TileRepeater<\/code> control.<\/li>\n<\/ol>\nThe challenge of Type Editors in the Out-Of-Process Designer<\/h2>\n
TileRepeater<\/code> control work at design time in the new out-of-process\nDesigner, we need to add the support for the process separation. When we want to\nshow the Type Editor as a modal Dialog, which allows the user to pick the types\nfor the data template assignment, we have to deal with the different processes:\nThe Visual Studio Process runs in .NET Framework. But the actual control, for\nwhich we are showing the custom UI, runs in the dedicated .NET server process.\nIf your WinForms project using the control, is targeting .NET Core 6.0, then\nthat process runs .NET Core 6.0. If your target is 7.0, the Server Process runs\nagainst .NET 7.0, and so on. That is necessary, because you need and use types\nonly the specific version of .NET knows about. The Visual Studio and .NET\nFramework<\/em>-based client process is simply not able to discover or handle those\n.NET types. From that fact arises the real challenge: Since the control\ndesigner\u2019s dialogs are running in the context of .NET Framework, it cannot\nsimply search for the types (in our example neither both the items to bind and\nthe resulting UserControl types) it is supposed to offer the user in that\ndialog. Rather, the .NET Framework part of the Type Editor needs to ask the .NET\nProcess for those types and then use transport classes to get those types\ncross-process back to the .NET Framework based Visual Studio process. It can now\nprocess the user\u2019s input and send the results back to the server process. And\nyes, that is a necessary breaking change from the previous .NET Framework-only\ncontrol designers, and it involves some refactoring of the design time code. But\nthis refactoring is needed only<\/em> if there is<\/em> an actual UI which needs to be\nshown on top of the UI that is presented in the context of your actual control,\nas we already discussed in the section [Control Designers with almost no\nmigration effort] (#control-designers-with-almost-no-migration-effort).<\/p>\n\n
ColorEditor<\/code> or FileNameEditor<\/code>) for editing certain types of values for\nexisting controls in .NET Framework, then you also<\/em> need the client\/server\napproach. That said, your control designer solution most probably doesn’t need\nto have additional communication code to exchange data between the server and\nthe client process in those cases. As long as you do not change the type the\noriginal editor is handling, the Designer handles the necessary communication\nbehind the covers. But: That communication is still required to happen, and the\nmodified (inherited) editor types still need to be run in the context of Visual\nStudio – which at this time is either the 32-Bit .NET Framework process (VS 2019) or\nthe 64-bit .NET Framework process (VS 2022).<\/p>\n<\/li>\ntypeof<\/code> (in C#) or GetType<\/code> (in VB). It would look something like this:<\/p>\n<\/li>\n<\/ul>\n[Editor(\"System.Windows.Forms.Design.FileNameEditor, System.Design, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a\",\n \"System.Drawing.Design.UITypeEditor, System.Drawing, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a\")]\npublic string? Filename { get; set; }<\/code><\/pre>\nTwo<\/em> .NET samples, and the Why<\/h2>\n
![\"Overview](\"https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2022\/12\/TemplateSolutionItems.png\")
<\/p>\n![\"Custom](\"https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2022\/12\/CustomControlWithOpenedActionList.png\")
<\/p>\n![\"The](\"https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2022\/12\/CreateNewTypeEditorSolution.png\")
<\/p>\n