Port existing C# templates to VB

mrlacey commented 7 years ago

As a continuation of #371 and X-Ref https://github.com/Microsoft/WindowsTemplateStudio/wiki/Visual-Basic

Port existing C# templates to VB.

Pages

[x] Blank
[x] Settings
[x] WebView
[x] Media Player
[x] Master/Detail
[x] Grid
[x] Chart
[x] Tabbed
[x] Map
[ ] Image Gallery ?
[ ] Camera

Features

[x] Settings Storage
[x] Suspend and Resume
[x] BackGround Task
[x] Toast Notifications
[x] Azure Hub Notifications
[x] Dev Center Notifications
[x] Live Tile
[x] First Run Prompt
[x] What's New Prompt
[x] URI Scheme
[ ] Launch Feedback Hub ?
[ ] Share Source ?
[ ] Share Target ?
[ ] DragDrop Source ?
[ ] DragDrop Target ?

Need strategy and automation for the handling of future changes to C# templates and localization.

Needed (PowerShell?) scripts

[x] Identify missing VB pages/features
[x] Identify changes to CS pages/features/projects (based on file last modified time)
[x] Identify changes to CS pages/features/projects (based on git commits)
[x] Process to copy description changes and translations from CS equivalent config files

Needed automated tests

Some of these may need to be purely manual so that C# code can evolve ahead of VB...TBD

[x] Check non-code content is identical in projects created with the same options
[x] Check both using the same versions of 3rd party libraries
[x] Check comments are the same in equivalent files
[x] Structure, formatting, coding conventions, etc. of generated VB code (via SonarLint)
[x] Check equivalent code files contain equivalent elements (via Roslyn)
[ ] Check equivalent generated projects function the same way (via WAD)
[ ] Check equivalent generated project create the same visual output (via WAD)

Need to update documentation for VB support.

Update

[ ] Main readme
[ ] CONTRIBUTING
[ ] Activation
[ ] GettingStarted *n
[ ] Templates
[ ] docs/projectTypes/navigationpane.md
[ ] docs/features/whats-new-prompt.md
[ ] docs/pages/settings.md *n
[ ] anything else with code samples?

mvegaca commented 7 years ago

Hi @mrlacey @ralarcon @crutkas Reviewing VB templates I've seen that we can use the same XAML code instead of duplicate those files. These files are the same file. .\templates\Pages\Blank\Views\BlankViewPage.xaml .\templates\Pages\BlankVB\Views\BlankViewPage.xaml

It makes sense to add the same XAML code on a different composition template? Will this code be always different on most of the pages? Have we planned how are going to grow on CSharp, VB, XAML y Xamarin?

mrlacey commented 7 years ago

I chose this approach for several reasons:

Having a copy of the XAML was the simplest approach and avoided having to change all the existing C# templates. I didn't want to have to change all existing templates and I didn't want to force anyone else writing future C# templates to do more work that was necessary to support VB in that we're not expecting or requiring new templates to be written for anything other than C#. If we did put the XAML in a composition template to make it possible to share it with a VB version, the only real way of making sure that it did work correctly would be to also write the VB version so we'd be requiring more work and making people work in a language (that in all likelihood) they did not use or want to learn to use.
Moving the XAML to composition templates would further complicate the template authoring process. This will not only increase the time needed to author new templates but also the complexity that any new contributor would need to understand. (We want more contributors and I expect that the more complicated we make it to contribute the less likely people will be to doing so.)
In my experience, the more composition involved in creating a page/feature/project the harder it is to debug it when it doesn't generate exactly as desired. More time spent debugging is less time spent fixing other bugs or working on new functionality.
I'm requiring the VB versions to use the exact same XAML files as the C# versions. Copying the version over is a simple and absolute way of enforcing this. It avoids getting into unnecessary complication from someone in the future creating different versions of the same file and using language flags to control which is selected. At this point, the value of putting them in a separate directory is lost.
While working on a template I find it much simpler to have the related files in the same directory. Putting the XAML files in a far off folder makes things more complicated. (Working on new features with lots of composition templates has taught me things are much easier when they're all together.)
It's not just XAML this applies to but to other files that are copied. If we broke out all the description, images, project reference merges, etc. the composition templates would get even more complicated.
The Xamarin branch will use different XAML and so is irrelevant to the discussion of how the C# & VB versions of UWP projects share XAML files.

So, in conclusion, Yes, we could split out all the XAML files into another set of templates that get composed but it would be a lot of work to write and test this change for the sake of getting rid of one PowerShell script when there are a lot of other more important things we could be focusing that time and effort on.

For all of this, the VB work is coming as a "community contribution" so there's a disclaimer that comes with it ever being behind the C# version. VB support isn't official and blessed by Microsoft and not something I'm expecting them to work on. If this were to change it would require a lot more investment from them as it would slow the pace of the project. If others from the community come forward to help support the VB work, or we get contributions of VB versions of templates first, or Microsoft's priorities change; then we can revisit this.

For further reference, there were also comments on this subject here

mvegaca commented 7 years ago

Hi, Matt. I agree with you, composition templates for XAML code would be a nightmare, I just was trying to open the conversation... I was thinking in the following:

All templates could decide what languages are available for:
- BlankPage.xaml & BlankPage.xaml.cs -> Available for C#
- BlankPage.xaml & BlankPage.xaml.vb -> Available for VB
- BlankPage.xaml & BlankPage.xaml.cs & BlankPage.xaml.vb -> Available for C# and VB

The same template includes CS and VB Code, both languages share XAML code included in the same folder... to enable this we will need to include some metadata in the template.json file to enable select the appropriated files once generated... sure this will deserve a PoC and considering it is not a priority, we can leave this open for the near future...

mrlacey commented 7 years ago

Another problem with having a XAML file only appear once in the template folder structure is it adds more complexity to the process for filtering templates. At the moment it works by copying whole folders. If we start sharing files the copying logic gets more complicated. It's not just a case of copying a directory if it is for the required language, it would then be a case of also copying other files which go with that template. Yes, all unnecessary complexity we don't need for now. Part of my reason for doing the work to support VB now was to find issues that make things more complicated or required code changes to make possible. It would have been better if we could have caught these issues earlier but hopefully doing it now will avoid other issues down the line.

mrlacey commented 7 years ago

Moving milestone back as won't happen for 1.4 - just trying to set expectations.

mrlacey commented 7 years ago

What are "installer icons with language adorners"? Glad you asked

crutkas commented 7 years ago

Where do said icons live?

mrlacey commented 7 years ago

@crutkas copies of adorners at https://github.com/Microsoft/WindowsTemplateStudio/tree/Issue863-VBTemplates/design/Assets/Logo/icon-adorners Original icon file at https://github.com/Microsoft/WindowsTemplateStudio/blob/Issue863-VBTemplates/design/Assets/Logo/windowsTemplateStudio_Logo_256x256.ico Language specific icons are: https://github.com/Microsoft/WindowsTemplateStudio/blob/Issue863-VBTemplates/code/src/ProjectTemplates/CSharp.UWP.2017.Solution/windowsTemplateStudio_Logo_256x256.ico and https://github.com/Microsoft/WindowsTemplateStudio/blob/Issue863-VBTemplates/code/src/ProjectTemplates/VBNet.UWP.VS2017.Solution/windowsTemplateStudio_Logo_256x256.ico

Nukepayload2 commented 7 years ago

I want to port the URI Scheme feature. Please leave it to me.

mrlacey commented 7 years ago

I want to port the URI Scheme feature. Please leave it to me.

@Nukepayload2 As probably the most complicated feature (in terms of the number of composition templates) and requiring the most manual testing I wasn't looking forward to that. Go ahead.

Nukepayload2 commented 7 years ago

Why ".csproj" is hard coded in BaseGenAndBuildFixture.BuildAppxBundle(String, String) ? It causes RunWackOnProjectWithAllPagesAndFeaturesAsync(String, String, String) always fail when testing VB templates.

mrlacey commented 7 years ago

Why ".csproj" is hard coded ?

Because everything only initially supported C# and so this wasn't an issue. Part of the work to support VB templates is adapting all the testing and generation logic to also support more than just C#.

mrlacey commented 7 years ago

The current plan is to close this and merge all the VB templates that have been created so far so that we can start gathering feedback on them from the dev nightly builds.

Creating new issues to follow on from the above items that weren't completed.

There is a known issue with the MasterDetail visual output where symbols are not displayed properly. This was not fixed so it can be used as a reference when adding tests to confirm identical visual output of identical projects created with the different languages.

If any other problems are discovered these should be raised as issues.

mrlacey commented 7 years ago

Closing this as these templates are now available in the dev-nightly build. Separate issues have been created for each of the above-noted items that were not completed as part of the PR for this issue. (These only relate to docs or were otherwise blocked.)

Any feedback on these templates will be greatly appreciated. Try them out yourself by installing the dev-nightly version of the templates.

microsoft / TemplateStudio