From 5217b1e7d6ad486a12efee9cb6e8a78f6a68b253 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Halil=20=C4=B0brahim=20Kalkan?= Date: Fri, 18 Sep 2020 14:49:13 +0300 Subject: [PATCH] Complete the getting started document for blazor UI --- docs/en/Getting-Started.md | 169 ++++++++++------------- docs/en/Startup-Templates/Application.md | 1 + 2 files changed, 74 insertions(+), 96 deletions(-) diff --git a/docs/en/Getting-Started.md b/docs/en/Getting-Started.md index 4cc3a6e68c..b992247224 100644 --- a/docs/en/Getting-Started.md +++ b/docs/en/Getting-Started.md @@ -11,6 +11,8 @@ This tutorial explains how to create a new web application using the [application startup template](Startup-Templates/Application.md). +> This document assumes that you prefer to use **{{ UI_Value }}** as the UI framework and **{{ DB_Value }}** as the database provider. For other options, please change the preference on top of this document. + ## Setup Your Development Environment @@ -41,117 +43,83 @@ The following tools should be installed on your development machine: > ABP CLI is a free & open source tool for the ABP framework. -First, you need to install the ABP CLI using the following command: +{{if UI == "Blazor"}} + +BLAZOR UI IS ONLY AVAILABLE WITH THE PREVIEW VERSION. SO, YOU NEED TO INSTALL THE PREVIEW VERSION OF THE ABP CLI + +First, you need to install the ABP CLI **RC.2** using the following command: ````shell -dotnet tool install -g Volo.Abp.Cli +dotnet tool install Volo.Abp.Cli -g --version 3.2.0-rc.2 ```` If you've already installed, you can update it using the following command: ````shell -dotnet tool update -g Volo.Abp.Cli +dotnet tool update Volo.Abp.Cli -g --version 3.2.0-rc.2 ```` -## Create a New Project +{{else}} -> This document assumes that you prefer to use **{{ UI_Value }}** as the UI framework and **{{ DB_Value }}** as the database provider. For other options, please change the preference on top of this document. +First, you need to install the ABP CLI using the following command: -### Using the ABP CLI to Create a New Project +````shell +dotnet tool install -g Volo.Abp.Cli +```` -Use the `new` command of the ABP CLI to create a new project: +If you've already installed, you can update it using the following command: ````shell -abp new Acme.BookStore{{if UI == "NG"}} -u angular {{else if UI == "Blazor"}} -u blazor {{end}}{{if DB == "Mongo"}} -d mongodb{{end}}{{if Tiered == "Yes"}}{{if UI == "MVC"}} --tiered {{else}} --separate-identity-server{{end}}{{end}} +dotnet tool update -g Volo.Abp.Cli ```` -{{ if Tiered == "Yes" }} +{{end}} -{{ if UI == "MVC" }} +## Create a New Project -* `--tiered` argument is used to create N-tiered solution where authentication server, UI and API layers are physically separated. +Use the `new` command of the ABP CLI to create a new project: -{{ else }} +````shell +abp new Acme.BookStore{{if UI == "NG"}} -u angular{{else if UI == "Blazor"}} -u blazor --preview{{end}}{{if DB == "Mongo"}} -d mongodb{{end}}{{if Tiered == "Yes"}}{{if UI == "MVC"}} --tiered{{else}} --separate-identity-server{{end}}{{end}} +```` -* `--separate-identity-server` argument is used to separate the identity server application from the API host application. If not specified, you will have a single endpoint on the server. +{{if UI == "Blazor"}} -{{ end }} +> BLAZOR UI IS ONLY AVAILABLE WITH THE PREVIEW VERSION. THIS IS WHY IT IS REQUIRED TO SET THE `--PREVIEW` OPTION. -{{ end }} +{{end}} > You can use different level of namespaces; e.g. BookStore, Acme.BookStore or Acme.Retail.BookStore. -#### ABP CLI Commands & Options - -[ABP CLI document](./CLI.md) covers all of the available commands and options for the ABP CLI. This document uses the [application startup template](Startup-Templates/Application.md) to create a new web application. See the [ABP Startup Templates](Startup-Templates/Index.md) document for other templates. - > Alternatively, you can select the "Direct Download" tab from the [ABP Framework web site](https://abp.io/get-started) to create a new solution. -## The Solution Structure +{{ if Tiered == "Yes" }} {{ if UI == "MVC" }} -After creating your project, you will have the following solution folders & files: - -![](images/solution-files-mvc.png) - -You will see the following solution structure when you open the `.sln` file in the Visual Studio: - -{{if DB == "Mongo"}} - -![vs-default-app-solution-structure](images/vs-app-solution-structure-mongodb.png) - -{{else}} - -{{if Tiered == "Yes"}} - -![vs-default-app-solution-structure](images/vs-app-solution-structure-tiered.png) - -{{else}} - -![vs-default-app-solution-structure](images/vs-app-solution-structure.png) - -{{end}} - -{{end}} - -{{ else if UI == "NG" }} -There are two folders in the created solution: - -![](images/solution-files-non-mvc.png) - -* `angular` folder contains the Angular UI application. -* `aspnet-core` folder contains the backend solution. +* `--tiered` argument is used to create N-tiered solution where authentication server, UI and API layers are physically separated. -Open the `.sln` (Visual Studio solution) file under the `aspnet-core` folder: +{{ else }} -![vs-angular-app-backend-solution-structure](images/vs-spa-app-backend-structure{{if DB == "Mongo"}}-mongodb{{end}}.png) +* `--separate-identity-server` argument is used to separate the identity server application from the API host application. If not specified, you will have a single endpoint on the server. {{ end }} -> ###### About the projects in your solution -> -> Your solution may have slightly different structure based on your **UI**, **database** and other preferences. - -The solution has a layered structure (based on the [Domain Driven Design](Domain-Driven-Design.md)) and also contains unit & integration test projects. - -{{ if DB == "EF" }} - -Integration tests projects are properly configured to work with **EF Core** & **SQLite in-memory** database. +{{ end }} -{{ else if DB == "Mongo" }} +### ABP CLI Commands & Options -Integration tests projects are properly configured to work with in-memory **MongoDB** database created per test (used [Mongo2Go](https://github.com/Mongo2Go/Mongo2Go) library). +[ABP CLI document](./CLI.md) covers all of the available commands and options for the ABP CLI. This document uses the [application startup template](Startup-Templates/Application.md) to create a new web application. See the [ABP Startup Templates](Startup-Templates/Index.md) document for other templates. -{{ end }} +### The Solution Structure -> See the [application template document](Startup-Templates/Application.md) to understand the solution structure in details. +The solution has a layered structure (based on the [Domain Driven Design](Domain-Driven-Design.md)) and contains unit & integration test projects. See the [application template document](Startup-Templates/Application.md) to understand the solution structure in details. ## Create the Database ### Connection String -Check the **connection string** in the `appsettings.json` file under the {{if UI == "MVC"}}{{if Tiered == "Yes"}}`.IdentityServer` and `.HttpApi.Host` projects{{else}}`.Web` project{{end}}{{else if UI == "NG" }}`.HttpApi.Host` project{{end}}: +Check the **connection string** in the `appsettings.json` file under the {{if Tiered == "Yes"}}`.IdentityServer` and `.HttpApi.Host` projects{{else}}{{if UI=="MVC"}}`.Web` project{{else}}`.HttpApi.Host` project{{end}}{{end}} {{ if DB == "EF" }} @@ -161,7 +129,7 @@ Check the **connection string** in the `appsettings.json` file under the {{if UI } ```` -The solution is configured to use **Entity Framework Core** with **MS SQL Server**. EF Core supports [various](https://docs.microsoft.com/en-us/ef/core/providers/) database providers, so you can use any supported DBMS. See [the Entity Framework integration document](https://docs.abp.io/en/abp/latest/Entity-Framework-Core) to learn how to [switch to another DBMS](Entity-Framework-Core-Other-DBMS.md). +The solution is configured to use **Entity Framework Core** with **MS SQL Server** by default. EF Core supports [various](https://docs.microsoft.com/en-us/ef/core/providers/) database providers, so you can use any supported DBMS. See [the Entity Framework integration document](Entity-Framework-Core.md) to learn how to [switch to another DBMS](Entity-Framework-Core-Other-DBMS.md). ### Apply the Migrations @@ -169,7 +137,7 @@ The solution uses the [Entity Framework Core Code First Migrations](https://docs #### Apply Migrations Using the DbMigrator -The solution comes with a `.DbMigrator` console application which applies migrations and also seed the initial data. It is useful on development as well as on production environment. +The solution comes with a `.DbMigrator` console application which applies migrations and also **seeds the initial data**. It is useful on **development** as well as on **production** environment. > `.DbMigrator` project has its own `appsettings.json`. So, if you have changed the connection string above, you should also change this one. @@ -181,7 +149,7 @@ Right click to the `.DbMigrator` project and select **Set as StartUp Project** ![db-migrator-output](images/db-migrator-output.png) -> Initial [seed data](Data-Seeding.md) creates the `admin` user in the database which is then used to login to the application. So, you need to use `.DbMigrator` at least once for a new database. +> Initial [seed data](Data-Seeding.md) creates the `admin` user in the database (with the password is `1q2w3E*`) which is then used to login to the application. So, you need to use `.DbMigrator` at least once for a new database. #### Using EF Core Update-Database Command @@ -221,7 +189,7 @@ The solution is configured to use **MongoDB** in your local computer, so you nee ### Seed Initial Data -The solution comes with a `.DbMigrator` console application which seeds the initial data. It is useful on development as well as on production environment. +The solution comes with a `.DbMigrator` console application which **seeds the initial data**. It is useful on **development** as well as on **production** environment. > `.DbMigrator` project has its own `appsettings.json`. So, if you have changed the connection string above, you should also change this one. @@ -233,7 +201,7 @@ Right click to the `.DbMigrator` project and select **Set as StartUp Project** ![db-migrator-output](images/db-migrator-output.png) -> Initial [seed data](Data-Seeding.md) creates the `admin` user in the database which is then used to login to the application. So, you need to use `.DbMigrator` at least once for a new database. +> Initial [seed data](Data-Seeding.md) creates the `admin` user in the database (with the password is `1q2w3E*`) which is then used to login to the application. So, you need to use `.DbMigrator` at least once for a new database. {{ end }} @@ -243,27 +211,27 @@ Right click to the `.DbMigrator` project and select **Set as StartUp Project** {{ if Tiered == "Yes" }} -Ensure that the `.IdentityServer` project is the startup project. Run the application which will open a **login** page in your browser. +1. Ensure that the `.IdentityServer` project is the startup project. Run this application that will open a **login** page in your browser. > Use Ctrl+F5 in Visual Studio (instead of F5) to run the application without debugging. If you don't have a debug purpose, this will be faster. -You can login, but you cannot enter to the main application here. This is just the authentication server. +You can login, but you cannot enter to the main application here. This is **just the authentication server**. -Ensure that the `.HttpApi.Host` project is the startup project and run the application which will open a **Swagger UI** in your browser. +2. Ensure that the `.HttpApi.Host` project is the startup project and run the application which will open a **Swagger UI** in your browser. ![swagger-ui](images/swagger-ui.png) -This is the API application that is used by the web application. +This is the HTTP API that is used by the web application. -Lastly, ensure that the `.Web` project is the startup project and run the application which will open a **welcome** page in your browser +3. Lastly, ensure that the `.Web` project is the startup project and run the application which will open a **welcome** page in your browser ![mvc-tiered-app-home](images/bookstore-home.png) -Click to the **login** button which will redirect you to the `Identity Server` to login to the application: +Click to the **login** button which will redirect you to the *authentication server* to login to the application: ![bookstore-login](images/bookstore-login.png) -{{ else }} +{{ else # Tiered != "Yes" }} Ensure that the `.Web` project is the startup project. Run the application which will open the **login** page in your browser: @@ -271,11 +239,11 @@ Ensure that the `.Web` project is the startup project. Run the application which ![bookstore-login](images/bookstore-login.png) -{{ end }} +{{ end # Tiered }} -{{ else if UI != "MVC" }} +{{ else # UI != "MVC" }} -#### Running the HTTP API Host (server-side) +### Running the HTTP API Host (Server Side) {{ if Tiered == "Yes" }} @@ -285,15 +253,15 @@ Ensure that the `.IdentityServer` project is the startup project. Run the applic You can login, but you cannot enter to the main application here. This is just the authentication server. -{{ end }} - Ensure that the `.HttpApi.Host` project is the startup project and run the application which will open a Swagger UI: -{{ if Tiered == "No" }} +{{ else # Tiered == "No" }} + +Ensure that the `.HttpApi.Host` project is the startup project and run the application which will open a Swagger UI: > Use Ctrl+F5 in Visual Studio (instead of F5) to run the application without debugging. If you don't have a debug purpose, this will be faster. -{{ end }} +{{ end # Tiered }} ![swagger-ui](images/swagger-ui.png) @@ -303,12 +271,25 @@ You can see the application APIs and test them here. Get [more info](https://swa > > Most of the HTTP APIs require authentication & authorization. If you want to test authorized APIs, manually go to the `/Account/Login` page, enter `admin` as the username and `1q2w3E*` as the password to login to the application. Then you will be able to execute authorized APIs too. -{{ end }} +{{ end # UI }} + +{{ if UI == "Blazor" }} -{{ if UI == "NG" }} -#### Running the Angular application (client-side) +### Running the Blazor Application (Client Side) -Go to the `angular` folder, open a command line terminal, type the `yarn` command (we suggest to the [yarn](https://yarnpkg.com/) package manager while `npm install` will also work in most cases) +Ensure that the `.Blazor` project is the startup project and run the application. + +> Use Ctrl+F5 in Visual Studio (instead of F5) to run the application without debugging. If you don't have a debug purpose, this will be faster. + +Once the application starts, click to the **Login** link on to header, which redirects you to the authentication server to enter a username and password: + +![bookstore-login](images/bookstore-login.png) + +{{ else if UI == "NG" }} + +### Running the Angular Application (Client Side) + +Go to the `angular` folder, open a command line terminal, type the `yarn` command (we suggest to the [yarn](https://yarnpkg.com/) package manager while `npm install` will also work) ```bash yarn @@ -320,11 +301,7 @@ Once all node modules are loaded, execute `yarn start` (or `npm start`) command: yarn start ``` -This will take care of compiling your `TypeScript` code, and automatically reloading your browser. -After it finishes, `Angular Live Development Server` will be listening on localhost:4200, -open your web browser and navigate to [localhost:4200](http://localhost:4200/) - - +It may take a longer time for the first build. Once it finishes, it opens the Angular UI in your default browser with the [localhost:4200](http://localhost:4200/) address. ![bookstore-login](images/bookstore-login.png) @@ -336,7 +313,7 @@ Enter **admin** as the username and **1q2w3E*** as the password to login to the If you want to include a [React Native](https://reactnative.dev/) project in your solution, add `-m react-native` (or `--mobile react-native`) argument to project creation command. This is a basic React Native startup template to develop mobile applications integrated to your ABP based backends. -See the "[Getting Started with the React Native](Getting-Started-React-Native.md)" document to learn how to configure and run the React Native application. +See the [Getting Started with the React Native](Getting-Started-React-Native.md) document to learn how to configure and run the React Native application. ## Next diff --git a/docs/en/Startup-Templates/Application.md b/docs/en/Startup-Templates/Application.md index 4e9bd63371..8cccf32382 100644 --- a/docs/en/Startup-Templates/Application.md +++ b/docs/en/Startup-Templates/Application.md @@ -33,6 +33,7 @@ abp new Acme.BookStore -t app This template provides multiple UI frameworks: * `mvc`: ASP.NET Core MVC UI with Razor Pages (default) +* `blazor`: Blazor UI * `angular`: Angular UI Use `-u` or `--ui` option to specify the UI framework: