Windowstemplatestudio: Have ability to add pages or features to an existing project

[mrlacey]

Very much for v2 but noting the value in having such a thing. (And predicting requests for it and recognizing it was discussed as a possible feature during initial project discussions.)

Apps can changed and extended over time. It would be great to have a way to add new pages or features to a project that has already been created.

There are lots of potential quetions and issues about such functionality so raising this to gather thoughts and suggestions.

[ralarcon]

We already have started thinking on this... in my opinion would be a killer feature.

[crutkas]

@mrlacey we call this the right click "Add" feature. we cut it for 1.0 due to dead by edge case :)

[mrlacey]

I'm predicting this to be one of the most requested features moving forward.

[skendrot]

This is probably bigger than creating new projects

[mrlacey]

Add is complicated by the lack of certainty about the project that is being added to.

• Could it be any project or just ones originally created by the tool?
• What if things aren't where they're expected to be? (Moved, deleted or renamed)
• The same options as the creator tool? Or different ones?
• What about changes to the tool templates since the original project was created?

Lots of potential issues. A small mountain of edge cases to consider. Really solid error handling and reporting needed.

[crutkas]

This is a complex issue for multiple reasons. Lots of permutations and assumptions we will have to do.

100% agree this is a must have item. Just has to be done right.

[ralarcon]

One question here is if we want this for 1.1. It would take a while to have this feature finished and I was wondering if we would prefer to create a 1.1 release with less impact but quickly.

[mrlacey]

There's probably a bigger question about how quick we want a v1.1 and then how much we want. I suspect this will be dependent upon initial feedback after launch.

[crutkas]

agreed. I sadly have been punting 1.1 as "near term" fixes which maybe a better thought should be 1.1 vs a 1.5 major release. we need to maybe really think immediate items we can release VS items we need feedback before we can really move forward. This falls in to "we want it soon" but requires thinking/POCs and community feedback so much more of a major release milestone VS minor items.

Post Build, we really should go through and do some clean up and prioritization

[ralarcon]

Currently setting up a PoC to discover hidden requirements and figure out an approach.

[sibille]

PoC's finished, let's share and discuss our conclusions:

1. Mark page and feature templates with tag wts.rightClickEnabled and integrate 1 by 1 to resolve template specific problems step by step .

2. Start with right click support on WTS projects and add support for non-WTS projects in a future release. Non WTS projects would require a project "upgrade" to WTS project (Add ActivationService, ActivationHandler, modify App.xaml.cs).
   In a blank new project this is not an issue, but in a more complex project this could have unexpected impact.

3. Add Option "Undo last action":
   Although we are treating with WTS projects they could have changed a lot and adding a new item with right click could cause effects we cannot control. Although developers work with source control systems and commit is recommended before adding an item through right click, it is easy for us to know what files we changed during the right click action and make a backup of them. To recover from unexpected errors we suggest to incorporate a "undo last action" right click option, that restores a backup made before adding an item with right click.

4. Possible problems and suggested resolution

• Naming/File collisions: A template is composed of various classes whose names are determined on generation.
  _For example: Template Blank: Page; Name chosen by user: Product; Generates: ProductPage, ProductViewModel._
  Names a determined by the template engine generation. Before generation we cannot know which files in a project could be overridden.
  Approach: Generate the item in a separate folder, check for collisions in project, prompt user in case of collision and copy the items.

• Singleinstance templates behaviour:
  As we cannot determine 100% (due to renaming, deletions, ...) which templates were already added to the project, we'll always show all templates. Considering singleinstance templates do not allow to chose the name, adding them twice will not result in duplication but overwrite the old template.

• Failing merges: When executing a merge, one possible scenario on right click is a deleted merge target. For example: Application was initially generated with a ShellPage, but the user decided to rename this page. When adding a new page, there is a composition template that will try to add the page to the ShellPages navigation items.
  Approach: Give explanation on failed merges. f. ex: Could not find ShellViewModel.cs to add page to primary navigation items

• Missing /renamed base classes: When generating a new page for MVVM Basic, we assume there is a class Observable. If it was renamed, is not there, generated code will not compile.
  Approach: One option would be to regenerate those classes. We suggest to NOT regenerate them to avoid duplication (assuming the user refactored deliberately).

• Versioning: What if MVVMLight changes and base class name is no longer ViewModelbase? What if SplitView changes and uses NavigationView Control
  Approach: Use ProjectType/Framework name to version: MVVMLight2 (right click on MVVMLight does not allow to add MVVMLight2 templates)

[mrlacey]

I'm running the 'poc-rightclick' branch but can't see how to try this out. What am I doing wrong or what do I need to do to try this?

Some general comments though:

1.  
2. How would the restriction to WTS generated projects be enforced?
3. How would you know if you can/should "upgrade" a project?
4. How do you tell what project type and framework to use?

5. Lets' take a positive, proactive approach to making additions regardless of whether the project that adding to is as expected. We put things where we would put them on creation. If adding a Page and there's isn't a Views folder we create that folder. If we want to modify a file we expect to exist but doesn't, we make the other changes we can make and write a warning in the output window that something couldn't be done and why. "WTS Warning: When adding 'BackgroundTask1' file 'ActivationService.cs' could not be found and so was not modified. Please see [DOCSLINK] for more details."

6.  

7. Can we leave the managing of undo to the Visual Studio undo stack?

8. If going to enable the ability to undo something we should allow the undoing of multiple actions, not just the last step. If we added our own separate undoing of what we thought was the last action this could also be further complicated by other modifications since the last change made by WTS.

9. a. Naming/File collisions

10. Can we not access the existing project to detect for possible collisions?

11. Alternatively, if it's a manually entered name why not prompt to the user if creation fails? Like 'Add New Item' does? Although with a better error message than them. 😉

12. b. Singleinstance templates behaviour:

13. Can we not just fail if trying to add something when something with the same name already exists? Or skip with a warning?
14. I'd be very wary of overwriting something that may be very different just because it has the same name.

15. On a related note, does not being able to tell what already exists in a project prevent us from including anything with a dependency in the rightclick list? If we don't know if a dependency exists and can't add or replace it if something with the same name exists can it be included? Or do we just skip it if something with the same name exists and output an info comment saying skipping it as it appears to already exist?

16. c. Failing merges:

17. Yes, lots of output information if we can't do something we want or an expected file is missing.

18. d. Missing /renamed base classes

19. Assume we're adding into a project originally created with WTS. If the developer renamed something once, they can update the reference to a different base class name.

20. e. Versioning

21. If a framework introduced a new version with breaking changes we could introduce new versions of the framework in the template like you suggest.
22. Issues relating to changes within files provided by WTS (like the ShellPage in the NavPanel project) are more complicated. This is a bit of a "what if" scenario. We can't know how things may change in the future and this is just something we need to leave for now. NavigationView is a good thing to consider ass we know it will change in the next few months but for the sake of backward compatibility and merging I think it'll alright. While we may change the control on the page, we won't change the page name and individual menu entries will continue to be of our own type (NavigtionMenuItem) so all should be good.

Sorry, a bit of a brain dump but hopefully something useful there.

[sibille]

Thanks for your comments on this!!
The poc only includes add item from the vsEmulator. To add a new item, you have to execute the vsEmulator, create a new Project or load a project with the Load Project link. Next to the folder icon there is a new button that allows you to add a new item to the solution.

Similar to this screenshot :

Regarding your comments:
2.1 Initially we thought in including metadata in the appxmanifest of the project on generation (projectType and framework), if this data is there, right click will be available
2.2 Project upgrade will be developed in a second step, but we thought in asking the user to choose framework and projectType, and if he agrees do a WTS project initialization
2.3 From the appxmanifest
2.4 Yeah, that's what we thought. Assume things are we expect them to be, if they are not do not execute action's we cannot execute and inform the user
3.1 It's not possible to use the VS Undo stack, it only offers undo for editions done in VS
3.2 Undo will include the entire las action, including all of it's steps.
We decided not to add all actions as we'll provide the undo with the help of a backup of the modified files. For actions that lay further back in time, possibility that this backup is outdated (due to other modifications) increases
4a) Yes we can, the problem is the other side, we don't know the output of generation until generation is done, that's why we thought in a two step model:
Generate template, then sync with project (if there are conflicts, prompt the user before overwriting files)
4d) Are you saying generate with the original baseclass and let the user change, or generate with the new baseclass name (I don't see how this is possible)

[mrlacey]

2.1 Ok to adding something to the appxmanifest. Probably also worth adding in the WTS template version numbers too. These may be useful in the future if needing to update or add things in a different way because of changes to the templates.
Relying on these being in the manifest means that any apps already created with WTS 1.0 will also need to be updated.

3.1 No VS undo option is disappointing. I'm inclined to not include a single step undo option as the possibility of having to handle other user changes means there are all sorts of ways things could go wrong. Is there a safe way of including an undo option?

3.2. As the csproj will need to be a modified file it risks undoing other project level changes too. This concerns me.
How will you track which backup files to restore? You can't just replace every *.bak file as there may be other files of this name already there.

3 Undo
Can we think about this differently. There are two issues:

1. Not everyone using WTS to add to an existing project will be using version control.
2. Adding to an existing project may not work as expected or the person may wish to remove what they're added. Removing may not be a simple task as it may involve merging with many files.
   Someone without version control (and good branching & commit discipline) may get in an undesirable state when wanting to undo an addition and so we want to help them.
   Instead of trying to add an 'undo' option, which has all the complications we've been discussing, what if we added a note to the additions wizard which simply says: "We recommend taking a backup of your project before adding to it. If you're not using version control, create a backup now." where 'create a backup now' is a link which will just create a timestamped zip of the entire project directory. With this, they can easily go back to the point before adding if they wish and we avoid the complexities of trying to handle all undo scenarios. And as a bonus, we also suggest to them that they should be using version control if they aren't.

4a. So you want to generate the new files in a temp folder and check they can be integrated into the existing project, presumably by trying to build a copy of everything before doing the actual integration? That seems potentially time-consuming, especially if building requires a package restore first.
Is that really the best way we have to avoid collisions? I can't imagine that the VS add new file dialog has to do so much to detect this.
Alternatively, could the wizard could walk the existing project and extract the names of anything that might possibly be a collision (namespaces, classes, enums, structs) so we know what to avoid.

4d. Generate with the original/expected base class name. That's all we can do.

[ralarcon]

Thanks @mrlacey, let me give some clarifications...

3.1 VS Edit -> Undo will work at file edition level. If you remove or add a file from project, that action will not be included in the Edit->Undo stack.

Our thougths that, considering we know exactly which files have been added and which files have been modified, we can allow the user to restore the project to the state previous to the last generation action. We can warn the user informing which files will be removed and which files can be "undoed".

I see what you point as a risk (an agree with you), the user may generate, manually change other things in the generated files and then "undo last WTS generation" and may leave things worst... If i'm not wrong, we can know if some files has been modified after the generation, so we can enable the undo only if files don't have changes.

3.2 The templates define the primary-outputs, then we know which files has been added and which files modified (by post-actions). Then we will remove only our added files and modify (restore the content) of the updated files.

Agree to warn the user that he should use source control to ensure "we" do not break any valuable work.

4a Most time consuming parts of project creation with WTS are: the addition of items to the project and the package restore. The generation in a temp folder is extreamly fast. The backup of existing files previous to "actually add items to the project" is just a file copy (fast as well). Generating to a temp folder allow us to identify conflicts and / or issues (post-actions that didn't works fine). If we had conflicts we can warn the user before continue. In other words. The steps we think are required are:
1) Generate to temp folder
2) Gather the conflicts (issues applying post actions)
3) If issues, warn the user and (eventually) show which files are going to be modified (even we would show the changes).
4) Replace the target files and add them to the project (via DTE -slow part of the process).

I think using this approach we would have a robust "right click".

[crutkas]

we have a POC but won't hit 1.1

[mrlacey]

Please note that I consider this a breaking change to anyone with existing templates. Even just getting a new project to build has meant I've needed to modify all the VB postaction scripts.
This will also impact anyone with a fork they're using or if in development of new templates (thinking particularly of #438 - Caliburn)
Need to make the changes clear in release notes and point to latest (updated) documentation.

[ralarcon]

Absolutely agree @mrlacey. Those breaking changes are needed to put the merges one step beyond and enable to report back as well as differentiate among the different contexts making a post action to fail.

[mrlacey]

surely this can be closed now...