# Sitecore DevEx Visual Studio add-in
Welcome to the Sitecore DevEx Visual Studio add-in. This tool is designed to work with the new 
Sitecore developer experience command-line tools to provide seemless integration
into Visual Studio 2019. The tool provides:

 - Module Configuration visualization
 - Module Configuration editor
 - Environment Editor
 - Serialization Compare tool
 - Serialization tree visualization tool
 - Automated build components
 - Automated build component editor

## Installing the add-in
The Visual Studio add-in consists of two components. The .VSIX add-in and the 
NuGet build components. The VSIX add-in is installed by double-clicking on the 
.VSIX file in Windows Explorer. This runs the VSIX installer to install the 
add-in.

The NuGet packages should be placed in a local folder and the folder path should
be added as a NuGet feed. This is done by opening the Package Manager settings 
dialog under the Tools -> NuGet Package Manager -> Package Manager Settings menu.

Press the "+" icon at the top right and add the local package folder as the 
source and name the package source:

![NuGet Package Manager](./Images/NuGetPackageManager.png)

## Using the add-in
The add-in provides functionality to help the developer work with the new 
Sitecore developer experience tools in Visual Studio 2019 when the developer 
is working on a solution using the Sitecore Developer Experience tools.

Th Sitecore Developer Experience tools need to be initialized using the 
command line tool. Typically, this is done using the `sitecore init` command. 
For more information, please see the Sitecore Developer Expereince documentation.

When a solution is using the Sitecore Developer Experience tools, a new menu
option will be added to the solution right-click menu that allows the developer
to open the **Sitecore Module Explorer**.

![Solution right click](./Images/SolutionRightClick.png)

The **Sitecore Module Explorer** tool window will be opened on the left side of 
Visual Studio.

![Initial Sitecore module explorer](./Images/InitialSitecoreModuleExplorer.png)

### Sitecore Module Explorer
The **Sitecore Module Explorer** allows you to edit all .json files that make up the
Sitecore Developer Experience configuration using a visual editor instead of 
editing the raw .json files.

Some of the elements in the **Sitecore Module Explorer** are used as containers for
other module explorer configuration files. These elements are not editable,
and will not open an editor, but may have right-click menus to support the 
configuration elements under them.

Any element that has a backing .json file will have a *View Code* option on the 
right-click menu. This allows the developer to view and edit the .json file in
the Visual Studio .json editor. This can be used instead of the form editor if
the developer wishes to directly work on the .json file.

All of the editor forms in the **Sitecore Module Explorer** are saved when the
developer click on "Save" or "Save All" in Visual Studio much like any other 
code/resource window.

#### Editing the sitecore.json file
The `sitecore.json` file is the root element in the **Sitecore Module Explorer** 
called `Sitecore Configuration Root`. To open the editor, double click on the 
`Sitecore Configuration Root` element:

![Sitecore Configuration Root](./Images/SitecoreConfigurationRootEditor.png)

The user can update the default settings for serialization and also quickly add 
module file glob paths.

### Environments
Environments are connections to a Sitecore server. These are stored in a file
`.sitecore/user.json` under the project root.

#### Creating and Editing Environments
To add your first environment, right click on `Environments` and choose 
*New Environment*. This will create a new Environment entry in the 
`.sitecore/user.json` file.

![New Environment](./Images/NewEnvironment.png)

If you name your environment "default", it will be the environment chosen 
by the command line tools if not environment is specified.

Double clicking on an environment will open the environment in an editor pane.
This can be updated and saved like any other editor pane.

#### Removing Environments
Right clicking on an environment under the Environments element and selecting 
*Remove Environment*. This will prompt the user to delete the environment.
Choosing "Yes" will immediately delete the environmnt from 
`.sitecore/user.sitecore`

### Modules
Modules in Sitecore Developer Experience are used to configure serialization for
different parts of an implementation. Each module defines how to seralize a
differe part of the Sitecore tree.

#### Adding Your First Module
Module Globs need to be defined in the `Sitecore Configuration Root` so the
Sitecore Developer Experience tools can find the `*.module.json` files in the
solution structure. Typically, your solution has a structure similar to:

    ├───.sitecore
    └───src
        ├───BasicCompanyBuild
        ├───BasicCompanyItems
        │   └───serialization
        ├───Feature
        │   └───BasicCompany
        │       ├───Accordion
        │       ├───HeroBanner
        │       ├───PromoCard
        │       ├───PromoContainer
        │       └───SectionHeader
        ├───Foundation
        │   └───Navigation
        ├───Project
        │   └───serialization
        └───Sitecore.RenderingHost.Helpers

If you want to have your `*.module.json` files located in each of the folders under 
/src, your module glob would be `src/*/*.module.json`

If you want to put your module files under folders like 
src/Feature/BasicCompany/Accordion your module glob would be 
`src/*/*/*/*.module.json`.

Once you have added the correct module globs to your `sitecore.json`, you can
right-click on the Modules element in the **Sitecore Module Explorer** and select
*New Module*. This will open a dialog box that lets the developer name the 
new module and choose the location of the module file:

![New Module](./Images/NewModule.png)

#### Editing Modules
Double clicking on a module will open the module editor pane. This allows you to 
edit settings that pertain to all serialzation trees in the module.

![Edit Module](./Images/EditModule.png)

##### Includes
Modules can contain multiple include entries, which describe the section of the 
Sitecore tree to serialize. Opening the module shows all includes that are 
part of the module. Right-clicking on a module and selecting *Add Include*
allows the developer to add an include entry to the module.

![Edit Include](./Images/EditInclude.png)

For more information on the meaning of the various settings in the include
editor, please see the Sitecore Developer Experience documentation.

An include can be removed by right-clicking on the include and choosing 
*Remove Include*

Expanding an include shows a `Rules` folder and an `Items` folder. The
`Items` folder contains all items serialized from the content tree
based on the parameters specifed in the include.

Double clicking on a serialized item will open the item file in a
Visual Studio text editor.

##### Rules
Rules modify the behavior of an include. An include can have multiple rules, 
and the order of the rules dictates the order the rules are evaluated. 
Expanding an include shows a `Rules` folder that containes the rules 
being applied to the include.

To add a new rule, right click on an include or the `Rules` folder and 
choose *Add Rule*. This will open a new rule editor pane and create the rule
under the include.

After adding the rule, it can be edited in the Rule editor pane.

![Edit Include](./Images/EditRule.png)

The Up and Down arrows on the left side of the rule editor pane allow 
the developer to re-order the rules under an include.

### Serializing items
The serialization window can be opened by right-clicking the root item or any 
module in the **Sitecore Module Explorer**. If serialization is opened from the
root, all modules will be evaludated for serialization. If opened from a module,
the items for the selected module will be evaluated for serialization.

If there is a difference between the serialized items in the solution and the 
target Sitecore environment, the sync window will show the differences grouped
by the module the difference occurs in:

![Sync Window](./Images/SyncWindow.png)

This is an example of the information the **Sync Window** will show. 
In this example, there are changes to the "templates" module in the form 
of a rename, and update and a create. There is also a change to the Home item.

#### Sync Window Toolbar
The sync window toolbar allows the developer to choose how the **Sync Window** 
compares the items in the selected Sitecore instance to the serialized items in 
the modules. The functions on the toolbar are as follows:

|Button| Description|
|----- |-------------|
|![Refresh](./Images/SyncWindow_Refresh.png)|Refreshes the **Sync Window** with the latest changes.|
|![Environments](./Images/SyncWindow_Environments.png)|Allows the developer to choose the environment to compare their local items.|
|![Push/Pull](./Images/SyncWindow_PushPull.png)|Toggle that allows the developer to Pull from Sitecore or Push to Sitecore.|
|![Search?](./Images/SyncWindow_Search.png)|TBD - Placeholder for new functionality.|
|![Filters](./Images/SyncWindow_Filters.png)|Allows the user to choose the modules to sync.|

#### Using the Sync window
The **Sync Window** allows users to update the items in Sitecore or update the 
serialized items in the modules. The user can click the "Push/Pull" toggle 
to select the direction for their update.

After the **Sync Window* finishes comparing the items to Sitecore, the 
developer clicks the check boxes next to an item to choose an item for 
update. The checkbox in the blue module area selects everything for the 
selected module for the sync operation. There is also a "Select All" check 
box for selecting or de-selecting everything.

After selecting the items to sync, the developer can click the "Do Sync" button 
to perform the sync operation.

If there are no errors during the sync operation, the items chosen for syncing 
are greyed out, and can not be selected. Pressing "Refresh" will perform the 
compare operation again and any items that were previously updated will be 
removed from the list.

#### Updated items
If an item has been updated, there is a small 
![Update Details](./Images/SyncWindow_UpdateDetails.png) icon to the right of the
updated item. This shows the fields that are different between the item in Sitecore
and in the serialized file.

#### Sync Errors
If any errors are found during the sync process, the **Sync Window** will show the 
errors encountered during the sync operation. There will be a "Validate" button
in place of the refresh button that can be used to attempt to repair the errors.
This performs the same operation as the command `sitecore ser push -validate`.

![Sync Window](./Images/SyncWindow_Errors.png)

After pushing validate, the developer will be presented with a list of the 
problems found in each module:

![Sync Window](./Images/SyncWindow_Validate.png)

Pressing the "Fix Errors" button at the bottom of the screen will perform the
fixes shown in the list. After fixing the errors, the user can click "Validate"
again to check the fixes and if there are no errors, the **Sync Window** will be
refreshed.

### Sitecore Developer Experience build components
The Sitecore developer experience build components require the NuGet package
SIC.TDS.Build.0.3.0.nupkg to be reachable in one of the users NuGet feeds. 
Please see above for instructions on setting up the feed.

#### Adding the build components
Adding the build components is done by right-clicking on the solution and adding
a new project. 

The project name to search for is "Sitecore Instance Configuration Project". 
Please Note, this name will be changed in the future.

![New Project](./Images/NewProject.png)

Pressing "Next" will let you name and then create the project. This will add
the project to the solution. It may take a few seconds for the NuGet package
to be restored for the new project. After the packages have been restored,
it should show up in the Solution Explorer:

![New Build Project](./Images/NewBuildProject.png)

#### Setting up the NuGet feed for the build components
The Sitecore for Visual Studio build components uses a NuGet package to provide
the build project with the components it needs. This NuGet package is automatically
referenced in the project, but you may need to add a new Nuget feed to your NuGet package 
feeds so the package is downloaded at build time.

The feed is: https://sitecore.myget.org/F/sc-developer-collection/api/v3/index.json

You can add this to your NuGet.config file or to the feed source in Visual Studio.

The following is an example of a NuGet.config with the developer collection feed:

    <configuration>
      <!--
      Used to specify the default Sources for list, install and update.
      -->
      <packageSources>
        <clear />
        <add key="Nuget" value="https://api.nuget.org/v3/index.json" />
        <add key="SitecorePreview" value="http://sitecore-nuget-preview:8010/index.json" />
	    <add key="SVSComponents" value="https://sitecore.myget.org/F/sc-developer-collection/api/v3/index.json"/>
      </packageSources>

      <activePackageSource>
        <!-- this tells that all of them are active -->
        <add key="All" value="(Aggregate source)" />
      </activePackageSource>
    </configuration>

If you want to add the feed to Visual Studio, please perform the following steps:

1) Open the Tools -> NuGet Package Manager -> Package Manager Settings menu in VS2019.
2) Click "Package Sources" in the settings list on the left side of the dialog.
3) Click the green plus sign in the upper right corner of the settings window. This should create a new entry in the list.
4) Set the "Name:" field in the lower portion of the options to "SVSComponents".
5) Set the "Source:" field to "https://sitecore.myget.org/F/sc-developer-collection/api/v3/index.json".
6) Click the "Update" button.
7) Click the OK button.

After setting up the feed, rebuilding the project should cause NuGet to pull the correct version of the package from MyGet and the project should build successfully.

#### Setting Build Properties
To set the build properties, right-click on the build project in the Solution 
Explorer and choose *Properties*. This will open a property page for the project
where the settings for building a package and/or pushing items at build time 
can be updated.

##### Building a package
To build a package, choose the *Serialized Items Package* tab and enable the 
build package checkbox. Once enabled, the developer can choose the modules to
include in the package.

![Build a Package](./Images/PackageProperties.png)

Packaging properties are configuration specific, so the developer can choose 
a different packaging options for each of their build configurations.

Enabling the packaging operation on this property page is the same as executing
the `sitecore package create` command at build time.

##### Pushing Items
If the developer wishes to push items to a Sitecore instance at build time, they
can use the *Serialized Items Push* settings tab to enable pushing items for a
specific build configuration. The developer can choose the modules to push
and choose to perform a "what-if" push operation. 

![Push Sitecore Items](./Images/PushProperties.png)

Enabling the push operation on this property page is the same as executing the 
`sitecore ser push` command at build time.