I thought I would publish the slides from the presentation I put together for last year's Developer Day, on producing releasable controls. It covered attributing and enhancing custom and user controls in order to get them to a level good enough for public or commercial release.
The slide deck is here, but I thought I might also elaborate a bit with a write-up of the hand-written notes I had for presenting.
The idea was to show how to bridge the gap between functional controls for WinForms, Web, WPF etc., that might be good enough for internal project use, and releasable ones that better support deployment and use in the Visual Studio toolbox with all the design-time support that makes a control easier and nicer to use. Simple attributes, extensions and practices that enhance a control to make it look and behave better when used by other developers.
The 20 tips are:
1. The Description Attribute, 2. The Category Attribute, 3. The Browsable Attribute - Use these simple attributes to decorate a control's properties to affect how (and whether) they appear in the property browser of Visual Studio.
4. The ToolboxBitmap Attribute - Add a 16x16 bitmap to your project and reference it using this attribute to avoid the default cog toolbox image.
5. The DefaultValue Attribute, 6. The ResetXxxx Method, 7. The ShouldSerializeXxxx Method - This is how you enable the Reset option in the context menu for a property in the property browser and govern how that property's state is serialized into the designer code for a control. If you want to provide the ability to reset a property, then you need a default to reset it to and if you have a default property, what is the point in serializing the value of that property for a control instance in a form or page, if the property's value is the same as the default. The DefaultValue attribute allows you to set a default (which must be a literal value) and the two methods allow you to get around the need for the default to be a literal value which is often the case where a property's type is an enumeration or a stored value (often resource strings localisation resources). Having implemented these methods, the designer will magically call them when providing the reset functionality for the property browser and when serializing the state of the control.
8. Extend the DefaultValue Attribute - This is a refinement of the above approach to getting around the literal restriction on using DefaultValue. Here you roll your own version of the attribute that can take arguments to allow resource retrieval for the default value rather than a literal.
9. The DefaultProperty Attribute, 10. The DefaultEvent Attribute - Determine which property is scrolled to and highlighted by default in the property browser and which event stub is generated when the control is double-clicked in the designer.
11. The ToolboxItemFilter Attribute - Used to restrict visibility of a control to particular designers in Visual Studio - if you use the Require value of the ToolboxItemFilterType enumeration then the control will only appear in the toolbox when that designer is open.
12. The Bindable Attribute, 13. Implement INotifyPropertyChanged - These help the IDE with hints for the property browser when displaying bindable properties - marking a property as bindable means that you have undertaken to have implemented property change notification for it and ensures that it is included in the list of default binding properties at the top of the property browser.
14. The setter value comparison pattern - This simple pattern helps avoid unnecessarily exercising setter code and erroneously firing property changed events, by checking that the new value is actually different to the old value.
15. The RefreshProperties Attribute - If a change in one of your properties has an effect on the display of others in the property browser or the control's appearance on the design surface then you can use this attribute to signal to the IDE that the property browser should re-query all the property values of the control and/or repaint the control in the designer.
16. Use Sandcastle - Microsoft now makes available the toolset it uses for generating the MSDN reference and help files from XML documentation comments in code. You can use Sandcastle to produce professional docs from your control's XML comments (which of course you should be providing for the sake of intellisense support and the IDE Object Browser).
17. Setup/Toolbox registration - This has perennially been an area of pain and confusion in the past and continues to be to this day. The links here point to sources of help, but the whole subject is inevitably bound up in permissions and issues with target machines and their configuration.
18. TypeConverter - Where your properties are not simple CLR types and the IDE does not know how to present and manage their values in the property browser you can supply one of the standard set of TypeConverters or indeed your own custom TypeConverter to help. In this example the property is a class instance with its own properties and using the ExpandableObjectConverter allows the IDE to know that it can 'drill-down' into the property to expose the property's own properties as an expanded list. TypeConverters specify to the IDE how to convert from a type to a string and back again so that the IDE knows how to serialise and present property values in the property browser window.
19. TypeEditor - Where a property is not easily entered as a string from the property browser a TypeEditor can be used to provide a UI for setting the property. The IDE already has TypeEditors for types such as Color where it will drop down a selector dialog with tabs for system, web and custom colour selection. You can write your own TypeEditors for custom display and editing of your properties and use the TypeEditor attribute to indicate to the IDE that the property has a special editor to display for setting its value.
20. Smart Tags - Common tasks for a control sited on the designer surface can be accessed via a little right-arrow icon if you supply a list of tasks using the smart tags support available in the Visual Studio IDE. The two books I name-check there Pro .NET 2.0 Windows Forms and Custom Controls by Matthew MacDonald and Windows Forms 2.0 Programming by Chris Sells and Michael Weinhardt contain good walkthroughs of how to set these up and provide the UI for them.
No comments:
Post a Comment