|
1 | 1 | # Development Guide |
2 | 2 |
|
3 | | - |
| 3 | +In this document, we will introduce **ASP.NET Zero Power Tools** and explain it. ASP.NET Zero Power Tools minimizes the effort for creating CRUD pages. It generates all the layers from the database to the user interface by just defining an entity. |
4 | 4 |
|
5 | | -## Introduction |
6 | | - |
7 | | -In this document, we will introduce **ASP.NET Zero Power Tools** and explain it. This tool is developed to minimize the effort of creating a new CRUD page. It creates all the related layers from the database to the user interface by just defining an entity. This tool supports ASP.NET Zero v5.0.0 and later versions. |
8 | | - |
9 | | -## Download And Install |
10 | | - |
11 | | - If your project version is 5.1.0+, all you have to do is just install the **ASP.NET Zero Power Tools** extension on Visual Studio from [marketplace](https://marketplace.visualstudio.com/items?itemName=Volosoft.AspNetZeroPowerTools) or Extension and Updates. |
12 | | - |
13 | | - |
14 | | - |
15 | | -**The Rad tool may require the EF Core tool during database migration. Please refer to its documentation to install it properly.** |
16 | | - |
17 | | -https://docs.microsoft.com/en-us/ef/core/miscellaneous/cli/dotnet |
| 5 | +> ASP.NET Zero Power Tools supports ASP.NET Zero v5.0.0 and above versions. |
18 | 6 |
|
19 | 7 | ## How To Use It? |
20 | 8 |
|
21 | | - The extension can be found inside the **Tools** menu (Tools -> Asp.Net Zero -> Create An Entity). When you run it, you will see the interface for creating an entity. After carefully filling out the fields, press the **Generate** button to start the code generation process. |
22 | | - |
23 | | - |
| 9 | +You can use ASP.NET Zero Power Tools in two ways: |
24 | 10 |
|
25 | | - A simple console will appear and give you information about the process. If there is no warning or failure, run your project to see the results. If you don't see the new page on UI, grant yourself the required **permissions** in the application. |
| 11 | +1. as a Visual Studio Extension |
| 12 | +2. Using its DLL files directly with a command line. |
26 | 13 |
|
27 | | -Warning: If you are working on ASP.NET Core & Angular template, after generating the entity via Power Tools, run your ***.Web.Host** project and then run "**./angular/nswag/refresh.bat**" to update **service-proxies.ts**. |
28 | | - |
29 | | - Warning: Be sure that you have saved your work before running this tool since it will add new files and modify some of the existing files. We strongly recommend using a source control system (like Git). Otherwise, backup your project. |
| 14 | +Visual Studio Extension is available for Windows version of Visual Studio. Mac and Linux users can use DLL of ASP.NET Zero Power Tools to generate CRUD pages. |
30 | 15 |
|
31 | 16 | ## How It Works? |
32 | 17 |
|
33 | | -DLLs (that are inside the folder mentioned above) do all the work. The extension is just a user interface. This design is required, otherwise it would only be available for Visual Studio Windows users. However, since the tool is built on .NET Core platform, **Mac** or **Linux** users can safely use the tool. |
34 | | - |
35 | | -On Mac and Linux, you have to manually do some of the work that is done by the extension. This involves just creating a short and basic[ JSON file](https://aspnetzero.com/Documents/Development-Guide-Rad-Tool-Mac-Linux) as input. |
| 18 | +DLLs (that are inside the ```aspnet-core\AspNetZeroRadTool``` folder in your solution) do all the work. The extension is just a user interface. Since the tool is built with .NET Core, **Mac** or **Linux** users can safely use it without the user interface. |
36 | 19 |
|
37 | | -## Navigation Properties |
| 20 | +Using ASP.NET Zero Power Tools on Mac and Linux requires a bit more effort. You have to create a [ JSON file](https://aspnetzero.com/Documents/Development-Guide-Rad-Tool-Mac-Linux) as input for code generation manually. For using ASP.NET Zero Power Power Tools in Mac or Linux, please check [Development Guide(Mac/Linux) document](Development-Guide-Rad-Tool-Mac-Linux). |
38 | 21 |
|
39 | | -A navigation property is a type of property on an entity that allows for navigation from one end of an association to the other end. Unlike other properties, navigation properties do not carry data. |
| 22 | +Visual Studio extension of ASP.NET Zero Power Tools also uses this DLL file for code generation. |
40 | 23 |
|
41 | | -Navigation properties provide a way to navigate an association between two entity types. Every object can have a navigation property for every relationship in which it participates. In ASP.NET Zero, a navigation property allows you create a button on the data table, where you can pick a record from a look up table. |
| 24 | +## Edit Pre-defined Templates |
42 | 25 |
|
43 | | -Power Tools allow you to create a navigation property for only **1-to-many (1:N)** relationships. |
| 26 | +Power Tools uses text templates for code generation, and these templates are located inside ```/AspNetZeroRadTool/FileTemplates``` directory in your project's root directory. Each template is split into three files: |
44 | 27 |
|
45 | | -In this scenario there are multiple records from one entity associated with a single record from another entity. This means you have a parent (or primary) entity and many related (or child) entities. |
| 28 | +* **MainTemplate.txt**: Power Tools uses this template for main code generation. |
| 29 | +* **PartialTemplates.txt**: Power Tools renders some placeholders in MainTemplate.txt conditionally. These conditional templates are stored in PartialTemplates.txt. |
| 30 | +* **TemplateInfo.txt**: Stores information about the template like path and condition. |
46 | 31 |
|
47 | | -- `Car` entity (1) is associated to `Producer` entity (N). |
48 | | -- `Car` entity (1) is associated to `Country` entity (N). |
| 32 | +If you want to edit any file, copy it in the same directory and change it's an extension to ```.custom.txt``` from ```.txt```. For example, you can create ```MainTemplate.custom.txt``` to override ```MainTemplate.txt``` in the same directory. Please don't make any changes to the original templates. |
49 | 33 |
|
50 | | -*Currently there's no support for many-to-1 (N:1) or many-to-many (N:N) relationships!* |
| 34 | +## Create A New Template |
51 | 35 |
|
52 | | -A foreign keys is automatically being created for each navigation property. |
| 36 | +You can also create new templates for code generation. Power Tools will generate new files based on your new templates during code generation. To create a new template, do the same process as editing a pre-defined template. |
53 | 37 |
|
54 | | -The diagram below shows a conceptual model with three entity types: `Car`, `Producer` and `Country`. |
55 | | -Navigation properties are `Producer` and `Country` that are defined on the `Car` entity. |
| 38 | +Power Tools discovers templates in the ```/FileTemplates``` directory every time it is run. So, restarting Power Tools will find your newly created templates. |
56 | 39 |
|
57 | | - |
58 | | - |
59 | | - |
60 | | - |
61 | | -## How To Edit Pre-defined Templates Or Create A New Template? |
62 | | - |
63 | | - The templates are inside "/AspNetZeroRadTool/FileTemplates" directory in your project's root directory. Every template is split into three files: "MainTemplate.txt", "PartialTemplates.txt" and "TemplateInfo.txt". If you want to edit any file, just copy it in same directory and change it's extension to ".custom.txt" from ".txt". For example, you can create "MainTemplate.custom.txt" to override "MainTemplate.txt" in same directory. Please don't make any changes to the original templates. |
64 | | - |
65 | | -To create a new template, do the same process as editing a pre-defined template. The tool doesn't know any info about templates and discovers them in the "/FileTemplates" directory every time it is run. This means your new template will be processed like the pre-defined ones. (".custom" extension is not needed for new templates.) |
66 | | - |
67 | | - You can report your issues or ask questions on [GitHub](https://github.com/aspnetzero/aspnet-zero-core) or [support.aspnetzero.com](https://support.aspnetzero.com). |
68 | | - |
69 | | -## How To Change Destination Path Of New Files? |
| 40 | +## Change Destination Path Of New Files |
70 | 41 |
|
71 | 42 | To change the destination path of a template, find the template folder of it in "AspNetZeroRadTool/FileTemplates" directory and edit the content of **TemplateInfo.txt** file. |
72 | 43 |
|
73 | 44 | Also, if you have moved a file that is going to be modified during rad tool generation, you can modify "AspNetZeroRadTool/**config.json**" file and set the new path of this file. |
74 | 45 |
|
75 | | - |
76 | 46 | ## Generated Files |
77 | 47 |
|
78 | | - Here is the full list of the files that are created or modified by the tool, if you give a basic "Cars" entity as input. |
| 48 | +Here is the full list of the files that are created or modified by the tool, if you give a basic "Cars" entity as input. |
79 | 49 |
|
80 | 50 | ### Server Side |
81 | 51 |
|
@@ -151,9 +121,6 @@ Also, if you have moved a file that is going to be modified during rad tool gene |
151 | 121 | - (AppArea)PageNames.cs |
152 | 122 |
|
153 | 123 | > Note that lookup files are being created per foreign key. |
154 | | -> |
155 | | -
|
156 | | - |
157 | 124 |
|
158 | 125 | ## Final Result |
159 | 126 |
|
|
0 commit comments