This section details some core design concepts that will help you get started with your first design.
Designs and Design Versions
Design is iterative, and some designs will evolve through multiple design versions. Versions of the same design are related together. Therefore, when opening a design version, you first choose the design, then the version of the design on which you wish to work.
Versioning
Versioning of designs is automatic. When creating a new design, it will be version 1.0. Each time you create a new version of a design, you choose only whether it is a minor or major increment, and the new version number is calculated for you.
It is easy to get overly caught up in versioning of designs. Some developers worry that a design should reach version 1.0 only when the design is considered complete. However, we recommend you do not concern yourself with that, as it can lead to unnecessary time and focus lost on processes with little or no actual benefit, such as renumbering versions when things change.
Change is natural, and something we need to build into our software and our development processes, so we do not attempt to place unnecessary focus on the meaning of version numbers for your designs. You can choose to identify a new design version as a major variation from what went before, or as a minor enhancement, as this is helpful to people who refer to your designs. Other than that, leave the rest to the tool.
Artefacts
Artefact is the general term used to refer to the items that you are designing. Think of artefacts as the primary output of your design process. An artefact may be anything you wish to create in your software, irrespective of what layer it is to reside within, or what its purpose. You might create an artefact to represent a class, a UI component, a data storage object (such as a table in a relational database or a document in a NoSQL data store) or even a script or data file to initialise a data store.
An artefact can be associated with a data structure. Basing an artefact on a data structure allows you to use the properties of the data structure to generate the artefact. This can be as simple as using the name of the data structure as a part of the name of the artefact, or more complex, such as using the fields of the data structure to create properties on the artefact (such as the properties of a class, or the fields of a table.)
An artefact is associated with an artefact template. This template is used to help define what the artefact is or does, and can be used during the code generation phase to create an output on disk.
Artefacts do not have to result in code generation. A property of the artefact is what happens during generation. By default, an artefact is generated once; it remembers when it was generated and does not regenerate. However, you can choose other options. See the Code Generation page for more details.
Artefact Hierarchy
Artefacts can be related in a hierarchy, so the artefact screens show artefacts in a tree structure. Artefact types help define the hierarchy.
Managing a hierarchy of artefacts is useful because artefacts can inherit properties from their parents. This allows us to enter data against a single artefact that applies to all of its children (such as locations on disk, and namespaces.)
Artefact Types
There are 4 primary types of artefact, which represent the primary levels of most software systems.
- Solution. A solution is expected to act as a container for other artefacts, especially projects.
- Project. A project is expected to act as a container for other artefacts, especially folders and items.
- Folder. A folder is a container for items, or other folders.
- Item. An item is not a container; we do not expect items to be children of items.
You do not have to have all of the levels represented in your design. However, we have found it useful to split templates into these subcategories to make them easier to find. Furthermore, it is very useful to be able to cascade properties from parent artefacts to their children, such as namespaces, disk locations and so on. Therefore, you are likely to want to try to create artefacts in a hierarchical structure, and can consider these levels to be a recommendation.
Levels are not intended to be interchangeable. The software is written assuming that solutions are the top level container, and contains projects. Projects are intended to contain folders and/or items. This restriction helps us to surface only the most useful of things in some of the screens.
It is worth bearing in mind that some development systems make it appear that item-type artefacts are children of other item-type artefacts. However, this is usually not the case in reality. Take as an example Microsoft Visual Studio, which seems to show that a file called Index.razor.cs is a child of Index.razor. However, in terms of the file system, you will see that these items actually sit side by side; the grouping is logical rather than physical. For that reason, we do not currently allow items to be containers for other items.
Data Structures
A data structure is a collection of data items that are logically associated. You can use a data structure to represent a data storage object (such as a table) but it is not a requirement that a data structure is persisted. You are in complete control. Create a data structure for any fields that you want to use to define an artefact.
As an example, you could choose to create a data structure for all of the fields that will be stored in a table. A second data structure might represent a subset of those fields that are used only in certain circumstances, such as those of interest in a lightweight read-only object, and then create an artefact based upon that subset of fields.
You can create as many data structures as you wish.