diff --git a/docs/cs/Best-Practices/PostgreSQL-Integration.md b/docs/cs/Best-Practices/PostgreSQL-Integration.md new file mode 100644 index 0000000000..9b0bf40dc2 --- /dev/null +++ b/docs/cs/Best-Practices/PostgreSQL-Integration.md @@ -0,0 +1,35 @@ +## Entity Framework Core PostgreSQL Integration + +> See [Entity Framework Core Integration document](../Entity-Framework-Core.md) for the basics of the EF Core integration. + +### EntityFrameworkCore Project Update + +- In `Acme.BookStore.EntityFrameworkCore` project replace package `Volo.Abp.EntityFrameworkCore.SqlServer` with `Volo.Abp.EntityFrameworkCore.PostgreSql` +- Update to use PostgreSQL in `BookStoreEntityFrameworkCoreModule` + - Replace the `AbpEntityFrameworkCoreSqlServerModule` with the `AbpEntityFrameworkCorePostgreSqlModule` + - Replace the `options.UseSqlServer()` with the `options.UsePostgreSql()` +- In other projects update the PostgreSQL connection string in necessary `appsettings.json` files + +#### Delete Existing Migrations + +Delete all existing migration files (including `DbContextModelSnapshot`) + +![postgresql-delete-initial-migrations](images/postgresql-delete-initial-migrations.png) + +#### Regenerate Initial Migration & Update the Database + +Set the correct startup project (usually a web project), +Open the **Package Manager Console** (Tools -> Nuget Package Manager -> Package Manager Console), select the `Acme.BookStore.EntityFrameworkCore.DbMigrations` as the **Default project** and execute the following command: + +Run `Add-Migration` command. +```` +PM> Add-Migration Initial +```` + +Then execute the `Update-Database` command to update the database schema: + +```` +PM> Update-Database +```` + +![postgresql-update-database](images/postgresql-update-database.png) diff --git a/docs/cs/Best-Practices/images/postgresql-delete-initial-migrations.png b/docs/cs/Best-Practices/images/postgresql-delete-initial-migrations.png new file mode 100644 index 0000000000..39d9e6dedf Binary files /dev/null and b/docs/cs/Best-Practices/images/postgresql-delete-initial-migrations.png differ diff --git a/docs/cs/Best-Practices/images/postgresql-update-database.png b/docs/cs/Best-Practices/images/postgresql-update-database.png new file mode 100644 index 0000000000..02b61ef6a3 Binary files /dev/null and b/docs/cs/Best-Practices/images/postgresql-update-database.png differ diff --git a/docs/cs/Dapper.md b/docs/cs/Dapper.md new file mode 100644 index 0000000000..d8b17838eb --- /dev/null +++ b/docs/cs/Dapper.md @@ -0,0 +1,61 @@ +# Dapper Integration + +Because Dapper's idea is that the sql statement takes precedence, and mainly provides some extension methods for the `IDbConnection` interface. + +Abp does not encapsulate too many functions for Dapper. Abp Dapper provides a `DapperRepository` base class based on Abp EntityFrameworkCore, which provides the `IDbConnection` and `IDbTransaction` properties required by Dapper. + +These two properties can work well with [Unit-Of-Work](Unit-Of-Work.md). + +## Installation + +Please install and configure EF Core according to [EF Core's integrated documentation](Entity-Framework-Core.md). + +`Volo.Abp.Dapper` is the main nuget package for the Dapper integration. Install it to your project (for a layered application, to your data/infrastructure layer): + +```shell +Install-Package Volo.Abp.Dapper +``` + +Then add `AbpDapperModule` module dependency (`DependsOn` attribute) to your [module](Module-Development-Basics.md): + +````C# +using Volo.Abp.Dapper; +using Volo.Abp.Modularity; + +namespace MyCompany.MyProject +{ + [DependsOn(typeof(AbpDapperModule))] + public class MyModule : AbpModule + { + //... + } +} +```` + +## Implement Dapper Repository + +The following code implements the `Person` repository, which requires EF Core's `DbContext` (MyAppDbContext). You can inject `PersonDapperRepository` to call its methods. + +`DbConnection` and `DbTransaction` are from the `DapperRepository` base class. + +```C# +public class PersonDapperRepository : DapperRepository, ITransientDependency +{ + public PersonDapperRepository(IDbContextProvider dbContextProvider) + : base(dbContextProvider) + { + } + + public virtual async Task> GetAllPersonNames() + { + return (await DbConnection.QueryAsync("select Name from People", transaction: DbTransaction)) + .ToList(); + } + + public virtual async Task UpdatePersonNames(string name) + { + return await DbConnection.ExecuteAsync("update People set Name = @NewName", new { NewName = name }, + DbTransaction); + } +} +``` diff --git a/docs/cs/Getting-Started-Angular-Template.md b/docs/cs/Getting-Started-Angular-Template.md new file mode 100644 index 0000000000..1bd605cd65 --- /dev/null +++ b/docs/cs/Getting-Started-Angular-Template.md @@ -0,0 +1,126 @@ +## Getting Started With the Angular Application Template + +This tutorial explain how to create a new Angular application using the startup template, configure and run it. + +### Creating a New Project + +This tutorial uses **ABP CLI** to create a new project. See the [Get Started](https://abp.io/get-started) page for other options. + +Install the ABP CLI using a command line window, if you've not installed before: + +````bash +dotnet tool install -g Volo.Abp.Cli +```` + +Use `abp new` command in an empty folder to create your project: + +````bash +abp new Acme.BookStore -u angular +```` + +> You can use different level of namespaces; e.g. BookStore, Acme.BookStore or Acme.Retail.BookStore. + +`-u angular` option specifies the UI framework to be Angular. Default database provider is EF Core. See the [CLI documentation](CLI.md) for all available options. + +#### Pre Requirements + +The created solution requires; + +* [Visual Studio 2017 (v15.9.0+)](https://visualstudio.microsoft.com/tr/downloads/) +* [.NET Core 2.2+](https://www.microsoft.com/net/download/dotnet-core/) +* [Node v10.16+](https://nodejs.org) +* [Yarn v1.17+](https://yarnpkg.com/) + +### The Solution Structure + +Open the solution in **Visual Studio**: + +![bookstore-visual-studio-solution](images/bookstore-visual-studio-solution-for-spa.png) + +The solution has a layered structure (based on [Domain Driven Design](Domain-Driven-Design.md)) and contains unit & integration test projects properly configured to work with **EF Core** & **SQLite in-memory** database. + +> See the [Application Template Document](Startup-Templates/Application.md) to understand the solution structure in details. + +### Database Connection String + +Check the **connection string** in the `appsettings.json` file under the `.HttpApi.Host` project: + +````json +{ + "ConnectionStrings": { + "Default": "Server=localhost;Database=BookStore;Trusted_Connection=True" + } +} +```` + +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 another DBMS if you want. Change the connection string if you need. + +### Create Database & Apply Database Migrations + +You have two options to create the database. + +#### Using the DbMigrator Application + +The solution contains a console application (named `Acme.BookStore.DbMigrator` in this sample) that can create database, apply migrations and seed 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. + +Right click to the `.DbMigrator` project and select **Set as StartUp Project**: + +![set-as-startup-project](images/set-as-startup-project.png) + +Hit F5 (or Ctrl+F5) to run the application. It will have an output like shown below: + +![set-as-startup-project](images/db-migrator-app.png) + +#### Using EF Core Update-Database Command + +Ef Core has `Update-Database` command which creates database if necessary and applies pending migrations. Right click to the `.Web` project and select **Set as StartUp Project**: + +![set-as-startup-project](images/set-as-startup-project.png) + +Open the **Package Manager Console**, select `.EntityFrameworkCore.DbMigrations` project as the **Default Project** and run the `Update-Database` command: + +![pcm-update-database](images/pcm-update-database-v2.png) + +This will create a new database based on the configured connection string. + +> Using the `.Migrator` tool is the suggested way, because it also seeds the initial data to be able to properly run the web application. + +### Running the Application + +#### Run the API Host (Server Side) + +Ensure that the `.HttpApi.Host` project is the startup project and un the application which will open a Swagger UI: + +![bookstore-homepage](images/bookstore-swagger-ui-host.png) + +You can see the application APIs and test them here. Get [more info](https://swagger.io/tools/swagger-ui/) about the Swagger UI. + +##### Authorization for the Swagger UI + +Most of the application 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. + +#### Run 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 in most cases): + +````bash +yarn +```` + +Once all node modules are loaded, execute `yarn start` or `npm start` command: + +````bash +yarn start +```` + +Open your favorite browser and go to `localhost:4200` URL. Initial username is `admin` and password is `1q2w3E*`. + +The startup template includes the **identity management** and **tenant management** modules. Once you login, the Administration menu will be available where you can manage **tenants**, **roles**, **users** and their **permissions**. + +> We recommend [Visual Studio Code](https://code.visualstudio.com/) as the editor for the Angular project, but you are free to use your favorite editor. + +### What's Next? + +* [Application development tutorial](Tutorials/Angular/Part-I.md) diff --git a/docs/cs/docs-nav.json b/docs/cs/docs-nav.json index 8560190492..91badc73e9 100644 --- a/docs/cs/docs-nav.json +++ b/docs/cs/docs-nav.json @@ -202,7 +202,7 @@ "items": [ { "text": "API", - "items": [ + "items": [ { "text": "Automatické API řadiče", "path": "AspNetCore/Auto-API-Controllers.md" @@ -245,11 +245,21 @@ "items": [ { "text": "Entity Framework Core integrace", - "path": "Entity-Framework-Core.md" + "path": "Entity-Framework-Core.md", + "items": [ + { + "text": "PostgreSQL integrace", + "path": "Best-Practices/PostgreSQL-Integration.md" + } + ] }, { "text": "MongoDB integrace", "path": "MongoDB.md" + }, + { + "text": "Dapper integrace", + "path": "Dapper.md" } ] },