Home » Blog

Archive for November, 2008

WPF Property Grid 2.0 is here

We’re pleased to announce version 2.0 of the WPF Property Grid. Since we launched version 1.0 in January, we’ve been continuing to enhance the product, and version 2.0 wraps up all those new features and adds a couple more. Here are some highlights.

Exciting new styles

Version 2.0 includes three new visual styles for the property grid, on top of its default Windows Forms-like appearance: Alloy, a dark brushed-metal style; Whalesong, a relaxed light-blue theme inspired by Office 2007; and Radium, a bright, colourful green style with animated highlights. You can use these styles directly, or you can use them as a starting point for your own customisations — the full source for all three styles is included. The templating samples from version 1.0 are still available but the new styles are much more comprehensive.

You can play with the new styles online here. (See below for .NET Framework and browser requirements.)

Multiple selected objects support

One frequently requested feature has been support for a SelectedObjects property which would allow users to select multiple objects and edit their properties all in one go. Version 2.0 of the property grid includes exactly that feature.

Sorting and grouping in XAML

The property grid has always supported sorting and grouping, but it wasn’t always as obvious as it could be, and you had to go into code to set it up. We’ve fixed that, providing properties on the grid that you can set through XAML for common sorting and grouping scenarios.

Partial trust

As WPF arrives on more and more machines, and with the recent introduction of Firefox support for XBAP, it’s becoming increasingly practical to deliver WPF applications over the Web. We’ve eliminated some of the code access security requirements of version 1.0, so that you can now use the grid in partial trust scenarios such as ClickOnce and XAML browser applications.

Plus there are a ton of smaller features and fixes — check the release notes in the documentation for details. We’ve also added a number of “how to” articles to the help file based on some frequent support questions.

Try it out

You can get a 14-day trial of WPF Property Grid 2.0 from our downloads area — take it for a spin today!

You can also try out the interactive demo. (You will need to have .NET Framework 3.0 SP1 or above, and be using an XBAP-friendly browser — Internet Explorer for .NET 3.0 SP1, Internet Explorer or Firefox for .NET 3.5 or above.)

For existing users

If you already have a licence for WPF Property Grid 1.0, version 2.0 is a free upgrade, which you can get from the store. A couple of things to be aware of:

• Version 2.0 installs side by side with version 1.0, rather than over the top. If you want to upgrade an existing project to use 2.0 (and you have not copied the DLL to a custom location), you will need to update your DLL reference path to “WPF Property Grid 2.0″. You might also need to update licenses.licx to reflect the new version number, though in practice we’ve found that this seems to be unnecessary.
• Although version 2.0 is highly compatible with version 1.0, you might need to make small changes to existing code if you are customising the built-in editors or retemplating the grid. These changes will be very minor: we will post details shortly, or in the meantime we will be happy to advise you on the forums.

Documentation, the Mindscape way

A question has been asked in our forums about how we create, maintain and publish the documentation for our products and rather than just reply in the forum I thought it maybe of interest to other software developers out there.

First off, if you haven’t read our help files for fear that they’re just simple API documentation you’ll be pleasantly surprised to see that we provide both API docs and a more human-readable discussion of various key features. LightSpeed’s documentation even includes a getting-started walk through to help guide new users to creating their domain models faster.

API documentation

Our API documentation is extracted from our XML doc comments in the source code. We turn on XML documentation generation which creates and XML file containing all the documentation for every class, method and property. This means if you’re an enterprise customer who receives the source code to our products that you’ll see these comments inline. We also turn on the static analysis and ensure that Visual Studio will provide a warning if there is a missing doc comment as it’s certainly very easy to forget to create one. To keep us honest (and to laugh at those who forget) we also turn on the compiler option to show warnings as errors so that our continuous integration environment will show a broken build if a doc comment is missing.

That brings us to having the raw source for our standard MSDN-styled API documentation.

Hand written documentation

We have those nice hand written documentation guides around key features. For those of you who are unaware of how windows help files are constructed, they’re effectively HTML pages grouped together with some table of contents meaning that these pages in our documentation are hand written html pages.

Because writing heaps of html by hand is somewhat tedious we use a Ruby utility called WebGen which can generate static html from pre-defined templates. We write our html documents using a textile like style markup (I say “like” because it includes some WebGen specific mark-up as well).

Code Samples

Code samples are always nice in documentation but the pain of maintaining documentation is that as your code changes these samples start to rot and don’t reflect how you would actually use the API. To overcome this we have a plug-in for WebGen which will extract code from our actual product unit tests. To paint a picture, here’s what we would have in our WebGen template:

{sccode: {region: Representing a one-to-many association, file: Domain/Member.cs}}

What this does is open up the file, Member.cs in the Domain directory and find the code wrapped inside the region tag with the region name of “Representing a one-to-many association”. It then injects it at that point in the template and nicely wraps it in syntax-highlighted goodness.

The nice thing about this is that we know that the code samples in our documentation at the very least compiles but also, because it comes from our tests, we know that it performs as expected. It also means that if we change our API and a test breaks that we’ll know and can update the test and then the documentation change will be reflected in the next nightly build.

Putting it all together

Once we’ve generated our xml API documentation and generated our static html pages for our hand written documentation with WebGen, it’s time to compile everything together into a single CHM file. For this we use the excellent Sandcastle Help File Builder (SHFB) and Sandcastle. Sandcastle is a collection of utilities and templates, created by Microsoft, for generating CHM files (as well as other types of output if you so desire). SHFB is a very nice visual application for automating Sandcastle and I highly recommend to anyone undertaking documentation generation.

Once we’ve configured things such as the table of contents, included our custom html pages into the structure, give standard documentation names and links to our help file inside SHFB we can save the SHFB project file for later use. This is handy because the SHFB comes with a command line version as well which integrates directly into our continuous integration environment so that every nightly build that we make available comes with a freshly minted version of our documentation.

Could we do more?

Beyond what I’ve covered here for our CHM help file that ships with LightSpeed, the WPF Property Grid and WPF Elements we also provide an HTML version online however I always feel that companies can do better with their documentation. We have received comments in the past about improvements in certain areas and have always acted on that feedback. Is there something more we could do in terms of documentation that would make you happy? If so – drop a comment here or, even if you don’t have feedback but a question about documentation, feel free to ask away.

VS File Explorer Update

A quick message to those using the free Mindscape VS File Explorer, we have just released an updated version which you can download here: VSFileExplorer download page

There are no new features in this release however it does resolve an issue with the way that one of the components we used is licensed (it was not correctly being registered so you may have received the occasional warning about a 30 day trial).

If you have features or feedback that you would like to make about the VSFileExplorer please post in our VSFileExplorer forum: VSFileExplorer Forum

Happy coding!

Microsoft BizSpark

Today Microsoft announced the release of a new program called BizSpark to help provide support for software startups who are developing a software based product or service on the Microsoft platform.

They will help you by providing some very useful resources to set you on the path towards success, namely:

Software:

• All the software included in the Microsoft® Visual Studio® Team System Team Suite (VSTS) with MSDN® Premium subscription
• Expression® Studio Version 2
• VSTS Team Foundation Server (standard edition)
• Production use rights to host a “software as a service” solution (developed during participation in the BizSpark Program, on any platform) over the Internet, with regard to products including:
  • Microsoft Windows Server (all versions up to and including Enterprise)
  • Microsoft SQL Server (all versions)
  • Microsoft Office SharePoint Portal Server
  • Microsoft System Center
  • Microsoft BizTalk Server
  • Microsoft Dynamics CRM (coming soon)

Support:

Giving you a connection to local resources and technology partners (known as Network Partners), incubators, investors, advisors, government agencies and hosters. In New Zealand, NZ Angels, Incubators New Zealand and Software New Zealand are helping to administer the program

Visibility:

Achieve global visibility to an audience of potential investors, clients and partners.

This is an AMAZING offer – and Mindscape is proud to be the first network partner to work with Microsoft on this program for the New Zealand region. If you are a start-up and you think you qualify (You need to be a privately held, local company, engaged in the development of a software based product or service and be less than 3 years old and be turning over less than $1M USD) then connect with us through the Microsoft Startup Zone – we would love to hear from you and help get you started with this exciting new program!

For more information, read all of the details on the BizSpark web site.

Inheritance in LightSpeed

One of the big mismatches between the world of objects and the world of relational databases is inheritance. Object-oriented programming likes to pull common state and behaviour up into base classes so that programmers can work polymorphically with the objects and so that common implementation can be reused. The relational world doesn’t really have an equivalent — or, alternatively, it has several near-equivalents, all of which model the same general idea in different ways.

Martin Fowler’s Patterns of Enterprise Application Architecture describes these approaches in the chapter “Object-Relational Structural Patterns.” The three entries to look at are Single Table Inheritance, Class Table Inheritance and Concrete Table Inheritance.

Concrete table inheritance is, from a LightSpeed point of view, the simplest of these approaches. In concrete table inheritance, there’s a table for every (concrete) class (entity), and that table contains all the state for that entity. Of course, that’s exactly the way LightSpeed works when there’s no inheritance involved; inheritance just means that the table for the derived entity has to contain columns for the fields of the base entity as well.

You should use concrete table inheritance when:

• You have objects that have some fields in common, but are more different than similar
• You don’t need to load objects polymorphically in a single query
• Your base class doesn’t actually have state at all — it just adds common business logic or helper methods

To use concrete table inheritance:

• In hand-coded entities, you don’t need to do anything; LightSpeed’s default behaviour will work with concrete table inheritance database schemas
• In the designer, select the inheritance arrow and set the Inheritance Type to ConcreteTableInheritance

Single table inheritance is LightSpeed’s way of supporting load-time polymorphism — that is, being able to materialise different kinds of object via a base class query. It means, for example, that you can query for Contribution objects, and get back ArticleContribution, VideoContribution and PhotoContribution objects as part of the result set. (Whereas with concrete table inheritance, you’d have to query for ArticleContribution, VideoContribution and PhotoContribution objects separately, though you could treat them polymorphically within your code once LightSpeed had loaded them for you.) In single table inheritance, there is a single table, named for the base class of the hierarchy, and it contains columns not only for the base class fields, but for all the types in the hierarchy. Thus the Contribution table might contain a WordCount column for articles, a Resolution column for photos and a Duration column for videos — even though these columns make no sense for the “wrong” kind of object. The table also contains a column which indicates the kind of entity a given row represents — LightSpeed calls this the discriminator.

You should use single table inheritance when:

• The objects are mainly the same, but with just a few additional fields here and there
• You need to load objects polymorphically in a single query

One thing to remember when we talk about loading objects polymorphically is to consider associations. Suppose you have a Member entity, and a Member is associated with their Contributions. Then Member.Contributions is effectively a query for Contribution objects; if Contribution is a base class, this will work correctly only in single table inheritance. If you want to represent Contribution entities using concrete table inheritance, then Member will need separate ArticleContributions, VideoContributions and PhotoContributions associations. This is rarely what you want, so this will often be a driver towards single table inheritance.

To use single table inheritance:

• In hand-coded entities, specify the DiscriminatorAttribute on the derived class
• In the designer, select the inheritance arrow and set the Inheritance Type to SingleTableInheritance (this is the default). You will also need to supply discriminator information.

Class table inheritance, like concrete table inheritance, has one table per class, but the table contains only the new fields introduced by that class. Fetching the entire entity requires joining data from across all the tables in the class’ inheritance hierarchy. LightSpeed currently doesn’t support this database pattern.

The design considerations and consequences discussed above are purely from a LightSpeed point of view. Fowler’s book provides much more information and discusses the wider design trade-offs between the possible approaches, and is well worth a read if your domain model involves an inheritance hierarchy and you’re trying to decide how to model it in your database.