How to build a guidance only toolkit?

Coordinator
Aug 5, 2014 at 9:51 PM
@johnmcbride asked "how would you only build guidance using the GE?"

Every toolkit comes complete with its only guidance 'volume'. That is, by default, an offline set of guidance topics for the toolkit which are displayed in Visual Studio.
The guidance can then be displayed while using the toolkit, or, as is the case with a hands on labs style of toolkit, can guide the user into using the toolkit while they develop their solution in Visual Studio. All toolkits come with guidance, but building the guidance is not a pre-requisite for building toolkit.

The more mature toolkits provide guidance to help users of the toolkit understand the tricks and habits of toolkits.

As it happens NuPattern is a toolkit itself and has an extensive volume of guidance to help toolkit builders build their own toolkits. You can view that guidance in the Guidance Explorer window, by clicking on the help link (toolbar of Solution Builder)

NuPattern makes it really easy to create guidance and display it along side your toolkit. It does all the heavy lifting of creating a set of linked topics from a single Word document.

It s not the only way to create guidance but the one we started with in toolkits. You can create your own manually using online wikis as well - but there is limited tooling for that right now.

The following instructions can be found in Visual Studio while developing your toolkit, in your toolkit solution. Simply open Solution Builder window and right-click on the top level toolkit node (representing your toolkit), and click 'Show Guidance'. The Guidance Explorer window pops up with all the content to help you build your toolkit. Look at the topics for building guidance. Specifically the ones under: Pattern Toolkit Guidance\How To: Guides\Authoring\Guidance



To build the default volume of guidance, all you have to do is edit the word document (YourToolkitProject\Assets\Guidance\ToolkitGuidance.doc) with Microsoft Word, and put your topics in there. (follow the instructions in the document, and use the styles you see for your topics). Then:
  • close the word document
  • in Solution Builder (for your toolkit project) right click on the 'Guidance' node and select 'Build Guidance'
NuPattern will automate the creation of the guidance topics and dump them in your project (at
YourToolkitProject\GeneratedCode\Guidance\Content). It will also generate a couple classes that become your TOC in Visual Studio.

Now to configure the guidance to show in your toolkit:
  • in 'Solution Builder', select the 'Toolkit Info' node of your toolkit node, and copy the value of the 'Identifier' property.
  • Now open your 'PatternModel.patterndefinition' file, on the root node, expand the 'Assciated Guidance' property, and paste into the 'Guidance Id' property. You can also set the 'Share Instance' to "true".
  • Now compile your toolkit
When someone is using your toolkit, they can now right-click on the root element (in their solution builder) and click the 'Show Guidance' menu to see the guidance you provided in your toolkit.
Aug 7, 2014 at 7:24 PM
Thanks Jezzsa, I guess my real question is, is there anyway to only build guidance without building a toolkit? I already have an existing vsix/multiple templates/IDE extension elements that i have built and would like to use the guidance and GE options (in several templates) of nupattern without having to rebuild my whole extension into the nupatttern toolkits. Any suggestions on how to accomplish this?

Thanks (@johnmcbride)
Coordinator
Aug 7, 2014 at 9:43 PM
Hey Jon, ah! got you now, I think I know what you are asking us now.

The technical answer is a resounding YES you can build your own guidance extension and wire it up to the Solution Builder AND Guidance Explorer, without building a toolkit for it.

We don't have any tooling yet that does that for you outside of the tooling we have in a toolkit, but building your own is feasible and integrating into your own VSIX should be straightforward if you already have a VSIX of your own.

So where to start? (OK, let me guide you here, but I have not tried this out in a side project yet)
  1. Notice that when you build the guidance document of a toolkit, it generates for you a couple of C# classes in a file 'YourToolkitProject\GeneratedCode\Guidance\GuidanceWorkflow.cs'. One class is called ProcessWorkflow, and the other is GuidanceExtension (names are irrelevant). Classes like these are all you need to add your own guidance in the GE window from your own VSIX.
  2. Simply create classes like these in your VSIX project and compile them. The ProcessWorkflow class provides the TOC and structure to your guidance. Its actually a comprehensive structure of workflow elements, each with a link to a topic or page. Yours can be local files or links to online guidance - your choice. The documentation that exists for these workflow classes can be found searching for 'Feature Builder Power Tool' or 'Feature Extensions' - this is a obsolete project now, but you can find some info on it around the internet. Like I say, NuPattern does not yet support creating guidance workflows outside of a pattern toolkit, so we don't have much documentation on those classes yet. The workflow is pretty straightfoward though, just follow the patterns a toolkit generates for you.
  3. The GuidanceExtension class is the object that actually gets instantiated by the IGuidanceManager service. The one generated by a NuPattern toolkit derives from BlackboardGuidanceExtension which is a specific kind of guidance extension. There are a couple others, the BlackboardGuidanceExtension provides you a property bag to use to hold state about your workflow which can be used by automation you hang off the workflow, such as commands and launchpoints which you can invoke straight from the page of your guidance! Its a pretty cool technology, but there is little documentation for it. (There's another story - ask me to tell it one day!)
    Anyhow, just go with the BlackboadGuidanceExtension as your base class for now.
  4. Once you have these classes compiled into your VSIX, and your VSIX is loaded at runtime into VS, you can get your guidance to display in the Guidance Explorer window by simply using the IGuidanceManager service. Get a instance of that service (usually calling something like GetService(typeof(IGuidanceManager)) or [Import] on a public property of this type somewhere in your VSIX code (just like we do in NuPattern toolkit automation classes - like commands). Then call IGuidanceManager.Instantiate() and pass the identifier of the [GuidanceExtension] attribute you have on your GuidanceExtension class.
  5. AFAIKR registration of your guidance extension should occur automatically simply by installing your VSIX. I recall that the GuidanceManager service scans all installed VSIXes for any classes with a [GuidanceExtension] attribute, and registers them. So you should find that your guidance extension is already registered in the IGuidanceManager.InstalledGuidanceExtensions collection. And if it is, then you can call Instantiate() anytime to have it displayed in the GE window. If there are several guidance extensions found installed in VS, you can switch between them using the IGuidanceManager.ActivateGuidanceExtension() method.
Does that explain it? Its a pretty cool and easy to use technology. Building guidance extensions themselves is fairly straightforward, building the workflows is more involved, and automating them is a little more challenging, but you don't need this to start with.

The whole guidance extension thing used to be a separate project and deliverable (its own packaging) called 'Feature Builder' but it canned by the Visual Studio team, which is why we absorbed it, primarily because NuPattern was reliant on it. There's a whole history about how they evolved together if you are interested: https://nupattern.codeplex.com/wikipage?title=Project%20History&referringTitle=Documentation

let me know how you go. If you publish your toolkit/guidance extension let us know we will publish a reference to it for others to see.
Aug 14, 2014 at 5:17 PM
Ok, I think i understand it. I do have a few more questions though.
I'm looking at the source because what i am thinking is, to extract the guidance document parsing code and processworkflow/guidanceextension code generation and wrap that up in its own (possible extension for others to use) to basically just build guidance (using the existing word document format and guidance explorer). Then to generate the code for inclusion into other VSIX wanting to use GE.

Question is, i'm having trouble finding the parsing code with in the repo. Can you point me to it. Would be interested to making this piece public for other to buil on if they just want to exercise the GE portion of nupattern.
Aug 14, 2014 at 8:58 PM
Jezza, What's your thought on extracting the Guidance explorer documentation parsing and cod generation pieces out into something like nuget packages where we could use them to build guidance into "any" project/item template or extension without the dependency of the nupattern toolkit?

This way the nupattern project could use them as packages as well as other extension could use the documentation feature, which is an awesome feature that could be used in general samples, howto tutorials.
Coordinator
Aug 14, 2014 at 9:18 PM
Hey John,

All good ideas, happy to support what the community feel is valuable. Need to think about how we construct those NuGets to make sense for authoring guidance, but in principle the objective is sound.

The part of the code that generates the guidance classes (mentioned before) from a Word document are in the 'Authoring' part of the code.
They are simply invoked as commands from the NuPattern Authoring toolkit.

Take a look in: https://github.com/NuPattern/NuPattern/tree/master/Src/Authoring/Source/Authoring.Guidance for the code that does the heavy lifting.
and the command that invokes it is here, and does the project maintenance stuff: https://github.com/NuPattern/NuPattern/blob/master/Src/Authoring/Source/Authoring.PatternToolkit.Automation/Commands/CreateGuidanceDocumentsCommand.cs


What would the experience look like for someone wishing to create guidance in your mind? I mean, in terms of how they might expect to get to the starting line. (i.e. what nugets/toolkits/tooling do you think they would go after first, and tolerate installing first, and what would they need to get started in their solution?)