Umbraco DictionaryBuilder Extension

DictionaryBuilder is an unofficial Visual Studio extension for generating a strongly typed dictionary service and models for Umbraco.

Compatibility

[Visual Studio Versions:]

• [x] Community Edition 2019 V16.9.2

[Umbraco Versions:]

• [x] 8.11.1

* The extension may work with other versions of Visual Studio and Umbraco but has not been officially tested meaning that undesired results may occur. This list will be maintained as more testing is undertaken.

Getting Started

[Marketplace]

1. Simply download and install the extension.

[Github]

1. Clone the repository.
2. Open in Visual Studio.
3. Build the solution.
4. In Windows Explorer, navigate to \DictionaryBuilder\bin\{Debug/Release} in your solution's folder.
5. Locate and install DictionaryBuilder.vsix.

Configuring Options

1. Extension options can be configured in Visual Studio by navigating to:
   Tools > Options > Umbraco > DictionaryBuilder Options:
   
2. A complete list of user preferences with the default option values and example SQL connection data can be viewed below (more information about each setting is shown below the property grid when highlighting an option):
   
3. The options file is saved in the same location as the solution using the naming convention:
   <solution name>.UmbracoDictionary.user. SQL passwords are encrypted using a System Key or Common Key as defined by the Encryption Method setting (see above screenshot) allowing you to commit this file into your repository.
   
4. The contents of the file is serialised using XML e.g.
   

(Re)building Dictionary

1. An Umbraco Dictionary context menu is available when right clicking on any project within the Solution Explorer. Click on the Rebuild Dictionary command to export the latest version of the dictionary models along with a service, extension classes and interfaces etc:
   
2. The exported files will be written to the paths defined in the extension options e.g:
   
3. Progress is written to the output window along with any error messages:
   

Example Source Code

1. An example of the source code generated by the DictionaryBuilder can be found in this repository folder: Example Code.
2. The example code is based on the following Umbraco dictionary structure which contains event messages to alert a content editor if they attempt to delete a node where this action has been disabled for their access level:
   
3. When the content editor attempts to delete a configuration node e.g:
   
4. An alert is shown to the content editor. In this case the alert message is retrieved from the Umbraco dictionary using the exported DictionaryBuilder service and strongly typed class models:
   
5. Example source code usage (for the full example see the commented source code in ExampleUsage.cs):
   

Synchronise Database Tables

1. It is possible to synchronise the dictionary database tables between development, staging and live deployments.
   IMPORTANT: It is strongly recommended to backup the destination database before doing so. The language table is not synchronised and it is therefore suggested that you check that the languages and id's match between deployments - otherwise dictionary values may be assigned to the wrong language after synchronising:
   
2. You will be prompted to confirm your selection before the synchronisation begins:
   
3. Progress is written to the output window along with any error messages: