Scaffolding Services and Controllers
This document was last updated against SnapDevelop 2019 R2 Beta.
Scaffolding is a technique for creating database-backed applications. It can be used to easily and quickly generate services and controllers in a project based on existing items and thus enjoys a variety of benefits:
Reduced repetitive work;
Enhanced development efficiency (a developer doesn’t have to build a project from scratch).
Currently SnapDevelop supports you to scaffold controllers or services based on .NET DataStore or SqlModelMapper models. This tutorial walks you through the process of scaffolding services or controllers in projects in SnapDevelop. You will learn how to access the scaffolding functionality, configure various scaffolding settings, and then generate scaffolded items.
Accessing Scaffolding Functionality
The Scaffold context menu is available at all file/folder nodes in a project. You need to ensure by yourself that you choose the appropriate items (models or services) to scaffold on. Chances are that you can use the wrong option to generate scaffolded items (service and/or controller) in the target project but such items would fail to work.
There are four scaffolding options under Scaffolding: Controller from Service (DataStore), Service and Controller from Model (DataStore), Controller from Service (SqlModelMapper), and Service and Controller from Model (SqlModelMapper). The following table explains what each option represents.
|Controller from Service (DataStore)||Indicates that you can generate controllers from services that operate on .NET DataStore models.|
|Service and Controller from Model (DataStore)||Indicates that you can generate services and controllers that operate on .NET DataStore models.|
|Controller from Service (SqlModelMapper)||Indicates that you can generate controllers from services that operate on SqlModelMapper models.|
|Service and Controller from Model (SqlModelMapper)||Indicates that you can generate services and controllers that operate on SqlModelMapper models.|
Specifying Scaffolding Templates
Selecting Template for Generating Service(s)
If you want to generate services via the scaffolding feature, make sure to select the Generate Service(s) check box. You should then select a template from the Template drop-down list. To understand the template options, refer to Managing Scaffolding Templates.
Selecting Template for Generating Controller(s)
If you want to generate controllers via the scaffolding feature, make sure to select the Generate Controller(s) check box. You should then select a template from the Template drop-down list. To understand the template options, refer to Managing Scaffolding Templates.
Managing Scaffolding Templates
Understanding System Scaffolding Templates
Scaffolding templates are essential for the scaffolding feature. There are a number of system scaffolding templates to choose from in the current version.
|.NET DataStore related|
|Repository_Pattern_Service_DataStore_for_PBClient||Generates services that perform PB-style DataStore operations (including Retrieve and Update) on .NET DataStore models.|
|Repository_Pattern_Service_DataStore_for_NonPBClient||Generates services that perform standard C# operations (including Retrieve , Create, RetrieveOne, Update and Delete) on .NET DataStore models.|
|Repository_Pattern_Service_DataStore_for_AnyClient||Generates services that perform both PB-style DataStore operations and standard C# operations on .NET DataStore models.|
|Controller _based_on_service_DataStore||Generates controllers based on services that perform PB-style DataStore operations and/or standard C# operations on .NET DataStore models.|
|Repository_Pattern_Service_SqlModelMapper||Generates services that perform standard C# operations on SqlModelMapper models.|
|Controller_based_on_service_SqlModelMapper||Generates controllers based on services that perform standard C# operations on SqlModelMapper models.|
The source files of the templates are stored in the SnapDevelop installation directory: SnapDevelop 2019 R2\modules\SnapDevelop.Scaffolding\Templates.
Viewing and Editing Scaffolding Templates
Sometimes you may want to view or edit a particular scaffolding template. You just need to find the location of the template and then view and edit it.
For example, the Controller folder in the directory SnapDevelop 2019 R2\modules\SnapDevelop.Scaffolding\Templates\Controller contains the source file of a template.
Each *.template file in the folder refers to the configuration of a template. For example, ServiceToController.template.
In the file:
ID: The template ID. It must be unique for each template.
Name: The name option to represent the template in the Scaffolding window and Scaffolding option settings.
Template Items: The actual template to be used. Note that the file and folder are specified with the relative path of the current template directory.
Package: The NuGet package that must be installed for the item generated based on the template to work properly.
ParsingRules: The parsing rules used for parsing the source items.
(In controller templates only) ParentTemplates: The IDs of the associated service templates. When the ID of a service template is specified for a controller template, after you have used the service template for scaffolding services, you will be able to select the controller template for scaffolding controllers based on the services.
(In service templates only) SuperClass Related Settings (such as IsEnableSuperClass, DefaultSuperClassName): Defines whether to generate base class for the target services, and what are the default base class name, and templates to use. Note that you shall create the corresponding base class templates in the template folder and also the template\Impl folder.
It is recommended that you do not change the configuration and design of system templates. You may add a custom scaffolding template based on a system template, and then edit its configuration or design according to what you want to implement with the template.
Adding Scaffolding Templates
If you think that the existing templates cannot meet your needs, you can create new templates on your own. If you want to add a new scaffolding template, it is recommended that you create it in the Scaffolding Templates folder in the default directory C:\Users\[appeon]\.sd\1.0.0 (you may need to replace [appeon] with your user name). You may copy the configuration and source file of an existing template and then build your own based on it.
Specifying Scaffolding Source and Target Items
The system templates use default parsing rules. If you have selected a user-defined template, you can configure the parsing rules before you specify the scaffolding source. The parsing rules filter out what source items you can select from.
Configuring Parsing Rules
Select Parsing Rules to go to the Parsing Rules configuration page.
When Scaffolding Based on a User-Defined Template
You need to select a user-defined scaffolding template first, and then specify classes and class attributes to be parsed. The configured parsing rule will only work for the currently selected template. You can specify different parsing rules for different templates.
Note: You can only view, but not edit, the parsing rules of system templates.
Specify Classes and Class Attributes to be Parsed
After you have selected the scaffolding template, you need to specify classes and class attributes to be parsed.
Get classes by keyword means that the source items to be parsed shall be Interface or Class.
Class(es)/Class attribute(s): If you want to parse all classes and/or class attributes in your program, you can select the Class check box and then the Class attribute(s) check box, and leave the input box empty. If you just want to parse some of the classes and/or class attributes in your program, you can select the Class check box and then the Class attribute(s) check box, and specify the class(es)/class attribute(s) in the input box. If you select neither the Class(es) nor the Class attribute(s) check box, no class or class attribute will be parsed.
Selecting Scaffolding Source and Target Items
After you have properly configured the parsing rules, all the source items (be it model or service) will be filtered out and listed. You can then select the ones you want to scaffold on.
Each selected source item has a corresponding target item, which is the item to generate based on the source item. Each target item (be it service or controller) has a default name. You can click on the default name to modify it if you want to name the target item differently.
Generating Scaffolded Items
You can configure the Generate Scaffolded Items settings so as to generate the scaffolded items in the intended way.
Settings for Target Service(s)
If you want to generate a service in a project, you need to specify the target project, the particular subfolder that accommodates the generated service, the namespace in the Service.cs file in the generated Service folder, the DataContext on which your program depends, as well as the base class.
Selects from the dropdown list the project in which you want to generate the target service.
Specifies the folder that belongs to the selected project and in which you want to generate the target service. You can select a folder from the dropdown list or choose New Folder to create a new folder.
Designates the namespace in the target service.
Specifies the data source that the target service will use. You can select from the dropdown list or choose New DataContext to create a new one. After you create a new DataContext, you should click the Refresh icon to update the dropdown list with the newly created DataContext.
Specifies whether to generate a base class for the target service. You can select None to skip generating a base class, or specify the base class to use, or select New Base Class to create a new base class. As indicated in the field name, if you specify a base class that already exists in the current project, the base class can be directly used for the target services; if you specify a base class that does not exist yet, the base class will first be created, and then used for the target services.
The template used for creating a base class is stored in the same folder as the service template. For more information, see Viewing and Editing Scaffolding Templates.
Settings for Target Controller(s)
If you want to generate a controller in a project, you need to specify the target project, the particular folder in the target project, as well as the namespace in the Controller.cs file in the generated Controller folder.
Selects from the dropdown list the project in which you want to generate the target controller.
Specifies the folder that belongs to the selected project and in which you want to generate the target controller. You can select from the dropdown list or choose New Folder to create a new folder.
Designates the namespace in the target controller.
Setting How to Add Method Attributes
This setting allows you to define a set of method attributes for the methods in the controller. For each listed method attribute, specify the method name to which you want to add the method attribute.
Note that if a method is not covered in the setting, scaffolding will decide which method attribute to add for it by checking the parameter of the method:
If the method has no parameter, the [HttpGet] method attribute will be added to it by default;
If the method contains one or more parameters with a non-basic C# type, the [HttpPost] method attribute will be added to it by default.
If Files Already Exist
This setting determines what to do if the files to add for the scaffolded items already exist in the target folder. You can select Overwrite to replace the existing files with the newly generated files, or Skip to retain the existing files.
Executing the Scaffolding Operation
When you have properly configured scaffolding settings, then you can click Generate to export the scaffolded items to the designated folder in the target project, as specified in Generating Scaffolded Items.
During the scaffolding process, you may be prompted whether to install the NuGet package required by the scaffolded item(s). You can select to install it right away, or install it manually later.
After the scaffolding process is complete, you can check the corresponding folder in the target project to see if the scaffolded items are generated successfully.