In the past, we have provided various tools to help our partners with different tasks, such as generating NetServer OSQL, Rows and archive provider code, for user-defined tables. This has been a considerable success for many, but has come in different shapes and sizes. Now we have consolidated those things into one tool; SuperOffice DevNet Toolbox.
The DevNet Toolbox is conceptually divided in two parts: code generation and continuous database operations. The code generation functionality is the same as it had been in the previous tools, allowing third-parties to generate NetServer Core code by reverse engineering third-party tables from the SuperOffice Database. The same is true for generating archive providers.
What’s different about this tooling is that there is no longer a NetServer dependency. You will not see any NetServer assemblies included or required to run this tool.
- NetServer Core Code
- Archive Providers
- Reverse engineer third-party tables to DictionaryStep
- Apply DictionaryStep
A majority of the functionality in this tool is made possible by leveraging the new Continuous Database (CD) assemblies.
SuperOffice.CD.DSL.dll contains all the types related to dictionary steps, all models involved, as well the commands that represent actions performed on third-party tables.
SuperOffice.CD.DSL.Implementation.dll contains all the functionality to perform the command actions, and is solely responsible for the new SDB file Import and Export functionality! This is not simply a reimplementation of the tools DBSetup uses for importing and exporting SDB files, this is the real McCoy, which DbSetup depends on for the same functionality. Where DbSetup.exe used to import and export .SDA files, the newer file format is .SDB.
While they are very similar, the change has more to do with the tooling used to generate the files than the files themselves. They are not backwards compatible, but not to worry! You can use this tool to backup an older version of a SuperOffice database, and restore it as necessary. In fact, this tool supports older versions as far back as SuperOffice v4.5!
Backup Database Dialog
The backup dialog only requires two pieces of information:
- The name of the backup file. The extension is not needed, and will automatically be added.
- The location where to save the backup file.
Restore Database Dialog
The restore dialog only requires file path of the .SDB backup file.
Whether the action is to perform a backup or restore, a progress dialog will appear and display the various steps involved with performing the operation.
Code Generation Dialog
The code generation dialog incorporates previous code generator capabilities, but now has it all in one! You can also opt to display SuperOffice tables, otherwise it will only show user-defined tables. Code generation options depend on the database version the tool is targeting.
When targeting SuperOffice v8.1, the UI will display code generation options for:
- Generate TableInfo and Rows
- Generate ArchiveProviders and Extenders
- Generate Dictionary Step Files
If the target database is SuperOffice v8 or earlier, only options #1 and #2 are displayed. When SuperOffice v.8.1 or greater, the Generate Dictionary Step File option appears.
The output code generation is a single Visual Studio .NET Solution file that contains two or more projects.
Where the generated code is saved is determined by the Destination Directory settings, and the name of the solution is determined by the specified Namespace.
When the Generate Code button is clicked, it will generate the following output:
- Solution file, references all generated projects.
- Two NetServer Projects
- Namespace + Lib: One project contains TableInfo, Rows and Archive Providers
- DemoConsole: One project contains console application that demonstrates how to use rows and archive providers.
- Two Continuous Database projects
- Namespace + CddLib: One project contains Dictionary Steps that describe user-defined tables.
- CddConsole: One project contains console application that demonstrates how to use Dictionary Steps to create user-defined tables into a database.
- Dependencies folder: contains SuperOffice Continuous Database assemblies.
When opened in Visual Studio, the different projects are organized into two different solution folders: Continuous Database and NetServer.
Continuous Database Development (CDD)
This concept is the result of researching a better way to create, maintain and extend a database schema over time. Many of the ideas that went into developing this concept are not original, and are an adaptation to an industry standard known as evolutionary database design, and is rooted in agile development methodologies.
A typical evolutionary workflow, as it pertains to DictionarySteps is shown below. An idea about something new is decided and a new database change is needed. Regardless if it requires a new table or field, data transformation, priming data, all or a combination thereof, the general process is the same and starts with a new DictionaryStep. Before a DictionaryStep is applied, and order to ensure there is a recoverable database, a backup step is best.
With a stable backup ready, it’s relatively safe to apply the DictionaryStep and begin to test the new changes. It is not uncommon to discover changes must be made, and now it’s time to update the DictionaryStep, restore the database, and then proceed to apply the DictionaryStep again.
How to create a DictionaryStep is written in great detail in this article “Continuous Database”, and will not be covered here. Please see that article for more information.
With the typical CDD workflow described, it’s time to explain how a DictionaryStep is applied.
Apply Dictionary Steps
There are two ways a DictionaryStep is applied to a database:
- Use the DevNet Toolbox application.
- Use the generated code example in the CddConsole application
Using code, it only takes a few lines to apply the dictionary steps towards a database. The requirements are:
- Create a connection to the database.
- Create an instance of the DatabaseManagement class to read the current database model.
- Use the StepLocator, which uses reflection, to locate all classes that have the Dictionary attribute.
- Use DatabaseManagerment to apply the discovered dictionary steps.
An alternative means to apply dictionary steps is to use the DevNet Toolbox application. This functionality is located on the Dictionary Steps screen, which is displayed by when the Apply Changes button is clicked.
When the dialog appears, select one of the two options for discovering dictionary steps:
- File: to scan one specific assembly.
- Folder: to scan a directory of assemblies.
Next, click the Scan for DictionarySteps button to discover all DictionarySteps and list them below. The list view will display the name, version and state of each Dictionary Steps, as well as whether it whether it has or has not been applied to the database.
Users can select dictionary steps that have not yet been applied to the database, and then click the Apply button to have them applied.
To be used as an aid for generating code and applying dictionary steps, the DevNet Toolbox is a GUI tool that rests on the shoulders of T4 templates. That’s where the true power lies. If you find yourself wishing to add things to the generated code, you have complete access to the files in the Templates directory, and can modify them as you wish.
This tool is not a supported SuperOffice product! This tool is made available only as a convenience for third-parties wishing to make their lives slightly easier generating code and applying DictionarySteps.
If you happen to witness any irregularities using this tool, please submit an email to email@example.com and we will try to assist as best we can.
This tool will likely end up as source code on our github repository so that you too can help make it even better!