updating docs
This commit is contained in:
Clint Rutkas
Родитель
01d39e98ee
Коммит
4f0cbb736f
|
|
@ -6,11 +6,13 @@ A developer should be able to quickly and easily add features, pages, and have a
|
|||
|
||||
That's why many of the guidelines of this document are obvious and serve only one purpose: Simplicity.
|
||||
|
||||
Also remeber that the Pull Requests must be done aganist the **[dev branch](https://github.com/Microsoft/WindowsTemplateStudio/tree/dev)**.
|
||||
|
||||
## A good pull request
|
||||
|
||||
Every contribution has to come with:
|
||||
|
||||
* Before starting coding, **you should open an issue** and start discussing with the community to see if your idea/feature is interesting enough
|
||||
* Before starting coding, **you must open an issue** and start discussing with the community to see if the idea/feature is interesting enough.
|
||||
* A documentation page in the [documentation folder](https://github.com/Microsoft/WindowsTemplateStudio/tree/dev/docs).
|
||||
* Unit tests (If applicable)
|
||||
* You tested your code with two most recent Windows 10 SDKs. (Build 14393 and 15063)
|
||||
|
|
|
|||
|
|
@ -1,32 +1,33 @@
|
|||
Getting Started with the Extension
|
||||
==================================
|
||||
# Getting Started with the Extension
|
||||
|
||||
## Installing the Visual Studio Extension
|
||||
|
||||
You can download the official extension from the [Visual Studio Gallery](https://visualstudiogallery.msdn.microsoft.com/) (coming soon).
|
||||
### Visual Studio Extension Feed URLs for Windows Template Studio
|
||||
|
||||
* **Pre-release (stable)** https://www.myget.org/F/prerelease/vsix/
|
||||
* **Nightly** https://www.myget.org/F/vsixextensions/vsix/
|
||||
* **(Coming soon)** The official extension from the [Visual Studio Gallery](https://visualstudiogallery.msdn.microsoft.com/)
|
||||
|
||||
### Pre-release build version
|
||||
|
||||
The Pre-release build version allows you to get updates with stable features not officially released yet (so, they are not definitive and may change).
|
||||
|
||||
This feed will have stable extension versions so it is not thought to have breaking changes (and can be installed side by side with the official one), anyway, installing this extension is at your own risk.
|
||||
This feed will have stable extension versions so it is not thought to have breaking changes (and can be installed side by side with the official one), anyway, installing this extension is at your own risk.
|
||||
|
||||
Open Visual Studio 2017 and go to Tools -> Extensions & Updates, then click on "Change your Extensions and Updates settings" and create an Additional Extension Gallery using https://www.myget.org/F/prerelease/vsix/ as Url.
|
||||
Open Visual Studio 2017 and go to Tools -> Extensions & Updates, then click on "Change your Extensions and Updates settings" and create an Additional Extension Gallery.
|
||||
|
||||
|
||||
|
||||
Then, go again to Tools -> Extensions & Updates and using the recently added online gallery, install the Uwp Community Extension.
|
||||
Then, go again to Tools -> Extensions & Updates and using the recently added online gallery, install the Windows Template Studio extension.
|
||||
|
||||
|
||||
|
||||
Once installed, you will see a new Project Template which allows you to access to the available templates: Pre-Release version uses the VNext Template Repository.
|
||||
|
||||
|
||||
|
||||
|
||||
You can start working with Windows Template Studio by cloning [our repo](https://github.com/Microsoft/WindowsTemplateStudio) and working locally with the code and the available templates.
|
||||
You can start working with Windows Template Studio by cloning [our repo](https://github.com/Microsoft/WindowsTemplateStudio) and working locally with the code and the available templates. If you plan to contribute, please follow the [contribution guidelines](../contributing.md)
|
||||
|
||||
If you plan to contribute, please follow the [contribution guidelines](../contributing.md) and remeber that the Pull Requests must be done aganist the "[dev](https://github.com/Microsoft/WindowsTemplateStudio/tree/dev)" branch.
|
||||
## Nighlty Dev-release
|
||||
|
||||
## Nighlty Dev-release
|
||||
If you want to have updates from in-progress changes, you can confiure the Nightly-Dev feed using this url: https://www.myget.org/F/vsixextensions/vsix/
|
||||
|
||||
This feed will have the result of the daily dev-branch integration so expect some instability. This extension can be installed side by side with the offical and pre-release, anyway, installing this extension is at your own risk.
|
||||
If you want to have updates from in-progress changes. This feed will have the result of the daily dev-branch integration so expect some instability. This extension can be installed side by side with the offical and pre-release, anyway, installing this extension is at your own risk.
|
||||
|
|
@ -1,14 +1,12 @@
|
|||
Getting Started with Windows Template Studio
|
||||
===============
|
||||
#Getting Started with Windows Template Studio
|
||||
|
||||
This section have the main concepts and definitions used in Windows Template Studio.
|
||||
|
||||
To start working with the latest version of this code, check [Getting Started for Developers](getting-started-developers.md)
|
||||
|
||||
To start using the Windows Template Studio extension, [Getting Started with the Extension](getting-started-extension.md)
|
||||
|
||||
To start authoring templates, check [Understanding the Templates](templates.md)
|
||||
|
||||
If you plan to contribute, please follow the [contribution guidelines](../contributing.md) and remeber that the Pull Requests must be done aganist the "[dev](https://github.com/Microsoft/WindowsTemplateStudio/tree/dev)" branch.
|
||||
* [Getting Started](docs/getting-started.md)
|
||||
* [Installing / Using the extension](docs/getting-started-extension.md)
|
||||
* [Getting started with the generator codebase](docs/getting-started-developers.md)
|
||||
* [Authoring Templates](docs/templates.md)
|
||||
* [Contribution guidelines](contributing.md)
|
||||
|
||||
## Main concepts
|
||||
Windows Template Studio is divided in the following main elements:
|
||||
|
|
|
|||
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 59 KiB |
|
|
@ -1,24 +1,26 @@
|
|||
Understanding the Templates
|
||||
====================
|
||||
# Understanding the Templates
|
||||
|
||||
Templates are used to generate the code. In Windows Template Studio we have the following kind of templates: Frameworks, Projects Types, Pages, Developer Features and Consumer Features.
|
||||
Templates are used to generate the code. In Windows Template Studio we have the following kind of templates: Frameworks, Projects Types, Pages, Developer Features and Consumer Features.
|
||||
|
||||
For example, you may want to generate a project to create an App which use the Split View (hamburguer) menu, based on MVVM Light framework, with some pages (Home, Products -a master detail page-, Find Us -a map page-, etc. ) and which include some developer features. Or maybe you want to create the same project but avoiding to depend on a certain external framework, in other words, you want the same stuff but using a MVVM Basic framework.
|
||||
|
||||
The Window Template Studio allow to combine the templates at your own convenience to generate the project you want, using your preferred framework and using the features you most like.
|
||||
The Window Template Studio allow to combine the templates at your own convenience to generate the project you want, using your preferred framework and using the features you most like.
|
||||
|
||||
# NxM Issue and Template Authoring principles
|
||||
## Template Authoring principles
|
||||
|
||||
As mentioned, you can combine Frameworks with Project Types and add Pages and Features. That is, you can have "Count(Frameworks) * Count(Project Types)" combinations and all the pages and framewoks must fit for each combination. If we have 3 frameworsk and 3 project types, we will have 9 combinations. We need to support all the pages for this combinations, so if we have 6 types of pages, we will need to maintain 9x6 = 54 Pages (mainly with the same code). The same happen for Features. Having templates created linearly is unmanageble, this is what we call NxM issue.
|
||||
As mentioned, you can combine Frameworks with Project Types and add Pages and Features. That is, you can have "Count(Frameworks) * Count(Project Types)" combinations and all the pages and framewoks must fit for each combination. If we have 3 frameworsk and 3 project types, we will have 9 combinations. We need to support all the pages for this combinations, so if we have 6 types of pages, we will need to maintain 9x6 = 54 Pages (mainly with the same code). The same happen for Features. Having templates created linearly is unmanageble, this is what we call MxN issue.
|
||||
|
||||
To avoid the NxM issue, we have designed the Templates as composable items (frameworks, projects, pages and features), which make the Template authoring a bit complex, but infinite more maintaneable in long term.
|
||||
To avoid the M*X issue, we have designed the Templates as composable items (frameworks, projects, pages and features), which make the Template authoring a bit complex, but infinite more maintaneable in long term.
|
||||
|
||||
We strong follow two principles for Template authoring:
|
||||
|
||||
* Principle #1: Templates are composable.
|
||||
* Principle #2: Avoid code duplication.
|
||||
|
||||
# Templates repository structure
|
||||
## Templates repository structure
|
||||
|
||||
The [Templates Repository](../templates) have the following structure:
|
||||
|
||||
* [Projects](../templates/Projects) --> Project type templates. This kind of templates define the navigation and global layout for the app.
|
||||
* [Frameworks](../templates/Frameworks) --> Framework templates. This kind of templates define the base frameworks / coding style for the app.
|
||||
* [Pages](../templates/Pages) --> Page Templates. This kind of templates define the different types of pages available for the apps.
|
||||
|
|
@ -28,22 +30,26 @@ The [Templates Repository](../templates) have the following structure:
|
|||
At the end, a Template is just code with some metadata. The metadata will contain the template information: name, description, licensing, remarks, programming language, type, guids, etc. The templates definition is based on [dotnet Template Engine](https://github.com/dotnet/templating), you can visit their repo for deep understanding on how the Template Engine works.
|
||||
|
||||
## Templates anatomy
|
||||
|
||||
In general, a template will have a folder and files structure which defines itself as a template. Depending on the kind of template the internal structure may differ but, in general, all the Templates define some metatada and a folder structure with files where the Template Engine apply the replacements.
|
||||
|
||||
TBD: Templates and Generation
|
||||
TBD: Mention Templates Composer && Post Actions
|
||||
|
||||
### Pages, DevFeatures and CustomerFeatures Templates
|
||||
|
||||
This kind of templates have the following structure:
|
||||
|
||||
* **Metadata Folder** (.template.config). Here we can find the template definition file (this is the [dotnet Template Engine](https://github.com/dotnet/templating) definition file). In this file is defined the metadata used while the engine make the code generation.
|
||||
* **Code and folders structure**. This structure will be maintaned once generated.
|
||||
|
||||
Let examine the template anatomy for the ["Blank" Page](../../templates/Pages/Blank):
|
||||
|
||||
* .template.config: Folder containing the Template metada configuration.
|
||||
* icon.png: icon that will be shown in the Wizard.
|
||||
* template.json: this is the template definition file itself. The template definition file determine which replacements will be done and which information will be returned to the generation engine. For example, the template definition defines "Blank" as "name" for the template. This means that "Blank" will be replaced by the parametrized name during the generation.
|
||||
* View: Folder containing the source code files for the page view (.xaml, and .xaml.cs)
|
||||
* ViewModel: Folder containing the source files for the view model.
|
||||
* icon.png: icon that will be shown in the Wizard.
|
||||
* template.json: this is the template definition file itself. The template definition file determine which replacements will be done and which information will be returned to the generation engine. For example, the template definition defines "Blank" as "name" for the template. This means that "Blank" will be replaced by the parametrized name during the generation.
|
||||
* View: Folder containing the source code files for the page view (.xaml, and .xaml.cs)
|
||||
* ViewModel: Folder containing the source files for the view model.
|
||||
|
||||
Following you can see some details from the template.json file.
|
||||
|
||||
|
|
@ -78,21 +84,22 @@ Custom tags (starting with 'utc.') that are used to organize the templates infor
|
|||
If we generate this template using the name "MyPage", the result will be a folder structure as follow:
|
||||
|
||||
* View (Folder)
|
||||
* MyPageView.xaml
|
||||
* MyPageView.xaml.cs
|
||||
* MyPageView.xaml
|
||||
* MyPageView.xaml.cs
|
||||
* ViewModel (Folder)
|
||||
* MyPageViewModel.cs
|
||||
* MyPageViewModel.cs
|
||||
|
||||
Pages, DevFeatures and CustomerFeatures templates are Framework and Project Type agnostic. Once generated, some Post-Actions are executed to adjust the generation to the framework and project type select by the user.
|
||||
|
||||
## Composable Generation
|
||||
|
||||
<TBD> Explain how the composable generation works
|
||||
*TODO:* Explain how the composable generation works
|
||||
|
||||
mention the composer
|
||||
|
||||
## Post Actions
|
||||
Befor drilling down in Framework and Projecty Type templates, there is an important concept we use to be able to maximize the code reuse and be able to apply particular code requirements to the generated projects. As metinoned before, Page, DevFeatures and CustomerFeatures are Framework and Project Type agnostic. Post-Actions are designed to complement the agnostic generation and get the expected final results. Imagine we have a certain page, the final code needed to be generated for this page is slightly different depending on which framework are we are using (i.e. namespaces required) and depending on which project type we are using (i.e. the navigation).
|
||||
|
||||
Befor drilling down in Framework and Projecty Type templates, there is an important concept we use to be able to maximize the code reuse and be able to apply particular code requirements to the generated projects. As metinoned before, Page, DevFeatures and CustomerFeatures are Framework and Project Type agnostic. Post-Actions are designed to complement the agnostic generation and get the expected final results. Imagine we have a certain page, the final code needed to be generated for this page is slightly different depending on which framework are we are using (i.e. namespaces required) and depending on which project type we are using (i.e. the navigation).
|
||||
|
||||
For example, consider we are creating a SplitView project type with MVVM Basic framework, we add several pages to the project. At the end, all the pages must be registered in the navigation and added to the navigation menu, the generated code will looks like:
|
||||
|
||||
|
|
@ -129,22 +136,28 @@ But the Pages templates are Framework and Project type agnostics, and more over,
|
|||
After the code is generated, the [PostActionFactory]() review all the generated files and, for those which the name contains "_postaction", execute the post-action defined in its content.
|
||||
|
||||
### Post-Action Types
|
||||
TBD: complete types of postactions
|
||||
*TODO:* complete types of postactions
|
||||
###
|
||||
|
||||
## Frameworks Templates
|
||||
|
||||
This templates contains all the generation information required by specific frameworks. Basically, contains the metadata and the post actions required to apply to a certain project or page during the generation to ensure the Framework infrastructure is added.
|
||||
|
||||
This kind of templates have the following structure:
|
||||
|
||||
* **Metadata Folder** (.metadata). Information about the framework. This information is displayed in the wizard.
|
||||
* **Code and folders structure**. The folder structure for this kind of templates is really important as it defines which specific code will be generated and which post-actions will be applied (as well as the post-action targets)when the user selects this kind of framewok.
|
||||
|
||||
|
||||
## Project Type Templates
|
||||
|
||||
*TODO:* documentation is pretty sparce below here
|
||||
|
||||
### Layouts
|
||||
|
||||
## Basic Authoring
|
||||
TBD -> Probably in a differnt Page
|
||||
|
||||
*TODO:* Probably in a different Page
|
||||
|
||||
### Add a new page
|
||||
|
||||
|
|
@ -158,25 +171,31 @@ After the code is generated, the [PostActionFactory]() review all the generated
|
|||
###
|
||||
|
||||
## Frameworks Templates
|
||||
|
||||
This templates contains all the generation information required by specific frameworks. Basically, contains the metadata and the post actions required to apply to a certain project or page during the generation to ensure the Framework infrastructure is added.
|
||||
|
||||
This kind of templates have the following structure:
|
||||
|
||||
* **Metadata Folder** (.metadata). Information about the framework. This information is displayed in the wizard.
|
||||
* **Code and folders structure**. The folder structure for this kind of templates is really important as it defines which specific code will be generated and which post-actions will be applied (as well as the post-action targets)when the user selects this kind of framewok.
|
||||
|
||||
|
||||
## Project Type Templates
|
||||
|
||||
### Layouts
|
||||
|
||||
## Basic Authoring
|
||||
TBD -> Probably in a differnt Page
|
||||
|
||||
*TODO:* Probably in a different Page
|
||||
|
||||
### Add a new page
|
||||
|
||||
### Add a new feature
|
||||
|
||||
## Advance Authoring
|
||||
TBD ->
|
||||
|
||||
*TODO:* Probably in a different Page
|
||||
|
||||
### Add custom post-actions??
|
||||
|
||||
### Add new framework
|
||||
|
|
|
|||
16
readme.md
16
readme.md
|
|
@ -1,10 +1,5 @@
|
|||
# Windows Template Studio
|
||||
|
||||
|Env|CI |Templates Publishing |Extension Publishing |
|
||||
|:-----|:--------:|:-------------------:|:-------------------:|
|
||||
|dev| |  | |
|
||||
|pre-release||||
|
||||
|
||||
Windows Template Studio goal is to help developers with their File->New experience in Visual Studio. It will generate a strong, generic foundation with the pages you need, but also integrate game changing features from the start. Any critical features will have code comments with links to MSDN, stack overflow and blogs to help unblock developers. Once the template is generated for the developer, it can provide base sample data and will be able to compile then run without issue.
|
||||
|
||||
Example scenario:
|
||||
|
|
@ -14,11 +9,18 @@ To reach our developers in an up-to-date fashion, the project is broken up into
|
|||
|
||||
## Getting Started
|
||||
|
||||
Please read the [Getting Started with Windows Template Studio](docs/getting-started.md) page for more detailed information about using Windows Template Studio.
|
||||
|
||||
* [Getting Started](docs/getting-started.md)
|
||||
* [Installing / Using the extension](docs/getting-started-extension.md)
|
||||
* [Getting started with the generator codebase](docs/getting-started-developers.md)
|
||||
* [Authoring Templates](docs/templates.md)
|
||||
* [Contribution guidelines](contributing.md)
|
||||
|
||||
## Build Status
|
||||
|
||||
|Env|CI |Templates Publishing |Extension Publishing |
|
||||
|:-----|:--------:|:-------------------:|:-------------------:|
|
||||
|dev| |  | |
|
||||
|pre-release||||
|
||||
|
||||
## Features
|
||||
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче