Skip to content

Commit 9f62979

Browse files
ismcagdasismcagdas
authored
Merge pull request #272 from aspnetzero/pr/4299
Update power tools documents
2 parents ec85661 + 6554199 commit 9f62979

32 files changed

+1019
-54
lines changed

‎docs/en/How-To-Create-Edit-Power-Tools-Templates.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# How to Create & Edit Power Tools Templates
2+
3+
Power Tools uses text templates for code generation, and these templates are located inside `/AspNetZeroRadTool/FileTemplates` directory in your project's root directory.
4+
5+
**MainTemplate.txt:** Power Tools uses this template for main code generation.
6+
**PartialTemplates.txt:** Power Tools renders some placeholders in `MainTemplate.txt` conditionally. These conditional templates are stored in `PartialTemplates.txt`.
7+
**TemplateInfo.txt:** Stores information about the template like path and condition.
8+
9+
*Folder structure*
10+
11+
![Folder structure](images/power-tools-folder-structure.png)
12+
13+
## Edit Pre-defined Templates
14+
15+
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.
16+
17+
![Edit Template](images/power-tools-edit-template.png)
18+
19+
## Create New Templates
20+
21+
To create new templates, simply add a new file to the `FileTemplates` directory. You can use the existing templates as a reference. For guidance on how templates function and how to use placeholders, please refer to the documentation provided at [Understanding Power Tools Templates](power-tools-understanding-power-tools-templates.md).
22+
23+
Power Tools discovers templates in the `FileTemplates` directory every time it is run. So, restarting Power Tools will find your newly created templates.
24+
25+
## Change Destination Path Of New Files
26+
27+
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.

‎docs/en/Power-Tools-Configuration.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# ASP.NET ZERO Power Tools Configuration
2+
3+
The `config.json` file provided in your ASP.NET Zero project contains essential file paths and configuration settings used by the Power Tools. While the Power Tools **typically do not require manual configuration**, there are instances where you **might need** to modify the configuration to adapt to changes in file locations or project structure. In such cases, updating the `config.json` becomes necessary to ensure the Power Tools function correctly.
4+
5+
Here are some key points to consider when modifying the `config.json` file:
6+
7+
1. **Company Name and Project Name:** You may need to update the **CompanyName** and **ProjectName** fields with appropriate values to match your project's details.
8+
9+
2. **Project Type and Version:** Set the **ProjectType** to **Angular** or **Mvc** and specify the appropriate **ProjectVersion**.
10+
11+
3. **Application Area Name:** Ensure the **ApplicationAreaName** matches the relevant area name in your project (used only for MVC projects).
12+
13+
4. **License Code:** Replace **[YOURLICENSECODE]** with the valid license code for your project.
14+
15+
5. **File Locations:** This section contains various file paths used by the Power Tools for different functionalities. If you change any of these file locations in your project, you need to update the corresponding paths in the `config.json` file accordingly. For example, if you move the DbContext file to a different location, update the **DbContext** path to reflect the new location.
16+
17+
6. **Base Paths:** The `config.json` file uses base paths (e.g., `AngularSrcPath`, `AngularMergedSrcPath`, `CoreSrcPath`) to build the final file paths. Make sure to set these base paths correctly according to your project's structure.
18+
19+
7. **Angular Project Type:** Depending on whether your Angular project is separate from server side Host project or merged with server side Host project, use the appropriate base path (`AngularSrcPath` for split projects or `AngularMergedSrcPath` for merged projects) for the Angular-related file paths.
20+
21+
Always **double-check** the **changes** you make in the config.json file to avoid any errors or inconsistencies. It's crucial to keep the configuration updated to ensure the Power Tools can accurately locate the required files and function as expected with your project's structure.
22+
23+
*Example config.json*
24+
```json
25+
{
26+
"CompanyName": "",
27+
"ProjectName": "[YOURPROJECTNAME]",
28+
"ProjectType": "Angular",
29+
"ProjectVersion": "v8.0.0",
30+
"ApplicationAreaName": "App",
31+
"LicenseCode": "[YOURLICENSECODE]",
32+
"AngularSrcPath": "\\..\\..\\angular\\src\\",
33+
"AngularMergedSrcPath": "\\..\\src\\{{Namespace_Here}}.Web.Host\\src\\",
34+
"CoreSrcPath": "\\..\\src\\",
35+
"FormatGeneratedFiles": true,
36+
"FileLocations": {
37+
"DbContext": "{{Namespace_Here}}.EntityFrameworkCore\\EntityFrameworkCore\\{{Project_Name_Here}}DbContext.cs",
38+
"CustomDtoMapper": "{{Namespace_Here}}.Application\\CustomDtoMapper.cs",
39+
"AppAuthorizationProvider": "{{Namespace_Here}}.Core\\Authorization\\AppAuthorizationProvider.cs",
40+
"EntityHistoryHelper": "{{Namespace_Here}}.Core\\EntityHistory\\EntityHistoryHelper.cs",
41+
"AppPermissions": "{{Namespace_Here}}.Core\\Authorization\\AppPermissions.cs",
42+
"LocalizationFile": "{{Namespace_Here}}.Core\\Localization\\{{Project_Name_Here}}\\{{Project_Name_Here}}.xml",
43+
"EntityFrameWorkProjectFolder": "{{Namespace_Here}}.EntityFrameworkCore",
44+
"Mvc": {
45+
"AppNavigationProvider": "{{Namespace_Here}}.Web.Mvc\\Areas\\{{App_Area_Name_Here}}\\Startup\\{{App_Area_Name_Here}}NavigationProvider.cs",
46+
"AppPageNames": "{{Namespace_Here}}.Web.Mvc\\Areas\\{{App_Area_Name_Here}}\\Startup\\{{App_Area_Name_Here}}PageNames.cs",
47+
"BundleConfig": "{{Namespace_Here}}.Web.Mvc\\bundles.json"
48+
},
49+
"Angular": {
50+
"AppNavigationService": "app\\shared\\layout\\nav\\app-navigation.service.ts",
51+
"ServiceProxies": "shared\\service-proxies\\service-proxy.module.ts",
52+
"Module": "app\\{{menu_Position_Here}}\\{{menu_Position_Here}}.module.ts",
53+
"RoutingModule": "app\\{{menu_Position_Here}}\\{{menu_Position_Here}}-routing.module.ts"
54+
}
55+
}
56+
}
57+
```

‎docs/en/Power-Tools-Creating-Entity-Json-File-Manually.md‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
# Creating Entity Json File Manually
2+
3+
In this document, we will explain how to use **ASP.NET Zero Power Tools** without the Visual Studio extension.
4+
5+
Purpose of the **ASP.NET Zero Power Tools VS Extension** is to create an input file. So, in order to use it without extension, input file needs to be created manually.
6+
7+
## Creating Input File
8+
9+
For creating JSON file manually, you need to learn fields of the JSON file (configuration for entity).
10+
11+
Properties are written as an array in JSON file. Add an object to that array for every property of your entity. There will be some unnecessary fields depending on property type. For example, you don't have to set regular expression for a numeric property or don't have to set range for a string.
12+
13+
You have to fill the fields of the JSON file for your entity. However, some of the fields must match our constants.
14+
15+
A property should be one of those types:
16+
17+
* bool
18+
* byte
19+
* short
20+
* DateTime
21+
* decimal
22+
* double
23+
* Guid
24+
* int
25+
* long
26+
* string
27+
28+
or one of the ENUMs you declared in **EnumDefinitions**.
29+
30+
You can find specification of the JSON file fields in the table below;
31+
32+
## Fields Table
33+
34+
| Name | Description |
35+
| --- | --- |
36+
| IsRegenerate | Set `true` if you have generated this entity before. |
37+
| MenuPosition | `main` or `admin` |
38+
| RelativeNamespace | Namespace of your entity (not including project's namespace) |
39+
| EntityName | Entity Name |
40+
| EntityNamePlural | Entity Name Plural |
41+
| TableName | Database Table Name (might be same with plural name) |
42+
| PrimaryKeyType | Type of primay key. <br />Can be `int`, `long`, `string`, `Guid` |
43+
| BaseClass | Base class of your entity. <br />Can be `Entity`, `AuditedEntity`, `CreationAuditedEntity`, `FullAuditedEntity` |
44+
| EntityHistory | Set `true` to track history of this entity. |
45+
| AutoMigration | `true` add-migration automatically, false do not add migration (you need to add migration manually) |
46+
| UpdateDatabase | `true` update-database automatically, false do not update-database (you need to update-database manually) |
47+
| CreateUserInterface | `true` creates/modifies ui layer files |
48+
| CreateViewOnly | `true` creates a view-only modal in actions button in table of your entity in ui |
49+
| CreateExcelExport | `true` adds excel report button in ui |
50+
| IsNonModalCRUDPage | `true` creates non-modal pages. |
51+
| PagePermission | Multitenancy<br />`"PagePermission":{"Host": [ISHOSTALLOWED],"Tenant":[ISTENANTALLOWED]}` |
52+
| Properties | Properties of your entity. See **Properties Table** for more. |
53+
| NavigationProperties | Navigation properties of your entity. See **NavigationProperties Table** for more. |
54+
| EnumDefinitions | Enum definitions you use on your entity. See **EnumDefinitions Table** for more. |
55+
56+
## Properties Table(Array):
57+
58+
| Name | Description |
59+
| --- | --- |
60+
| Name | Property Name |
61+
| Type | Type of property. <br />Can be string, bool, byte, short, DateTime, decimal, double, Guid, int, long, enum |
62+
| MaxLength | If type is string max length of string |
63+
| MinLength | If type is string min length of string |
64+
| Range | If type can have range value range of property<br />"Range": {"IsRangeSet": [ISRANGESET],"MinimumValue": [MINVAL],"MaximumValue": [MAXVAL]} |
65+
| Required | Is property required |
66+
| Nullable | Is property nullable |
67+
| Regex | specifies the regex that this property should match |
68+
| UserInterface | Will this property be listed, have a filter and editable in ui?<br />"UserInterface": {"List": true,"AdvancedFilter": true,"CreateOrUpdate": true} |
69+
70+
## NavigationProperties Table(Array):
71+
72+
| Name | Description |
73+
| --- | --- |
74+
| Namespace | Namespace of entity |
75+
| ForeignEntityName | Foreign Entity Name |
76+
| ForeignEntityNamePlural | Foreign Entity Name Plural |
77+
| IdType | Type of Foreign Key. See Entity -> PrimaryKeyType |
78+
| IsNullable | Is nullable |
79+
| PropertyName | Property name (Property name for that entity which will store Foreign Key) |
80+
| DisplayPropertyName | Property name of foreign entity. It will be displayed by that property on pages. |
81+
| DuplicationNumber | If you have two navigation property that navigates to same foreign entity, number them starting from 1. If not, just skip this. |
82+
| RelationType | single is the only option. |
83+
84+
## EnumDefinitions Table:
85+
86+
| Name | Description |
87+
| --- | --- |
88+
| Name | Name |
89+
| Namespace | Namespace |
90+
| EnumProperties | Properties <br />"EnumProperties":[{"Name":"[PROPERYNAME]","Value":[PROPERYVALUE]}] |
91+
92+
## Example JSON Input
93+
94+
```json
95+
{
96+
"IsRegenerate": false,
97+
"MenuPosition": "main",
98+
"RelativeNamespace": "Products",
99+
"EntityName": "Product",
100+
"EntityNamePlural": "Products",
101+
"TableName": "Products",
102+
"PrimaryKeyType": "int",
103+
"BaseClass": "Entity",
104+
"EntityHistory": false,
105+
"AutoMigration": true,
106+
"UpdateDatabase": true,
107+
"CreateUserInterface": true,
108+
"CreateViewOnly": true,
109+
"CreateExcelExport": true,
110+
"IsNonModalCRUDPage": false,
111+
"PagePermission": {
112+
"Host": true,
113+
"Tenant": true
114+
},
115+
"Properties": [
116+
{
117+
"Name": "Name",
118+
"Type": "string",
119+
"MaxLength": 25,
120+
"MinLength": 2,
121+
"Range": {
122+
"IsRangeSet": false,
123+
"MinimumValue": 0,
124+
"MaximumValue": 0
125+
},
126+
"Required": true,
127+
"Nullable": false,
128+
"Regex": "",
129+
"UserInterface": {
130+
"List": true,
131+
"AdvancedFilter": true,
132+
"CreateOrUpdate": true
133+
}
134+
},
135+
{
136+
"Name": "Type",
137+
"Type": "ProductType",
138+
"MaxLength": 0,
139+
"MinLength": 0,
140+
"Range": {
141+
"IsRangeSet": false,
142+
"MinimumValue": 0,
143+
"MaximumValue": 0
144+
},
145+
"Required": false,
146+
"Nullable": false,
147+
"Regex": "",
148+
"UserInterface": {
149+
"List": true,
150+
"AdvancedFilter": true,
151+
"CreateOrUpdate": true
152+
}
153+
}
154+
],
155+
"NavigationProperties": [
156+
{
157+
"Namespace": "Volosoft.RadToolExplainer.Authorization.Users",
158+
"ForeignEntityName": "User",
159+
"IdType": "long",
160+
"IsNullable": true,
161+
"PropertyName": "UserId",
162+
"DisplayPropertyName": "Name",
163+
"DuplicationNumber": 0,
164+
"RelationType": "single"
165+
}
166+
],
167+
"EnumDefinitions": [
168+
{
169+
"Name": "ProductType",
170+
"Namespace": "Volosoft.RadToolExplainer",
171+
"EnumProperties": [
172+
{
173+
"Name": "Liquid",
174+
"Value": 1
175+
},
176+
{
177+
"Name": "Solid",
178+
"Value": 2
179+
}
180+
]
181+
}
182+
]
183+
}
184+
```
185+
186+
> Note: Please Keep in mind that JSON file is completely **case sensitive**.

‎docs/en/Power-Tools-Getting-Started.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# ASP.NET ZERO Power Tools Getting Started
2+
3+
Did you know you can achieve Rapid Application Development (RAD) without sacrificing your ASP.Net Core habits and comforts?
4+
5+
## Pre Requirements
6+
7+
* [Visual Studio 2017 (v15.9.0+)](https://www.visualstudio.com/) (Only for Windows)
8+
* [.NET 7 Runtime](https://dotnet.microsoft.com/en-us/download/dotnet/7.0)
9+
* [EF Core Cli](https://docs.microsoft.com/en-us/ef/core/cli/dotnet)
10+
* [ASP.NET Zero v5.0.0+](https://aspnetzero.com/Download)
11+
12+
## Installation
13+
14+
To harness the capabilities of ASP.NET Zero Power Tools, there are two convenient methods available. You can either install the Visual Studio extension or utilize the binaries provided within your ASP.NET Zero solution. Choose the approach that best suits your preferences and requirements.
15+
16+
### Windows
17+
18+
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 from Visual Studio's **Manage Extensions** menu.
19+
20+
![Visual studio extensions](images/power-tools-visual-studio-extensions.png)
21+
22+
### Mac/Linux
23+
24+
If you are a non-Windows user, you have the option to use the binaries of ASP.NET Zero Power Tools that are already included in your ASP.NET Zero solution.
25+
26+
The main purpose of the ASP.NET Zero Power Tools Visual Studio Extension is to create an input file automatically. However, if you prefer not to use the extension, you can create the input file manually.
27+
28+
To create the input file manually for ASP.NET Zero Power Tools, you can refer to the documentation provided at [ASP.NET Zero Power Tools](power-tools-creating-entity-json-file-manually.md). This documentation offers detailed instructions on how to create the input file, which is required to generate entities using the Power Tools.
29+
30+
Once you have created the JSON input file, you can proceed to generate the entity using the following command in the **AspNetZeroRadTool** folder within your project:
31+
32+
```bash
33+
dotnet AspNetZeroRadTool.dll YourEntity.Json
34+
```
35+
36+
## Notes
37+
38+
* If you are using the Visual Studio extension, you can find the generated JSON input file in the **AspNetZeroRadTool** folder within your project.
39+
* Please keep in mind that JSON file is completely case sensitive.
40+
* 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`

0 commit comments

Comments
 (0)