Grouping with ProvideProfileAttribute

[reduckted]

I have an extension with a lot of options. I've created a single Options class like so:

public class Options : BaseOptionModel<Options> {
    // Lots of options...
}

Because there are a lot of options that fall into different categories, I've defined multiple Tools Options pages where each page is for a different category of options.

[ProvideOptionPage(typeof(AzureDevOpsServerOptionsPage), ...)]
[ProvideOptionPage(typeof(BitbucketServerOptionsPage), ...)]
[ProvideOptionPage(typeof(GeneralOptionsPage), ...)]
[ProvideOptionPage(typeof(GitHubEnterpriseOptionsPage), ...)]
[ProvideOptionPage(typeof(GitHubOptionsPage), ...)]
[ProvideOptionPage(typeof(GitilesOptionsPage), ...)]
[ProvideOptionPage(typeof(GitLabEnterpriseOptionsPage), ...)]

This works great, and all of the pages are grouped under a single node.

Now I'm trying to work out how I should use ProvideProfileAttribute. If I define a ProvideProfileAttribute for each options page, like this:

[ProvideProfile(typeof(AzureDevOpsServerOptionsPage), ...)]
[ProvideProfile(typeof(BitbucketServerOptionsPage), ...)]
[ProvideProfile(typeof(GeneralOptionsPage), ...)]
[ProvideProfile(typeof(GitHubEnterpriseOptionsPage), ...)]
[ProvideProfile(typeof(GitHubOptionsPage), ...)]
[ProvideProfile(typeof(GitilesOptionsPage), ...)]
[ProvideProfile(typeof(GitLabEnterpriseOptionsPage), ...)]

Then I end up with this mess in the Export Settings Wizard:

What I really want is to have all of the categories grouped together, just like they are in the Tools Options dialog. I've tried all sorts of combinations of categoryName, objectName, AlternateParent and GroupName, and nothing seems to make a difference.

So there's a few questions that I have:

1. First, is using a single Options object with multiple Tools Options pages the correct approach, or is it expected that each Tools Options page has its own Options object?
2. How do I get all of the profiles to be grouped under a parent node?
3. Should I even be using multiple profiles, or should I only provide a single profile?

[madskristensen]

Really good questions. Perhaps @jekelly knows the answer?

[JoshuaBStevens]

I don't see anything obvious. Let me debug it and get back to you.

[JoshuaBStevens]

You need to put [ComVisible(true)] on your options page class. Sorry about the obscure requirement.

[reduckted]

Thanks @JoshuaBStevens. 😁

I got it working in that test extension I linked above after adding the ComVisible attribute, but I'm still having trouble with my real implementation. When exporting settings, my breakpoint in SaveSettingsToXml is hit, but the export produces this mysterious error:

Your settings were exported, but there were some errors.

Error 1: Failed to export settings for 'General' [code 6882]

No exceptions are thrown (at least none that show up in Visual Studio's output window), and nothing appears in the ActivityLog.xml file.
If I restart Visual Studio and export again, none of the breakpoints are hit. It's only after I change the name of the category used in the ProvideOptionPage that the breakpoints are hit again, but exporting just produces the same outcome as before. 😕

Any idea what that error code might be referring to?

[reduckted]

And, of course, after posting that, I thought of one last thing to try, which seems to have worked! 🤦‍♂️ I had an inheritance hierarchy like this:

GeneralOptionsPage
    OptionsPageBase
        Microsoft.VisualStudio.Shell.UIElementDialogPage
            Microsoft.VisualStudio.Shell.DialogPage

I tried removing my base class and just inheriting directly from UIElementDialogPage like this:

GeneralOptionsPage
    Microsoft.VisualStudio.Shell.UIElementDialogPage
        Microsoft.VisualStudio.Shell.DialogPage

And it worked! I'm not sure exactly what OptionsPageBase had in it that was causing the problems, but I'll investigate a bit further and report back with what I find.

[reduckted]

I'm not sure exactly what OptionsPageBase had in it that was causing the problems, but I'll investigate a bit further and report back with what I find.

The problem was my base class also needed the [ComVisible(true)] attribute on it.

[madskristensen]

What!! I was today years old when I learned about SupportsProfiles = true. Does that mean we don't need to use ProvideProfileAttribute at all, @JoshuaBStevens ?

[JoshuaBStevens]

SupportsProfiles = true will import and export by getting and setting the public properties of your options page. If you want your import/export schema to be different, you might find it useful to provide your own IProfileManager implementation, and I think that's when you'd use ProvideProfileAttribute. But that's quite rare.

[reduckted]

Thanks to @JoshuaBStevens, I was able to get this working how I wanted. ❤️

As he pointed out, there's a SupportsProfiles property on the ProvideOptionPage attribute that will give me the behavior that I wanted.

By setting the SupportsProfiles property to true, I was able to completely do away with the BaseOptionModel base class and just define the properties on each DialogPage. Visual Studio will load and save those properties automatically.

I'm still a bit confused about what Visual Studio actually does when loading and saving those properties, because it seems to be able to export settings without actually creating an instance of the DialogPage (no breakpoints were hit anywhere in the class), unless an instance of the DialogPage had already been created by viewing the Tools -> Options page. I think Visual Studio was just reading whatever data it had previously saved in the registry. I can see why it would do that, but boy was it frustrating when you're trying to debug the loading and saving!

Another thing that I couldn't get working was the loading and saving of objects and collections. In the end I just gave up and defined a string property that serialized the collection to/from JSON and had that string property saved to the registry and to the exported XML file. 🤷‍♂️

If anyone is interested, you can see my implementation here: https://github.com/reduckted/GitWebLinks/tree/3cb46cb99f2657d1e8e70c32de571df7a29e656b/visual-studio/source/GitWebLinks/Options

I think there's a few changes that we can make in the toolkit to make things a little bit easier. The one major thing that caught me out is needing the [ComVisible(true)] attribute on all levels of the hierarchy of your dialog page implementation, not just on the final class. I think an analyzer would be really useful to point out when you make this mistake. I'll make a pull request in the next day or two (hopefully 🤞) with some changes.

[madskristensen]

That's awesome!