Is this really the version you are looking for? Kentico Xperience 9 Documentation is no longer updated. Use the switcher in the header to choose your product version.
This page contains best practices and tips for developing projects in Visual Studio in combination with a Team Foundation Version Control or Git source control repository and the Kentico continuous integration solution. Many of the recommendations also apply generally when using continuous integration with any type of source control system.
For detailed instructions and additional information, please refer to the following resources:
When using a Team Foundation Version Control repository, developers need to set up their Kentico project and CIRepository folder within a Local workspace. Server workspaces are not supported.
See the Decide between using a local or a server workspace (opens in a new tab) article for more information about the workspace location types.
When you add a new object or delete an existing one in Kentico, the system creates or removes the corresponding XML files. You may need to perform additional actions to correctly track such changes, depending on the type of your source control repository:
Identifiers are values that the continuous integration solution uses to determine the names and locations of files representing objects in the CIRepository folder:
Avoid making changes to object identifiers if possible, particularly for objects that have a large number of child objects or affect the identity of other objects (such as sites). This also includes operations that change the identifier indirectly, for example moving a child object under a different parent.
When an object's identifier changes, the continuous integration solution deletes the file representing the object in the file system and creates a new one based on the new identifier. This causes a loss of the file's version history in the source control and makes it difficult to merge changes made to the same object by other developers.
When checking in (committing) changes to your source control, we strongly recommend including all detected file changes in the CIRepository folder. It may not be obvious which files correspond to specific changes made in the Kentico administration interface. Certain objects are represented by multiple files and changes may also affect related objects or relationships between objects.
To learn more about how objects are represented in the CIRepository folder, see the following pages:
Whenever you load a different version of any files in the CIRepository folder from your source control, you need to:
The restore operation ensures that your instance's database is consistent with the file system repository. If you continue working on the instance without performing the restore operation, changes to local data may overwrite the new versions of the files that you loaded from the source control.
You may encounter object conflicts when getting or checking in CIRepository files. Conflicts happen if your local folder and the opposing folder contain a file with the same name, but different content. File names are based on unique identifiers of objects (in most cases the object's code name).
For more information about the identifiers of CIRepository files, see the Changing object identifiers section and Continuous integration repository structure page.
Planned conflicts can occur if you need to create the same object across your entire development environment. For example, multiple developers may create a web part category with the same name when starting development of custom web parts. Even if the objects have completely identical values for all configurable properties, a conflict will occur during synchronization, because the object's GUID (globally unique identifier) value is different for each developer.
The best solution is to have one developer create the object and check in the resulting XML files to the central source control. Other developers then load the XML files from the source control and restore the object to their local database. This approach completely avoids object conflicts and file merging.
If you cannot avoid an object conflict and need to merge XML files, always use the GUID value that is already checked in to the source control and replace your local GUID. Do NOT push your local GUID values to the source control – this could cause conflicts for all other developers in your environment.
Note:
Unplanned conflicts occur if developers unintentionally create different objects of the same type with matching identifiers (typically code names) and then synchronize through the source control. In such cases, you need to contact the developer who checked in the conflicting XML file and one of you must delete and recreate the object with a different identifier (or rename the identifier values). We strongly recommend changing the local object that is not checked in to the source control yet, which prevents potential conflicts for other developers.
We do not recommend using the Visual Studio Undo action for changes that create new files. Undoing changes may lead to inconsistencies between the state of the file system repository and the database. You can instead delete the given object in the Kentico interface, which also makes the corresponding changes in the file system.
If you undo a delete or modify operation and revert an XML file to its previous state, you then need to restore the objects into the database to reverse the object changes in Kentico.
For Kentico projects installed as a web application, the App_Data/CIRepository folder and its file content does not need to be included in the CMSApp project. Note that the folder still must be mapped to your source control (we strongly recommend having the entire Kentico project folder mapped).