diff --git a/common.props b/common.props index a22af0116f..5671a3fc31 100644 --- a/common.props +++ b/common.props @@ -1,7 +1,7 @@ latest - 3.2.0 + 3.3.0 $(NoWarn);CS1591;CS0436 https://abp.io/assets/abp_nupkg.png https://abp.io/ diff --git a/docs/en/API/Dynamic-CSharp-API-Clients.md b/docs/en/API/Dynamic-CSharp-API-Clients.md index 94a0222243..23ec336acf 100644 --- a/docs/en/API/Dynamic-CSharp-API-Clients.md +++ b/docs/en/API/Dynamic-CSharp-API-Clients.md @@ -162,4 +162,4 @@ context.Services.AddHttpClientProxies( Using `asDefaultServices: false` may only be needed if your application has already an implementation of the service and you do not want to override/replace the other implementation by your client proxy. -> If you disable `asDefaultServices`, you can only use `IHttpClientProxy` interface to use the client proxies (see the related section above). \ No newline at end of file +> If you disable `asDefaultServices`, you can only use `IHttpClientProxy` interface to use the client proxies. See the *IHttpClientProxy Interface* section above. \ No newline at end of file diff --git a/docs/en/Blob-Storing.md b/docs/en/Blob-Storing.md index 23b4f80560..f477e6178a 100644 --- a/docs/en/Blob-Storing.md +++ b/docs/en/Blob-Storing.md @@ -20,7 +20,7 @@ The ABP Framework has already the following storage provider implementations; * [Database](Blob-Storing-Database.md): Stores BLOBs in a database. * [Azure](Blob-Storing-Azure.md): Stores BLOBs on the [Azure BLOB storage](https://azure.microsoft.com/en-us/services/storage/blobs/). * [Aliyun](Blob-Storing-Aliyun.md): Stores BLOBs on the [Aliyun Storage Service](https://help.aliyun.com/product/31815.html). -* [Ninio](Blob-Storing-Minio.md): Stores BLOBs on the [MinIO Object storage](https://min.io/). +* [Minio](Blob-Storing-Minio.md): Stores BLOBs on the [MinIO Object storage](https://min.io/). * [Aws](Blob-Storing-Aws.md): Stores BLOBs on the[Amazon Simple Storage Service](https://min.io/). More providers will be implemented by the time. You can [request](https://github.com/abpframework/abp/issues/new) it for your favorite provider or [create it yourself](Blob-Storing-Custom-Provider.md) and [contribute](Contribution/Index.md) to the ABP Framework. diff --git a/docs/en/Blog-Posts/2020-09-17 v3_2_Preview/POST.md b/docs/en/Blog-Posts/2020-09-17 v3_2_Preview/POST.md new file mode 100644 index 0000000000..716a88b6b8 --- /dev/null +++ b/docs/en/Blog-Posts/2020-09-17 v3_2_Preview/POST.md @@ -0,0 +1,240 @@ +# ABP Framework & ABP Commercial 3.2 RC With The New Blazor UI + +We are extremely excited today to release the [ABP Framework](https://abp.io/) (and the [ABP Commercial](https://commercial.abp.io/), as always) version `3.2.0-rc.1` (Release Candidate). This release includes an early preview version of the **Blazor UI** for the ABP.IO Platform. + +## The Blazor UI + +While the Blazor UI **should be considered as experimental** for now, it is possible to start to develop your application today. + +### Fundamental Services + +Currently, implemented some important framework features; + +* **Authentication** through the MVC backend using the OpenId Connect authorization code flow. So, all the current login options (login, register, forgot password, external/social logins...) are supported. +* **Authorization**, using the ABP Framework **permissions** as well as the standard authorization system. +* **Localization** just works like the MVC UI. +* **Basic Theme** with top main menu. +* **Dynamic C# HTTP API proxies**, so you can directly consume your backend API by injecting the application service interfaces. +* Some other **fundamental services** like `ISettingProvider`, `IFeatureChecker`, `ICurrentUser`... + +Also, the standard .net services are already available, like caching, logging, validation and much more. Since the ABP Framework is layered itself, all the non MVC UI related features are already usable for the Blazor UI. + +### Pre-Built Modules + +Some modules have been implemented; + +* **Identity** module is pre-installed and provides **user, role and permission management**. +* **Profile management** page is implemented to allow to change password and personal settings. + +### About the Blazorise Library + +We've selected the [Blazorise](https://blazorise.com/) as a fundamental UI library for the Blazor UI. It already supports different HTML/CSS frameworks (like Bootstrap, Bulma, Ant Design...) and significantly increases the developer productivity. + +![blazorise-github](blazorise-github.png) + +We also have a good news: **[Mladen Macanović](https://github.com/stsrki)**, the creator of the Blazorise, is **joining to the core ABP Framework team** in the next weeks. We are excited to work with him to bring the power of these two successful projects together. + +### The Tutorial + +We are currently in progress of updating the [web application development tutorial](https://docs.abp.io/en/abp/3.2/Tutorials/Part-1) for the Blazor UI. Follow the [@abpframework](https://twitter.com/abpframework) Twitter account to get informed once it's ready. + +### Get started with the Blazor UI + +If you want to try the Blazor UI today, follow the instructions below. + +#### Upgrade the ABP CLI + +> **Known issue**: When you upgrade the ABP CLI to `3.2.0-rc.1`, you won't be able to create new solutions with a stable version ([#5453](https://github.com/abpframework/abp/issues/5453)). Downgrade to `3.1.0` back after trying the preview version, if you want to create solutions with a stable version later. + +Install the latest [ABP CLI](https://docs.abp.io/en/abp/3.2/CLI) preview version: + +````bash +dotnet tool update Volo.Abp.Cli -g --version 3.2.0-rc.1 +```` + +#### Create a new Solution + +Then you can create a new solution using the *abp new* command: + +````bash +abp new AbpBlazorDemo -u blazor --preview +```` + +Also specify the `-t app-pro` parameter if you are an ABP Commercial user. + +> See the ABP CLI documentation for the additional options, like MongoDB database or separated authentication server. + +#### Open the Solution + +Open the generated solution using the latest Visual Studio 2019. You will see a solution structure like the picture below: + +![visual-studio-solution-with-blazor](visual-studio-solution-with-blazor.png) + +> **A fix for the 3.2.0-rc.1** +> +> There is a bug in the `3.2.0-rc.1` that prevents `HttpApi.Host` project run properly, when you try to login to the application. **Follow the steps explained in the [#5457](https://github.com/abpframework/abp/issues/5457) for the `HttpApi.Host` project** to fix it for your solution, before running it. It will be resolved with the `3.2.0-rc.2`. + +#### Run the Application + +* Run the `DbMigrator` project to create the database and seed the initial data. +* Run the `HttpApi.Host` project for the server side. +* Run the `Blazor` project to start the Blazor UI. + +Use `admin` as the username and `1q2w3E*` as the password to login to the application. + +Here, a screenshot from the role management page of the Blazor UI: + +![blazor-role-management](blazor-role-management.png) + +## What's New with the ABP Framework 3.2 + +Beside the Blazor UI, there are a lot of issues have been closed with [the milestone 3.2](https://github.com/abpframework/abp/milestone/39?closed=1). I will highlight some of the major features and changes released with this version. + +### MongoDB ACID Transactions + +[MongoDB integration](https://docs.abp.io/en/abp/3.2/MongoDB) now supports multi-document transactions that comes with the MongoDB 4.x. + +> Transactions are disabled for automated integration tests coming with the application startup template, since the Mongo2Go library (we use in the test projects) has a problem with the transactions. We've sent a [Pull Request](https://github.com/Mongo2Go/Mongo2Go/pull/101) to fix it and will enable the transactions again when they merge & release it. +> +> If you are upgrading an existing solution and using MongoDB, please disable transactions for the test projects by following the [Unit Of Work](https://docs.abp.io/en/abp/3.2/Unit-Of-Work) documentation. + +### Kafka Integration for the Distributed Event Bus + +ABP Framework's [distributed event system](https://docs.abp.io/en/abp/3.2/Distributed-Event-Bus) has been [integrated to RabbitMQ](https://docs.abp.io/en/abp/3.2/Distributed-Event-Bus-RabbitMQ-Integration) before. By the version 3.2, it has a Kafka integration package, named [Volo.Abp.EventBus.Kafka](https://www.nuget.org/packages/Volo.Abp.EventBus.Kafka). + +See the [Kafka integration documentation](https://docs.abp.io/en/abp/3.2/Distributed-Event-Bus-Kafka-Integration) to learn how to install and configure it. + +### Host Features + +[ABP Feature System](https://docs.abp.io/en/abp/3.2/Features) allows you to define features in your application. Then you can enable/disable a feature dynamically on the runtime. It is generally used in a [multi-tenant](https://docs.abp.io/en/abp/3.2/Multi-Tenancy) system to restrict features for tenants, so you can charge extra money for some features in a SaaS application. + +In some cases, you may want to use the same features in the host side (host is you as you are managing the tenants). For this case, we've added a "**Manage Host Features**" button to the Tenant Management page so you can open a modal dialog to select the features for the host side. + +![host-features](host-features.png) + +### AbpHttpClientBuilderOptions + +ABP Framework provides a system to dynamically create C# proxies to consume HTTP APIs from your client applications. `AbpHttpClientBuilderOptions` is a new option class to configure the `HttpClient`s used by the proxy system. + +**Example: Use the [Polly](https://github.com/App-vNext/Polly) library to retry up to 3 times for a failed HTTP request** + +````csharp +public override void PreConfigureServices(ServiceConfigurationContext context) +{ + PreConfigure(options => + { + options.ProxyClientBuildActions.Add((remoteServiceName, clientBuilder) => + { + clientBuilder.AddTransientHttpErrorPolicy(policyBuilder => + policyBuilder.WaitAndRetryAsync( + 3, + i => TimeSpan.FromSeconds(Math.Pow(2, i)) + ) + ); + }); + }); +} +```` + +See the issue [#5304](https://github.com/abpframework/abp/issues/5304) for the details. + +### ABP Build Command + +We are using **mono repository** approach and the [abp repository](https://github.com/abpframework/abp) has tens of solutions and hundreds of projects (the framework, modules, tooling, templates...) with all of them are referencing to each other. + +It gets a significant time to build the whole repository for every Git push. To **optimize** this process, we've created the **abp build** command in the [ABP CLI](https://docs.abp.io/en/abp/3.2/CLI): + +````bash +abp build +```` + +We will use this command to build the abp repository or a solution inside it. However it is available to everyone in case of need. + +> **Most of the people will not need it**. If you need it, see the [ABP CLI](https://docs.abp.io/en/abp/3.2/CLI) document to learn all the details and options. + +### Other Features, Improvements and Changes + +* Introduced the `DynamicRangeAttribute` that can be used to determine the range values on runtime, just like the `DynamicStringLengthAttribute` was introduced before. +* Improved the feature management modal for multi-tenant applications to group features on the UI and show hierarchically. +* Added `--skip-cli-version-check` option to ABP CLI to improve the performance by bypassing the online version check. +* Angular UI now redirect to MVC UI (the authentication server side) for profile management page, if the authorization code flow is used (which is the default). +* Account module profile management page is now extensible. You can implement the `IProfileManagementPageContributor` interface and register it using the `ProfileManagementPageOptions` class. +* Improvements and optimizations for the [Angular service proxy generation](https://blog.abp.io/abp/Introducing-the-Angular-Service-Proxy-Generation). + +And a lot of minor improvements and bug fixes. You can see [the milestone 3.2](https://github.com/abpframework/abp/milestone/39?closed=1) for all issues & PRs closed with this version. + +## What's New with the ABP Commercial 3.2 + +### Breaking Changes + +The new *profile picture management* feature uses the [BLOB storing](https://docs.abp.io/en/abp/3.2/Blob-Storing) system, so it needs a Storage Provider. The new **startup template comes with the [Database BLOB Provider](https://docs.abp.io/en/abp/3.2/Blob-Storing-Database) pre-installed**. You can change it if you want to use another BLOB provider (like Azure, AWS or a simple file system). + +**Existing solutions must configure a BLOB provider** after upgrading to the version 3.2. Follow the [BLOB Storing document](https://docs.abp.io/en/abp/3.2/Blob-Storing#blob-storage-providers) to configure the provider yourself. + +### The Blazor UI + +The **experimental** Blazor UI is also available for the ABP Commercial. The [Lepton Theme](https://commercial.abp.io/themes) hasn't been implemented with this initial preview, however we are working on it with the highest priority. + +You can use the [ABP Suite](https://docs.abp.io/en/commercial/latest/abp-suite/index) or the following ABP CLI command to create a new solution with the Blazor UI: + +````bash +abp new AbpBlazorDemo -u blazor -t app-pro --preview +```` + +Please try it and provide feedback to us. Thanks in advance. + +> See the instructions in the *Get started with the Blazor UI* section above to properly create and run your application. + +### File Management Angular UI + +Angular UI for the [File Management](https://commercial.abp.io/modules/Volo.FileManagement) module is available with the version 3.2. You can add it to your solution using the ABP Suite. + +![file-management-module-angular](file-management-module-angular.png) + +### Profile Picture Management + +We've added profile picture management for the account module, so a user can select one of the options below for her profile picture; + +* Use the default placeholder as the avatar. +* Use [Gravatar](https://gravatar.com/) service to get the picture matching the email address of the user. +* Upload a file as the profile picture. + +![account-profile-picture](account-profile-picture.jpg) + +### Two Factor Authentication Features + +Created [features](https://docs.abp.io/en/abp/3.2/Features) and [settings](https://docs.abp.io/en/abp/3.2/Settings) to disable, enable or force to use 2FA on login for the tenants and users. + +### Upgrading the ABP Suite + +You can use the following command to upgrade the ABP Suite to the latest preview version: + +```` +abp suite update --preview +```` + +## Other News + +### The ABP Community + +**ABP Community** web site is constantly being improved and new articles are added. We will add "**commenting**" and "**rating**" features to the articles soon to increase the interactivity between the people. + +![abp-community-20200917](abp-community-20200917.png) + +If you have something to share with the ABP community or want to follow the project progress, please check the **[community.abp.io](https://community.abp.io/)**! + +### CMS Kit Project + +We are silently working on a project, named [CMS Kit](https://github.com/abpframework/abp/tree/dev/modules/cms-kit), for a few months. CMS Kit is a set of reusable CMS (Content Management System) components based on the ABP Framework. Some of the components currently being developed: + +* **Comments**; Allows users to comment under something (a blog post, a document, an image... etc). +* **Reactions**; Allows users to give reactions to something (a comment, a picture... etc.) using simple emoji icons. +* **Rating**; Allows users to rate some content from 1 to 5. +* **Newsletter**; Allows you to put a newsletter box to your web site to collect emails from users. +* **Contact**; Put a form to get message from the web site visitors. + +There are more planned components like articles, tags, votes, favorites, portfolio, image gallery, FAQ... etc. We will document and deploy these components when they get matured and ready to use. Some of them will be open source & free while some of them are paid (included in the [ABP Commercial](https://commercial.abp.io/) license). + +## Feedback + +Please try the ABP Framework 3.2.0 RC and [provide feedback](https://github.com/abpframework/abp/issues/new) to help us to release a more stable version. The planned release date for the [3.2.0 final](https://github.com/abpframework/abp/milestone/43) version is October 01. \ No newline at end of file diff --git a/docs/en/Blog-Posts/2020-09-17 v3_2_Preview/abp-community-20200917.png b/docs/en/Blog-Posts/2020-09-17 v3_2_Preview/abp-community-20200917.png new file mode 100644 index 0000000000..1a3997a6ab Binary files /dev/null and b/docs/en/Blog-Posts/2020-09-17 v3_2_Preview/abp-community-20200917.png differ diff --git a/docs/en/Blog-Posts/2020-09-17 v3_2_Preview/account-profile-picture.jpg b/docs/en/Blog-Posts/2020-09-17 v3_2_Preview/account-profile-picture.jpg new file mode 100644 index 0000000000..1b57ce4025 Binary files /dev/null and b/docs/en/Blog-Posts/2020-09-17 v3_2_Preview/account-profile-picture.jpg differ diff --git a/docs/en/Blog-Posts/2020-09-17 v3_2_Preview/blazor-role-management.png b/docs/en/Blog-Posts/2020-09-17 v3_2_Preview/blazor-role-management.png new file mode 100644 index 0000000000..e00d66e9d0 Binary files /dev/null and b/docs/en/Blog-Posts/2020-09-17 v3_2_Preview/blazor-role-management.png differ diff --git a/docs/en/Blog-Posts/2020-09-17 v3_2_Preview/blazorise-github.png b/docs/en/Blog-Posts/2020-09-17 v3_2_Preview/blazorise-github.png new file mode 100644 index 0000000000..1c8490f605 Binary files /dev/null and b/docs/en/Blog-Posts/2020-09-17 v3_2_Preview/blazorise-github.png differ diff --git a/docs/en/Blog-Posts/2020-09-17 v3_2_Preview/file-management-module-angular.png b/docs/en/Blog-Posts/2020-09-17 v3_2_Preview/file-management-module-angular.png new file mode 100644 index 0000000000..e370c0d5bc Binary files /dev/null and b/docs/en/Blog-Posts/2020-09-17 v3_2_Preview/file-management-module-angular.png differ diff --git a/docs/en/Blog-Posts/2020-09-17 v3_2_Preview/host-features.png b/docs/en/Blog-Posts/2020-09-17 v3_2_Preview/host-features.png new file mode 100644 index 0000000000..c803f8599b Binary files /dev/null and b/docs/en/Blog-Posts/2020-09-17 v3_2_Preview/host-features.png differ diff --git a/docs/en/Blog-Posts/2020-09-17 v3_2_Preview/visual-studio-solution-with-blazor.png b/docs/en/Blog-Posts/2020-09-17 v3_2_Preview/visual-studio-solution-with-blazor.png new file mode 100644 index 0000000000..c4c018e842 Binary files /dev/null and b/docs/en/Blog-Posts/2020-09-17 v3_2_Preview/visual-studio-solution-with-blazor.png differ diff --git a/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/POST.md b/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/POST.md new file mode 100644 index 0000000000..b286bb509d --- /dev/null +++ b/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/POST.md @@ -0,0 +1,122 @@ +# How to Setup Azure Active Directory and Integrate Abp Angular Application + +This guide demonstrates how to register an application to Azure Active Directory and integrate AzureAD to an ABP angular application that enables users to sign in using OAuth 2.0 with credentials from **Azure Active Directory**. + +## Authentication Flow + +Abp angular applications use **Authentication Code with PKCE** (specs [here](https://tools.ietf.org/html/rfc7636)) which is the most suitable flow for spa applications by the time this article is written since implicit flow is deprecated. + +The most common question is; + +> Where to put OpenId connection code in angular project? + +The answer is, **you don't**. Abp angular application is integrated with backend code (HttpApi.Host project) where it loads the configurations, **permissions** etc. For none-tiered angular applications, **HttpApi.Host** project also has IdentityServer4 embedded; also serving as **Authorization Server**. Angular application authentication flow is shown below. + +auth-diagram + +> What if I want Azure AD as my authorization server and not IdentityServer? + +This means your application will be using AzureAD user store for authentication. By registering both angular app and HttpApi to AzureAD, authentication might work but **authorization won't**. Users need to be registered to Abp identity system for auditing, permissions etc. So the flow should be 3rd party registration. + +## Setting up OpenId Connection + +Lets start with adding OpenId connection. Open the **HttpApiHostModule.cs** and update the **ConfigureAuthentication** method as below: + +```csharp +JwtSecurityTokenHandler.DefaultInboundClaimTypeMap.Clear(); +JwtSecurityTokenHandler.DefaultInboundClaimTypeMap.Add("sub", ClaimTypes.NameIdentifier); + +context.Services.AddAuthentication() + .AddIdentityServerAuthentication(options => + { + options.Authority = configuration["AuthServer:Authority"]; + options.RequireHttpsMetadata = false; + options.ApiName = "NonTieredAngular"; + options.JwtBackChannelHandler = new HttpClientHandler() + { + ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousAcceptAnyServerCertificateValidator + }; + }) + .AddOpenIdConnect("AzureOpenId", "Azure AD OpenId", options => + { + options.Authority = "https://login.microsoftonline.com/" + configuration["AzureAd:TenantId"] + "/v2.0/"; + options.ClientId = configuration["AzureAd:ClientId"]; + options.ResponseType = OpenIdConnectResponseType.CodeIdToken; + options.CallbackPath = configuration["AzureAd:CallbackPath"]; + options.ClientSecret = configuration["AzureAd:ClientSecret"]; + options.RequireHttpsMetadata = false; + options.SaveTokens = true; + options.GetClaimsFromUserInfoEndpoint = true; + options.Scope.Add("email"); + }); +``` + +> If you are using tiered (separate identity server) application, open **IdentityServerModule.cs** and add the OpenIdConnection manually to **ConfigureServices** method as following: + +```csharp +public override void ConfigureServices(ServiceConfigurationContext context) +{ + var hostingEnvironment = context.Services.GetHostingEnvironment(); + var configuration = context.Services.GetConfiguration(); + + JwtSecurityTokenHandler.DefaultInboundClaimTypeMap.Clear(); + JwtSecurityTokenHandler.DefaultInboundClaimTypeMap.Add("sub", ClaimTypes.NameIdentifier); + + context.Services.AddAuthentication() + .AddOpenIdConnect("AzureOpenId", "Azure AD OpenId", options => + { + ... // Same configuration above + }); +``` + +Now we can add AzureAD settings. Open the **appsettings.json** located in **HttpApi.Host** project (or **IdentityServer** project if you are using tiered application). Add the following; + +```csharp +"AzureAd": { + "Instance": "https://login.microsoftonline.com/", + "TenantId": "", + "ClientId": "", + "Domain": "domain.onmicrosoft.com", + "CallbackPath": "/signin-azuread-oidc", + "ClientSecret": "" +}, +``` + +Keep on mind that **App.SelfUrl** + **AzureAd.CallbackPath** will be used in AzureAD app registration. We'll update the AzureAd settings after registering the application in Azure Portal. + +## Setting up Azure Active Directory + +Navigate to Manage Azure Active Directory in [azure portal](https://portal.azure.com/). Go to **App registrations** on left side menu and hit New registration. + +![azure-app-registration](azure-app-registration.jpg) + +Enter a name for your application and **App.SelfUrl** + **AzureAd.CallbackPath** as redirect uri then register. + +azure-app-register + +Now navigate to **Authentication** on the left menu and enable **ID tokens**. + +![azure-app-authentication](azure-app-authentication.jpg) + +We also need to set a client secret. Navigate to **Certificates & secrets** menu on the left and create a new client secret. + +![azure-app-secret](azure-app-secret.jpg) + +**Copy** the secret and update your appsettings.json **AzureAd.ClientSecret** field. + +![azure-app-overview](azure-app-overview.jpg) + +Also update your **AzureAd.TenantId** and **AzureAd.ClientId** fields with the information located under **Overview** menu. And that's all. + +Next time you hit login, you should be seeing login screen enabled Azure AD like below. + +![app-login](app-login.JPG) + +# FAQ + +* I am getting errors when trying to login to AzureAD. + * You can check [this article FAQ](https://community.abp.io/articles/how-to-use-the-azure-active-directory-authentication-for-mvc-razor-page-applications-4603b9cf) which covers many errors. + + +* But I don't want my users to see default login screen. I want my users to login **only** from AzureAD. + * You can **mimic** this behaviour by customizing the login page and instantly trigger Azure AD provider click. For more info, you can check [this article](https://community.abp.io/articles/how-to-customize-the-login-page-for-mvc-razor-page-applications-9a40f3cd). diff --git a/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/app-login.JPG b/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/app-login.JPG new file mode 100644 index 0000000000..94500a4f15 Binary files /dev/null and b/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/app-login.JPG differ diff --git a/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/auth-diagram.jpeg b/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/auth-diagram.jpeg new file mode 100644 index 0000000000..dec4a66a17 Binary files /dev/null and b/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/auth-diagram.jpeg differ diff --git a/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/azure-app-authentication.jpg b/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/azure-app-authentication.jpg new file mode 100644 index 0000000000..5061118aa3 Binary files /dev/null and b/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/azure-app-authentication.jpg differ diff --git a/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/azure-app-overview.jpg b/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/azure-app-overview.jpg new file mode 100644 index 0000000000..11053062e2 Binary files /dev/null and b/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/azure-app-overview.jpg differ diff --git a/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/azure-app-register.JPG b/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/azure-app-register.JPG new file mode 100644 index 0000000000..68c180cea0 Binary files /dev/null and b/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/azure-app-register.JPG differ diff --git a/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/azure-app-registration.jpg b/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/azure-app-registration.jpg new file mode 100644 index 0000000000..12f4eb36e2 Binary files /dev/null and b/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/azure-app-registration.jpg differ diff --git a/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/azure-app-secret.jpg b/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/azure-app-secret.jpg new file mode 100644 index 0000000000..9cf2009eda Binary files /dev/null and b/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/azure-app-secret.jpg differ diff --git a/docs/en/Getting-Started.md b/docs/en/Getting-Started.md index 55fcafe132..dbfb8a714e 100644 --- a/docs/en/Getting-Started.md +++ b/docs/en/Getting-Started.md @@ -3,13 +3,15 @@ ````json //[doc-params] { - "UI": ["MVC","NG"], + "UI": ["MVC", "Blazor", "NG"], "DB": ["EF", "Mongo"], "Tiered": ["Yes", "No"] } ```` -This tutorial explains how to create a new {{if UI == "MVC"}} ASP.NET Core MVC (Razor Pages) web {{else if UI == "NG"}} Angular {{end}} application using the startup template. +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 @@ -20,11 +22,11 @@ First things first! Let's setup your development environment before creating the The following tools should be installed on your development machine: -* [Visual Studio 2019 (v16.4+)](https://visualstudio.microsoft.com/vs/) for Windows / [Visual Studio for Mac](https://visualstudio.microsoft.com/vs/mac/). [1](#f-editor) +* [Visual Studio 2019](https://visualstudio.microsoft.com/vs/) for Windows / [Visual Studio for Mac](https://visualstudio.microsoft.com/vs/mac/). [1](#f-editor) * [.NET Core 3.1+](https://www.microsoft.com/net/download/dotnet-core/) -* [Node v12 or v14](https://nodejs.org/en/) -* [Yarn v1.20+ (not v2)](https://classic.yarnpkg.com/en/docs/install) [2](#f-yarn) or npm v6+ (installed with Node) +* [Node v12 or v14](https://nodejs.org/) +* [Yarn v1.20+ (not v2)](https://classic.yarnpkg.com/en/docs/install) [2](#f-yarn) or npm v6+ (already installed with Node) {{ if Tiered == "Yes" }} * [Redis](https://redis.io/) (the startup solution uses the Redis as the [distributed cache](Caching.md)). @@ -37,123 +39,102 @@ The following tools should be installed on your development machine: ### Install the ABP CLI -[ABP CLI](./CLI.md) is a command line interface that is used to automate some common tasks for ABP based applications. +[ABP CLI](./CLI.md) is a command line interface that is used to automate some common tasks for ABP based solutions. > 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 - -> 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. - -### Using the ABP CLI to Create a New Project +{{else}} -Use the `new` command of the ABP CLI to create a new project: +First, you need to install the ABP CLI using the following command: ````shell -abp new Acme.BookStore{{if UI == "NG"}} -u angular {{end}}{{if DB == "Mongo"}} -d mongodb{{end}}{{if Tiered == "Yes" && UI != "NG"}} --tiered {{else if Tiered == "Yes" && UI == "NG"}}--separate-identity-server{{end}} +dotnet tool install -g Volo.Abp.Cli ```` -{{ if UI == "NG" }} - -* `-u` argument specifies the UI framework, `angular` in this case. - -{{ if Tiered == "Yes" }} - -* `--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 you've already installed, you can update it using the following command: -{{ end }} +````shell +dotnet tool update -g Volo.Abp.Cli +```` -{{ end }} +{{end}} -{{ if DB == "Mongo" }} +## Create a New Project -* `-d` argument specifies the database provider, `mongodb` in this case. +Use the `new` command of the ABP CLI to create a new project: -{{ end }} +````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}} +```` -{{ if Tiered == "Yes" && UI != "NG" }} +{{if UI == "Blazor"}} -* `--tiered` argument is used to create N-tiered solution where authentication server, UI and API layers are physically separated. +> 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}} - -![vs-default-app-solution-structure](images/vs-app-solution-structure{{if Tiered == "Yes"}}-tiered{{end}}.png) - -{{end}} +* `--tiered` argument is used to create N-tiered solution where authentication server, UI and API layers are physically separated. -{{ else if UI == "NG" }} -There are three folders in the created solution: +{{ else }} -![](images/solution-files-non-mvc.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. -* `angular` folder contains the Angular UI application. -* `aspnet-core` folder contains the backend solution. +{{ end }} -Open the `.sln` (Visual Studio solution) file under the `aspnet-core` folder: +{{ end }} -![vs-angular-app-backend-solution-structure](images/vs-spa-app-backend-structure{{if DB == "Mongo"}}-mongodb{{end}}.png) +### ABP CLI Commands & Options -{{ end }} +[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. -> ###### About the projects in your solution -> -> Your solution may have slightly different structure based on your **UI**, **database** and other preferences. +### The Solution Structure -The solution has a layered structure (based on the [Domain Driven Design](Domain-Driven-Design.md)) and also contains unit & integration test projects. +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. -{{ if DB == "EF" }} +{{ if DB == "Mongo" }} -Integration tests projects are properly configured to work with **EF Core** & **SQLite in-memory** database. +#### MongoDB Transactions -{{ else if DB == "Mongo" }} +The [startup template](Startup-templates/Index.md) **disables** transactions in the `.MongoDB` project by default. If your MongoDB server supports transactions, you can enable the it in the *YourProjectMongoDbModule* class: -Integration tests projects are properly configured to work with in-memory **MongoDB** database created per test (used [Mongo2Go](https://github.com/Mongo2Go/Mongo2Go) library). + ```csharp + Configure(options => + { + options.TransactionBehavior = UnitOfWorkTransactionBehavior.Enabled; + }); + ``` {{ end }} -> 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" }} @@ -163,7 +144,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 @@ -171,7 +152,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. @@ -183,7 +164,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 @@ -223,7 +204,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. @@ -235,7 +216,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 }} @@ -245,27 +226,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: @@ -273,11 +254,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" }} @@ -287,15 +268,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) @@ -305,12 +286,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 == "NG" }} -#### Running the Angular application (client-side) +{{ if UI == "Blazor" }} -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) +### Running the Blazor Application (Client Side) + +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 @@ -322,11 +316,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) @@ -338,7 +328,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/MongoDB.md b/docs/en/MongoDB.md index e7d8084f41..1328cfc084 100644 --- a/docs/en/MongoDB.md +++ b/docs/en/MongoDB.md @@ -275,6 +275,17 @@ public class BookService > Important: You must reference to the `Volo.Abp.MongoDB` package from the project you want to access to the MongoDB API. This breaks encapsulation, but this is what you want in that case. +### Transactions + +MongoDB supports multi-document transactions starting from the version 4.0 and the ABP Framework supports it. However, the [startup template](Startup-templates/Index.md) **disables** transactions by default. If your MongoDB **server** supports transactions, you can enable the it in the *YourProjectMongoDbModule* class: + +```csharp +Configure(options => +{ + options.TransactionBehavior = UnitOfWorkTransactionBehavior.Enabled; +}); +``` + ### Advanced Topics #### Set Default Repository Classes diff --git a/docs/en/Multi-Tenancy.md b/docs/en/Multi-Tenancy.md index 5138c9de04..c087c6b8f2 100644 --- a/docs/en/Multi-Tenancy.md +++ b/docs/en/Multi-Tenancy.md @@ -304,6 +304,7 @@ Volo.Abp.AspNetCore.MultiTenancy package adds following tenant resolvers to dete * **CurrentUserTenantResolveContributor**: Gets the tenant id from claims of the current user, if the current user has logged in. **This should always be the first contributor for security**. * **QueryStringTenantResolveContributor**: Tries to find current tenant id from query string parameter. Parameter name is "__tenant" by default. +* **FormTenantResolveContributor**: Tries to find current tenant id from form parameter. Parameter name is "__tenant" by default. * **RouteTenantResolveContributor**: Tries to find current tenant id from route (URL path). Variable name is "__tenant" by default. So, if you defined a route with this variable, then it can determine the current tenant from the route. * **HeaderTenantResolveContributor**: Tries to find current tenant id from HTTP header. Header name is "__tenant" by default. * **CookieTenantResolveContributor**: Tries to find current tenant id from cookie values. Cookie name is "__tenant" by default. diff --git a/docs/en/Road-Map.md b/docs/en/Road-Map.md index 91fe94427e..8670ba080b 100644 --- a/docs/en/Road-Map.md +++ b/docs/en/Road-Map.md @@ -4,22 +4,18 @@ You can always check the milestone planning and the prioritized backlog issues o While we will **continue to add other exciting features**, we will work on the following major items in the **middle term**: -* **Blazor UI** for the framework and all the pre-built modules. +* **Blazor UI** for the framework and all the pre-built modules (in progress). * **.NET 5.0**! As Microsoft has announced that the .NET 5.0 will be released in November 2020, we will prepare for this change before and move to the .NET 5.0 just after Microsoft releases it. We hope a smooth transition. Beside this middle term goals, there are many features in the [backlog](https://github.com/abpframework/abp/milestone/2). Here, a list of some major items in the backlog; -* [#2882](https://github.com/abpframework/abp/issues/2882) / Providing a **gRPC integration** infrastructure (while it is [already possible](https://github.com/abpframework/abp-samples/tree/master/GrpcDemo) to create or consume gRPC endpoints for your application, we plan to create endpoints for the [standard application modules](https://docs.abp.io/en/abp/latest/Modules/Index)) +* [#2882](https://github.com/abpframework/abp/issues/2882) / Providing a gRPC integration infrastructure (while it is [already possible](https://github.com/abpframework/abp-samples/tree/master/GrpcDemo) to create or consume gRPC endpoints for your application, we plan to create endpoints for the [standard application modules](https://docs.abp.io/en/abp/latest/Modules/Index)) * [#236](https://github.com/abpframework/abp/issues/236) Resource based authorization system * [#1754](https://github.com/abpframework/abp/issues/1754) / Multi-lingual entities -* [#347](https://github.com/abpframework/abp/issues/347) / Support MongoDB ACID transactions * [#633](https://github.com/abpframework/abp/issues/633) / Realtime notification system * [#57](https://github.com/abpframework/abp/issues/57) / Built-in CQRS infrastructure -* [#4222](https://github.com/abpframework/abp/issues/4222) / Kafka integration for the Distributed Event Bus * [#336](https://github.com/abpframework/abp/issues/336) / Health Check abstraction * [#2532](https://github.com/abpframework/abp/issues/2532), [#2564](https://github.com/abpframework/abp/issues/2465) / CosmosDB integration with EF Core and MongoDB API -* [#1168](https://github.com/abpframework/abp/issues/1168) / Official Vue UI startup template -* [#1638](https://github.com/abpframework/abp/issues/1638) Official React startup template * [#4223](https://github.com/abpframework/abp/issues/4223) / WebHook system * [#162](https://github.com/abpframework/abp/issues/162) / Azure ElasticDB Integration for multitenancy * [#2296](https://github.com/abpframework/abp/issues/2296) / Feature toggling infrastructure 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: diff --git a/docs/en/Tutorials/Part-1.md b/docs/en/Tutorials/Part-1.md index 98263f64f7..3348679420 100644 --- a/docs/en/Tutorials/Part-1.md +++ b/docs/en/Tutorials/Part-1.md @@ -2,32 +2,15 @@ ````json //[doc-params] { - "UI": ["MVC","NG"], + "UI": ["MVC","Blazor","NG"], "DB": ["EF","Mongo"] } ```` -{{ -if UI == "MVC" - UI_Text="mvc" -else if UI == "NG" - UI_Text="angular" -else - UI_Text="?" -end -if DB == "EF" - DB_Text="Entity Framework Core" -else if DB == "Mongo" - DB_Text="MongoDB" -else - DB_Text="?" -end -}} - ## About This Tutorial In this tutorial series, you will build an ABP based web application named `Acme.BookStore`. This application is used to manage a list of books and their authors. It is developed using the following technologies: -* **{{DB_Text}}** as the ORM provider. +* **{{DB_Value}}** as the database provider. * **{{UI_Value}}** as the UI Framework. This tutorial is organized as the following parts; @@ -45,9 +28,10 @@ This tutorial is organized as the following parts; ### Download the Source Code -This tutorial has multiple versions based on your **UI** and **Database** preferences. We've prepared two combinations of the source code to be downloaded: +This tutorial has multiple versions based on your **UI** and **Database** preferences. We've prepared a few combinations of the source code to be downloaded: * [MVC (Razor Pages) UI with EF Core](https://github.com/abpframework/abp-samples/tree/master/BookStore-Mvc-EfCore) +* [Blazor UI with EF Core](https://github.com/abpframework/abp-samples/tree/master/BookStore-Blazor-EfCore) * [Angular UI with MongoDB](https://github.com/abpframework/abp-samples/tree/master/BookStore-Angular-MongoDb) {{if UI == "MVC" && DB == "EF"}} @@ -217,7 +201,7 @@ Before updating the database, read the section below to learn how to seed some i > It's good to have some initial data in the database before running the application. This section introduces the [Data Seeding](../Data-Seeding.md) system of the ABP framework. You can skip this section if you don't want to create seed data, but it is suggested to follow it to learn this useful ABP Framework feature. -Create a class deriving from the `IDataSeedContributor` in the `*.Domain` project and copy the following code: +Create a class deriving from the `IDataSeedContributor` in the `*.Domain` project by copying the following code: ```csharp using System; @@ -278,18 +262,9 @@ Run the `Acme.BookStore.DbMigrator` application to update the database: ![bookstore-dbmigrator-on-solution](images/bookstore-dbmigrator-on-solution.png) -{{if DB == "EF"}} `.DbMigrator` is a console application that can be run to **migrate the database schema** and **seed the data** on **development** and **production** environments. -{{end}} - -{{if DB == "Mongo"}} - -While MongoDB **doesn't require** a database schema migration, it is still good to run this application since it **seeds the initial data** on the database. This application can be used on **development** and **production** environments. - -{{end}} - ## Create the Application Service The application layer is separated into two projects: @@ -426,7 +401,7 @@ namespace Acme.BookStore.Books ### BookAppService -It is time to implement the `IBookAppService` interface. Create a new class, named `BookAppService` in the `Books` namespace (folder) of the Acme.BookStore.Application project: +It is time to implement the `IBookAppService` interface. Create a new class, named `BookAppService` in the `Books` namespace (folder) of the `Acme.BookStore.Application` project: ````csharp using System; @@ -466,7 +441,7 @@ ABP can [**automagically**](../API/Auto-API-Controllers.md) configures your appl ### Swagger UI -The startup template is configured to run the [Swagger UI](https://swagger.io/tools/swagger-ui/) using the [Swashbuckle.AspNetCore](https://github.com/domaindrivendev/Swashbuckle.AspNetCore) library. Run the application by pressing `CTRL+F5` and navigate to `https://localhost:/swagger/` on your browser. (Replace `` with your own port number.) +The startup template is configured to run the [Swagger UI](https://swagger.io/tools/swagger-ui/) using the [Swashbuckle.AspNetCore](https://github.com/domaindrivendev/Swashbuckle.AspNetCore) library. Run the application ({{if UI=="MVC"}}`Acme.BookStore.Web`{{else}}`Acme.BookStore.HttpApi.Host`{{end}}) by pressing `CTRL+F5` and navigate to `https://localhost:/swagger/` on your browser. Replace `` with your own port number. You will see some built-in service endpoints as well as the `Book` service and its REST-style endpoints: diff --git a/docs/en/Tutorials/Part-10.md b/docs/en/Tutorials/Part-10.md index 05ed6e343e..2e0b1c4939 100644 --- a/docs/en/Tutorials/Part-10.md +++ b/docs/en/Tutorials/Part-10.md @@ -2,32 +2,15 @@ ````json //[doc-params] { - "UI": ["MVC","NG"], + "UI": ["MVC","Blazor","NG"], "DB": ["EF","Mongo"] } ```` -{{ -if UI == "MVC" - UI_Text="mvc" -else if UI == "NG" - UI_Text="angular" -else - UI_Text="?" -end -if DB == "EF" - DB_Text="Entity Framework Core" -else if DB == "Mongo" - DB_Text="MongoDB" -else - DB_Text="?" -end -}} - ## About This Tutorial In this tutorial series, you will build an ABP based web application named `Acme.BookStore`. This application is used to manage a list of books and their authors. It is developed using the following technologies: -* **{{DB_Text}}** as the ORM provider. +* **{{DB_Value}}** as the ORM provider. * **{{UI_Value}}** as the UI Framework. This tutorial is organized as the following parts; @@ -45,9 +28,10 @@ This tutorial is organized as the following parts; ### Download the Source Code -This tutorials has multiple versions based on your **UI** and **Database** preferences. We've prepared two combinations of the source code to be downloaded: +This tutorial has multiple versions based on your **UI** and **Database** preferences. We've prepared a few combinations of the source code to be downloaded: * [MVC (Razor Pages) UI with EF Core](https://github.com/abpframework/abp-samples/tree/master/BookStore-Mvc-EfCore) +* [Blazor UI with EF Core](https://github.com/abpframework/abp-samples/tree/master/BookStore-Blazor-EfCore) * [Angular UI with MongoDB](https://github.com/abpframework/abp-samples/tree/master/BookStore-Angular-MongoDb) ## Introduction @@ -66,21 +50,21 @@ public Guid AuthorId { get; set; } {{if DB=="EF"}} -> In this tutorial, we preferred to not add a **navigation property** to the `Author` entity (like `public Author Author { get; set; }`). This is due to follow the DDD best practices (rule: refer to other aggregates only by id). However, you can add such a navigation property and configure it for the EF Core. In this way, you don't need to write join queries while getting books with their entities (just like we will done below) which makes your application code simpler. +> In this tutorial, we preferred to not add a **navigation property** to the `Author` entity from the `Book` class (like `public Author Author { get; set; }`). This is due to follow the DDD best practices (rule: refer to other aggregates only by id). However, you can add such a navigation property and configure it for the EF Core. In this way, you don't need to write join queries while getting books with their authors (just like we will done below) which makes your application code simpler. {{end}} ## Database & Data Migration -Added a new, required `AuthorId` property to the `Book` entity. But, what about the existing books on the database? They currently don't have `AuthorId`s and this will be a problem when we try to run the application. +Added a new, required `AuthorId` property to the `Book` entity. But, **what about the existing books** on the database? They currently don't have `AuthorId`s and this will be a problem when we try to run the application. -This is a typical migration problem and the decision depends on your case; +This is a **typical migration problem** and the decision depends on your case; * If you haven't published your application to the production yet, you can just delete existing books in the database, or you can even delete the entire database in your development environment. -* You can do it programmatically on data migration or seed phase. +* You can update the existing data programmatically on data migration or seed phase. * You can manually handle it on the database. -We prefer to **delete the database** {{if DB=="EF"}}(run the `Drop-Database` in the *Package Manager Console*){{end}} since this is just an example project and data loss is not important. Since this topic is not related to the ABP Framework, we don't go deeper for all the scenarios. +We prefer to **delete the database** {{if DB=="EF"}}(you can run the `Drop-Database` in the *Package Manager Console*){{end}} since this is just an example project and data loss is not important. Since this topic is not related to the ABP Framework, we don't go deeper for all the scenarios. {{if DB=="EF"}} @@ -108,6 +92,8 @@ Run the following command in the Package Manager Console (of the Visual Studio) Add-Migration "Added_AuthorId_To_Book" ```` +> Ensure that the `Acme.BookStore.EntityFrameworkCore.DbMigrations` is the Default project and the `Acme.BookStore.DbMigrator` is the startup project, as always. + This should create a new migration class with the following code in its `Up` method: ````csharp @@ -222,6 +208,8 @@ namespace Acme.BookStore The only change is that we set the `AuthorId` properties of the `Book` entities. +> Delete existing books or delete the database before executing the `DbMigrator`. See the *Database & Data Migration* section above for more info. + {{if DB=="EF"}} You can now run the `.DbMigrator` console application to **migrate** the **database schema** and **seed** the initial data. @@ -299,7 +287,7 @@ namespace Acme.BookStore.Books } ```` -This will be used in a new method will be added to the `IBookAppService`. +This will be used in a new method that will be added to the `IBookAppService`. ### IBookAppService @@ -1068,4 +1056,112 @@ Open the `/src/app/book/book.component.html` and add the following form group ju That's all. Just run the application and try to create or edit an author. +{{end}} + +{{if UI == "Blazor"}} + +### The Book List + +It is very easy to show the *Author Name* in the book list. Open the `/Pages/Books.razor` file in the `Acme.BookStore.Blazor` project and add the following `DataGridColumn` definition just after the `Name` (book name) column: + +````xml + +```` + +When you run the application, you can see the *Author* column on the table: + +![blazor-bookstore-book-list-with-authors](images/blazor-bookstore-book-list-with-authors.png) + +### Create Book Modal + +Add the following field to the `@code` section of the `Books.razor` file: + +````csharp +IReadOnlyList authorList = Array.Empty(); +```` + +And fill it in the `OnInitializedAsync` method, by adding the following code to the end of the method: + +````csharp +authorList = (await AppService.GetAuthorLookupAsync()).Items; +```` + +The final `@code` block should be the following: + +````csharp +@code +{ + bool canCreateBook; + bool canEditBook; + bool canDeleteBook; + + //ADDED A NEW FIELD + IReadOnlyList authorList = Array.Empty(); + + protected override async Task OnInitializedAsync() + { + await base.OnInitializedAsync(); + + canCreateBook = await + AuthorizationService.IsGrantedAsync(BookStorePermissions.Books.Create); + canEditBook = await + AuthorizationService.IsGrantedAsync(BookStorePermissions.Books.Edit); + canDeleteBook = await + AuthorizationService.IsGrantedAsync(BookStorePermissions.Books.Delete); + + //GET AUTHORS + authorList = (await AppService.GetAuthorLookupAsync()).Items; + } +} +```` + +Finally, add the following `Field` definition into the `ModalBody` of the *Create* modal, as the first item, before the `Name` field: + +````xml + + @L["Author"] + + +```` + +This requires to add a new localization key to the `en.json` file: + +````js +"PickAnAuthor": "Pick an author" +```` + +You can run the application to see the *Author Selection* while creating a new book: + +![book-create-modal-with-author](images/book-create-modal-with-author.png) + +### Edit Book Modal + +Add the following `Field` definition into the `ModalBody` of the *Edit* modal, as the first item, before the `Name` field: + +````xml + + @L["Author"] + + +```` + +That's all. We are reusing the `authorList` defined for the *Create* modal. + {{end}} \ No newline at end of file diff --git a/docs/en/Tutorials/Part-2.md b/docs/en/Tutorials/Part-2.md index bcec504886..61271b1c93 100644 --- a/docs/en/Tutorials/Part-2.md +++ b/docs/en/Tutorials/Part-2.md @@ -2,32 +2,15 @@ ````json //[doc-params] { - "UI": ["MVC","NG"], + "UI": ["MVC","Blazor","NG"], "DB": ["EF","Mongo"] } ```` -{{ -if UI == "MVC" - UI_Text="mvc" -else if UI == "NG" - UI_Text="angular" -else - UI_Text="?" -end -if DB == "EF" - DB_Text="Entity Framework Core" -else if DB == "Mongo" - DB_Text="MongoDB" -else - DB_Text="?" -end -}} - ## About This Tutorial In this tutorial series, you will build an ABP based web application named `Acme.BookStore`. This application is used to manage a list of books and their authors. It is developed using the following technologies: -* **{{DB_Text}}** as the ORM provider. +* **{{DB_Value}}** as the ORM provider. * **{{UI_Value}}** as the UI Framework. This tutorial is organized as the following parts; @@ -45,9 +28,10 @@ This tutorial is organized as the following parts; ### Download the Source Code -This tutorial has multiple versions based on your **UI** and **Database** preferences. We've prepared two combinations of the source code to be downloaded: +This tutorial has multiple versions based on your **UI** and **Database** preferences. We've prepared a few combinations of the source code to be downloaded: * [MVC (Razor Pages) UI with EF Core](https://github.com/abpframework/abp-samples/tree/master/BookStore-Mvc-EfCore) +* [Blazor UI with EF Core](https://github.com/abpframework/abp-samples/tree/master/BookStore-Blazor-EfCore) * [Angular UI with MongoDB](https://github.com/abpframework/abp-samples/tree/master/BookStore-Angular-MongoDb) {{if UI == "MVC" && DB == "EF"}} @@ -115,7 +99,7 @@ We will use these dynamic proxy functions in the next sections to communicate to ## Localization -Before starting to the UI development, we first want to prepare the localization texts (you normally do when needed while developing your application). +Before starting to the UI development, we first want to prepare the localization texts (you normally do this when needed while developing your application). Localization texts are located under the `Localization/BookStore` folder of the `Acme.BookStore.Domain.Shared` project: @@ -341,9 +325,7 @@ You can run the application! The final UI of this part is shown below: This is a fully working, server side paged, sorted and localized table of books. -{{end}} - -{{if UI == "NG"}} +{{else if UI == "NG"}} ## Install NPM packages @@ -551,7 +533,137 @@ Now you can see the final result on your browser: ![Book list final result](./images/bookstore-book-list.png) -{{end}} +{{else if UI == "Blazor"}} + +## Create a Books Page + +It's time to create something visible and usable! Right click to the `Pages` folder under the `Acme.BookStore.Blazor` project and add a new **razor component**, named `Books.razor`: + +![blazor-add-books-component](images/blazor-add-books-component.png) + +Replace the contents of this component as shown below: + +````html +@page "/books" + +

Books

+ +@code { + +} +```` + +### Add Books Page to the Main Menu + +Open the `BookStoreMenuContributor` class in the `Blazor` project add the following code to the end of the `ConfigureMainMenuAsync` method: + +````csharp +context.Menu.AddItem( + new ApplicationMenuItem( + "BooksStore", + l["Menu:BookStore"], + icon: "fa fa-book" + ).AddItem( + new ApplicationMenuItem( + "BooksStore.Books", + l["Menu:Books"], + url: "/books" + ) + ) +); +```` + +Run the project, login to the application with the username `admin` and the password `1q2w3E*` and see the new menu item has been added to the main menu: + +![blazor-menu-bookstore](images/blazor-menu-bookstore.png) + +When you click to the Books menu item under the Book Store parent, you are being redirected to the new empty Books Page. + +### Book List + +We will use the [Blazorise library](https://blazorise.com/) as the UI component kit. It is a very powerful library that supports major HTML/CSS frameworks, including the Bootstrap. + +ABP Framework provides a generic base class, `BlazoriseCrudPageBase<...>`, to create CRUD style pages. This base class is compatible to the `ICrudAppService` that was used to build the `IBookAppService`. So, we can inherit from the `BlazoriseCrudPageBase` to automate the standard CRUD stuff. + +Open the `Books.razor` and replace the content as the following: + +````xml +@page "/books" +@using Volo.Abp.Application.Dtos +@using Volo.Abp.BlazoriseUI +@using Acme.BookStore.Books +@using Acme.BookStore.Localization +@using Microsoft.Extensions.Localization +@inject IStringLocalizer L +@inherits BlazoriseCrudPageBase + + + +

@L["Books"]

+
+ + + + + + + @L[$"Enum:BookType:{(int)context.Type}"] + + + + + @context.PublishDate.ToShortDateString() + + + + + + + @context.CreationTime.ToLongDateString() + + + + + +
+```` + +> If you see some syntax errors, you can ignore them if your application property built and run. Visual Studio still has some bugs with Blazor. + +* Inherited from the `BlazoriseCrudPageBase` which implements all the CRUD details for us. +* `Entities`, `TotalCount`, `PageSize`, `OnDataGridReadAsync` are defined in the base blass. +* Injected `IStringLocalizer` (as `L` object) and used for localization. + +While the code above pretty easy to understand, you can check the Blazorise [Card](https://blazorise.com/docs/components/card/) and [DataGrid](https://blazorise.com/docs/extensions/datagrid/) documents to understand them better. + +#### About the BlazoriseCrudPageBase + +We will continue to benefit from the `BlazoriseCrudPageBase` for the books page. You could just inject the `IBookAppService` and perform all the server side calls yourself (thanks to the [Dynamic C# HTTP API Client Proxy](../API/Dynamic-CSharp-API-Clients.md) system of the ABP Framework). We will do it manually for the authors page to demonstrate how to call server side HTTP APIs in your Blazor applications. + +## Run the Final Application + +You can run the application! The final UI of this part is shown below: + +![blazor-bookstore-book-list](images/blazor-bookstore-book-list.png) + +This is a fully working, server side paged, sorted and localized table of books. + +{{end # UI }} ## The Next Part diff --git a/docs/en/Tutorials/Part-3.md b/docs/en/Tutorials/Part-3.md index be3dd75d64..079b9e7cf8 100644 --- a/docs/en/Tutorials/Part-3.md +++ b/docs/en/Tutorials/Part-3.md @@ -2,32 +2,15 @@ ````json //[doc-params] { - "UI": ["MVC","NG"], + "UI": ["MVC","Blazor","NG"], "DB": ["EF","Mongo"] } ```` -{{ -if UI == "MVC" - UI_Text="mvc" -else if UI == "NG" - UI_Text="angular" -else - UI_Text="?" -end -if DB == "EF" - DB_Text="Entity Framework Core" -else if DB == "Mongo" - DB_Text="MongoDB" -else - DB_Text="?" -end -}} - ## About This Tutorial In this tutorial series, you will build an ABP based web application named `Acme.BookStore`. This application is used to manage a list of books and their authors. It is developed using the following technologies: -* **{{DB_Text}}** as the ORM provider. +* **{{DB_Value}}** as the ORM provider. * **{{UI_Value}}** as the UI Framework. This tutorial is organized as the following parts; @@ -45,9 +28,10 @@ This tutorial is organized as the following parts; ### Download the Source Code -This tutorial has multiple versions based on your **UI** and **Database** preferences. We've prepared two combinations of the source code to be downloaded: +This tutorial has multiple versions based on your **UI** and **Database** preferences. We've prepared a few combinations of the source code to be downloaded: * [MVC (Razor Pages) UI with EF Core](https://github.com/abpframework/abp-samples/tree/master/BookStore-Mvc-EfCore) +* [Blazor UI with EF Core](https://github.com/abpframework/abp-samples/tree/master/BookStore-Blazor-EfCore) * [Angular UI with MongoDB](https://github.com/abpframework/abp-samples/tree/master/BookStore-Angular-MongoDb) {{if UI == "MVC" && DB == "EF"}} @@ -1175,6 +1159,392 @@ Clicking the "Delete" action calls the `delete` method which then shows a confir {{end}} +{{if UI == "Blazor"}} + +## Creating a New Book + +In this section, you will learn how to create a new modal dialog form to create a new book. Since we've inherited from the `BlazoriseCrudPage`, we only need to develop the view part. + +### Add "New Button" Button + +Open the `Books.razor` and replace the `` section with the following code: + +````xml + + + +

@L["Books"]

+
+ + + + + +
+
+```` + +This will change the card header by adding a "New book" button to the right side: + +![blazor-add-book-button](images/blazor-add-book-button.png) + +Now, we can add a modal that will be opened when we click to the button. + +### Book Creation Modal + +Open the `Books.razor` and add the following code to the end of the page: + +````xml + + + + + @L["NewBook"] + + + + + @L["Name"] + + + + @L["Type"] + + + + @L["PublishDate"] + + + + @L["Price"] + + + + + + + + + +```` + +* `CreateModal` object, `CloseCreateModalAsync` and `CreateEntityAsync` method are defined by the base class. See the [Blazorise documentation](https://blazorise.com/docs/) if you want to understand the `Modal` and the other components. + +That's all. Run the application and try to add a new book: + +![blazor-new-book-modal](images/blazor-new-book-modal.png) + +## Updating a Book + +Editing a books is similar to the creating a new book. + +### Actions Dropdown + +Open the `Books.razor` and add the following `DataGridColumn` section inside the `DataGridColumns` as the first item: + +````xml + + + + + @L["Actions"] + + + + @L["Edit"] + + + + + +```` + +* `OpenEditModalAsync` is defined in the base class which takes the `Id` of the entity (book) to edit. + +This adds an "Actions" dropdown to all the books inside the `DataGrid` with an `Edit` action: + +![blazor-edit-book-action](images/blazor-edit-book-action.png) + +### Edit Modal + +We can now define a modal to edit the book. Add the following code to the end of the `Books.razor` page: + +````xml + + + + + @EditingEntity.Name + + + + + @L["Name"] + + + + @L["Type"] + + + + @L["PublishDate"] + + + + @L["Price"] + + + + + + + + + +```` + +### AutoMapper Configuration + +The base `BlazoriseCrudPage` uses the [object to object mapping](../Object-To-Object-Mapping.md) system to convert an incoming `BookDto` object to a `CreateUpdateBookDto` object. So, we need to define the mapping. + +Open the `BookStoreBlazorAutoMapperProfile` inside the `Acme.BookStore.Blazor` project and change the content as the following: + +````csharp +using Acme.BookStore.Books; +using AutoMapper; + +namespace Acme.BookStore.Blazor +{ + public class BookStoreBlazorAutoMapperProfile : Profile + { + public BookStoreBlazorAutoMapperProfile() + { + CreateMap(); + } + } +} +```` + +* We've just added the `CreateMap();` line to define the mapping. + +### Test the Editing Modal + +You can now run the application and try to edit a book. + +![blazor-edit-book-modal](images/blazor-edit-book-modal.png) + +## Deleting a Book + +Open the `Books.razor` page and add the following `DropdownItem` under the "Edit" action inside the "Actions" `DropdownMenu`: + +````xml + + @L["Delete"] + +```` + +* `DeleteEntityAsync` is defined in the base class. + +Run the application and try to delete a book. + +## Full CRUD UI Code + +Here the complete code to create the book management CRUD page, that has been developed in the last two parts: + +````xml +@page "/books" +@using Volo.Abp.Application.Dtos +@using Volo.Abp.BlazoriseUI +@using Acme.BookStore.Books +@using Acme.BookStore.Localization +@using Microsoft.Extensions.Localization +@inject IStringLocalizer L +@inherits BlazoriseCrudPageBase + + + + + +

@L["Books"]

+
+ + + + + +
+
+ + + + + + + + @L["Actions"] + + + + @L["Edit"] + + + @L["Delete"] + + + + + + + + + @L[$"Enum:BookType:{(int) context.Type}"] + + + + + @context.PublishDate.ToShortDateString() + + + + + + + @context.CreationTime.ToLongDateString() + + + + + +
+ + + + + + @L["NewBook"] + + + + + @L["Name"] + + + + @L["Type"] + + + + @L["PublishDate"] + + + + @L["Price"] + + + + + + + + + + + + + + + @EditingEntity.Name + + + + + @L["Name"] + + + + @L["Type"] + + + + @L["PublishDate"] + + + + @L["Price"] + + + + + + + + + +```` + +{{end}} + ## The Next Part See the [next part](Part-4.md) of this tutorial. diff --git a/docs/en/Tutorials/Part-4.md b/docs/en/Tutorials/Part-4.md index 2868df8ba6..9c31f4fd3c 100644 --- a/docs/en/Tutorials/Part-4.md +++ b/docs/en/Tutorials/Part-4.md @@ -2,32 +2,15 @@ ````json //[doc-params] { - "UI": ["MVC","NG"], + "UI": ["MVC","Blazor","NG"], "DB": ["EF","Mongo"] } ```` -{{ -if UI == "MVC" - UI_Text="mvc" -else if UI == "NG" - UI_Text="angular" -else - UI_Text="?" -end -if DB == "EF" - DB_Text="Entity Framework Core" -else if DB == "Mongo" - DB_Text="MongoDB" -else - DB_Text="?" -end -}} - ## About This Tutorial In this tutorial series, you will build an ABP based web application named `Acme.BookStore`. This application is used to manage a list of books and their authors. It is developed using the following technologies: -* **{{DB_Text}}** as the ORM provider. +* **{{DB_Value}}** as the ORM provider. * **{{UI_Value}}** as the UI Framework. This tutorial is organized as the following parts; @@ -45,9 +28,10 @@ This tutorial is organized as the following parts; ### Download the Source Code -This tutorial has multiple versions based on your **UI** and **Database** preferences. We've prepared two combinations of the source code to be downloaded: +This tutorial has multiple versions based on your **UI** and **Database** preferences. We've prepared a few combinations of the source code to be downloaded: * [MVC (Razor Pages) UI with EF Core](https://github.com/abpframework/abp-samples/tree/master/BookStore-Mvc-EfCore) +* [Blazor UI with EF Core](https://github.com/abpframework/abp-samples/tree/master/BookStore-Blazor-EfCore) * [Angular UI with MongoDB](https://github.com/abpframework/abp-samples/tree/master/BookStore-Angular-MongoDb) {{if UI == "MVC" && DB == "EF"}} @@ -62,7 +46,9 @@ This part is also recorded as a video tutorial and ** The test projects are configured to use **SQLite in-memory** as the database. A separate database instance is created and seeded (with the data seed system) to prepare a fresh database for every test. +> The test projects are configured to use **SQLite in-memory** as the database. A separate database instance is created and seeded (with the [data seed system](../Data-Seeding.md)) to prepare a fresh database for every test. {{else if DB=="Mongo"}} -> **[Mongo2Go](https://github.com/Mongo2Go/Mongo2Go)** library is used to mock the MongoDB database. A separate database instance is created and seeded (with the data seed system) to prepare a fresh database for every test. +> **[Mongo2Go](https://github.com/Mongo2Go/Mongo2Go)** library is used to mock the MongoDB database. A separate database instance is created and seeded (with the [data seed system](../Data-Seeding.md)) to prepare a fresh database for every test. {{end}} diff --git a/docs/en/Tutorials/Part-5.md b/docs/en/Tutorials/Part-5.md index 5b2dfc0431..74d2c25d70 100644 --- a/docs/en/Tutorials/Part-5.md +++ b/docs/en/Tutorials/Part-5.md @@ -2,32 +2,15 @@ ````json //[doc-params] { - "UI": ["MVC","NG"], + "UI": ["MVC","Blazor","NG"], "DB": ["EF","Mongo"] } ```` -{{ -if UI == "MVC" - UI_Text="mvc" -else if UI == "NG" - UI_Text="angular" -else - UI_Text="?" -end -if DB == "EF" - DB_Text="Entity Framework Core" -else if DB == "Mongo" - DB_Text="MongoDB" -else - DB_Text="?" -end -}} - ## About This Tutorial In this tutorial series, you will build an ABP based web application named `Acme.BookStore`. This application is used to manage a list of books and their authors. It is developed using the following technologies: -* **{{DB_Text}}** as the ORM provider. +* **{{DB_Value}}** as the ORM provider. * **{{UI_Value}}** as the UI Framework. This tutorial is organized as the following parts; @@ -45,9 +28,10 @@ This tutorial is organized as the following parts; ### Download the Source Code -This tutorial has multiple versions based on your **UI** and **Database** preferences. We've prepared two combinations of the source code to be downloaded: +This tutorial has multiple versions based on your **UI** and **Database** preferences. We've prepared a few combinations of the source code to be downloaded: * [MVC (Razor Pages) UI with EF Core](https://github.com/abpframework/abp-samples/tree/master/BookStore-Mvc-EfCore) +* [Blazor UI with EF Core](https://github.com/abpframework/abp-samples/tree/master/BookStore-Blazor-EfCore) * [Angular UI with MongoDB](https://github.com/abpframework/abp-samples/tree/master/BookStore-Angular-MongoDb) {{if UI == "MVC" && DB == "EF"}} @@ -145,6 +129,8 @@ Go to the *Administration -> Identity -> Roles* page, select *Permissions* actio Grant the permissions you want and save the modal. +> **Tip**: New permissions are automatically granted to the admin role if you run the `Acme.BookStore.DbMigrator` application. + ## Authorization Now, you can use the permissions to authorize the book management. @@ -186,6 +172,8 @@ namespace Acme.BookStore.Books Added code to the constructor. Base `CrudAppService` automatically uses these permissions on the CRUD operations. This makes the **application service** secure, but also makes the **HTTP API** secure since this service is automatically used as an HTTP API as explained before (see [auto API controllers](../API/Auto-API-Controllers.md)). +> You will see the declarative authorization, using the `[Authorize(...)]` attribute, later while developing the author management functionality. + {{if UI == "MVC"}} ### Razor Page @@ -327,6 +315,64 @@ if (await context.IsGrantedAsync(BookStorePermissions.Books.Default)) } ```` +You also need to add `async` keyword to the `ConfigureMenuAsync` method and re-arrange the return values. The final `BookStoreMenuContributor` class should be the following: + +````csharp +using System.Threading.Tasks; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Localization; +using Acme.BookStore.Localization; +using Acme.BookStore.MultiTenancy; +using Acme.BookStore.Permissions; +using Volo.Abp.TenantManagement.Web.Navigation; +using Volo.Abp.UI.Navigation; + +namespace Acme.BookStore.Web.Menus +{ + public class BookStoreMenuContributor : IMenuContributor + { + public async Task ConfigureMenuAsync(MenuConfigurationContext context) + { + if (context.Menu.Name == StandardMenus.Main) + { + await ConfigureMainMenuAsync(context); + } + } + + private async Task ConfigureMainMenuAsync(MenuConfigurationContext context) + { + if (!MultiTenancyConsts.IsEnabled) + { + var administration = context.Menu.GetAdministration(); + administration.TryRemoveMenuItem(TenantManagementMenuNames.GroupName); + } + + var l = context.GetLocalizer(); + + context.Menu.Items.Insert(0, new ApplicationMenuItem("BookStore.Home", l["Menu:Home"], "~/")); + + var bookStoreMenu = new ApplicationMenuItem( + "BooksStore", + l["Menu:BookStore"], + icon: "fa fa-book" + ); + + context.Menu.AddItem(bookStoreMenu); + + //CHECK the PERMISSION + if (await context.IsGrantedAsync(BookStorePermissions.Books.Default)) + { + bookStoreMenu.AddItem(new ApplicationMenuItem( + "BooksStore.Books", + l["Menu:Books"], + url: "/Books" + )); + } + } + } +} +```` + {{else if UI == "NG"}} ### Angular Guard Configuration @@ -412,6 +458,197 @@ Open the `/src/app/book/book.component.html` file and replace the edit and delet {{end}} +{{else if UI == "Blazor"}} + +### Authorize the Razor Component + +Open the `/Pages/Books.razor` file in the `Acme.BookStore.Blazor` project and add an `Authorize` attribute just after the `@page` directive, as shown below: + +````html +@page "/books" +@attribute [Authorize(BookStorePermissions.Books.Default)] +@using Acme.BookStore.Permissions +@using Microsoft.AspNetCore.Authorization +... +```` + +Adding this attribute prevents to enter this page if the current hasn't logged in or hasn't granted for the given permission. In case of attempt, the user is redirected to the login page. + +### Show/Hide the Actions + +The book management page has a *New Book* button and *Edit* and *Delete* actions for each book. We should hide these buttons/actions if the current user has not granted for the related permissions. + +#### Inject the IAuthorizationService + +Inject the `IAuthorizationService` into the `Books.razor`: + +````csharp +@inject IAuthorizationService AuthorizationService +```` + +#### Get the Permissions On Initialization + +Add the following code block to the end of the `Books.razor` file: + +````csharp +@code +{ + bool canCreateBook; + bool canEditBook; + bool canDeleteBook; + + protected override async Task OnInitializedAsync() + { + await base.OnInitializedAsync(); + + canCreateBook =await AuthorizationService.IsGrantedAsync(BookStorePermissions.Books.Create); + canEditBook = await AuthorizationService.IsGrantedAsync(BookStorePermissions.Books.Edit); + canDeleteBook = await AuthorizationService.IsGrantedAsync(BookStorePermissions.Books.Delete); + } +} +```` + +We will use these `bool` fields to check the permissions. + +> **Blazor Tip**: While adding the C# code into a `@code` block is fine for small code parts, it is suggested to use the code behind approach to develop a more maintainable code base when the code block becomes longer. We will use this approach for the authors part. + +#### Hide the New Book Button + +Wrap the *New Book* button by an `if` block as shown below: + +````xml +@if (canCreateBook) +{ + +} +```` + +#### Hide the Edit/Delete Actions + +As similar to the *New Book* button, we can use `if` blocks to conditionally show/hide the *Edit* and *Delete* actions: + +````xml +@if (canEditBook) +{ + + @L["Edit"] + +} +@if (canDeleteBook) +{ + + @L["Delete"] + +} +```` + +#### About the Permission Caching + +You can run and test the permissions. Remove a book related permission from the admin role to see the related button/action disappears from the UI. + +However, ABP Framework caches the permissions of the current user in the client side. So, when you change a permission for yourself, you need to manually **refresh the page** to take the effect. If you don't refresh and try to use the prohibited action you get an HTTP 403 (forbidden) response from the server. + +> Changing a permission for a role or user immediately available on the server side. So, this cache system doesn't cause any security problem. + +### Menu Item + +Even we have secured all the layers of the book management page, it is still visible on the main menu of the application. We should hide the menu item if the current user has no permission. + +Open the `BookStoreMenuContributor` class in the `Acme.BookStore.Blazor` project, find the code block below: + +````csharp +context.Menu.AddItem( + new ApplicationMenuItem( + "BooksStore", + l["Menu:BookStore"], + icon: "fa fa-book" + ).AddItem( + new ApplicationMenuItem( + "BooksStore.Books", + l["Menu:Books"], + url: "/books" + ) + ) +); +```` + +And replace this code block with the following: + +````csharp +var bookStoreMenu = new ApplicationMenuItem( + "BooksStore", + l["Menu:BookStore"], + icon: "fa fa-book" +); + +context.Menu.AddItem(bookStoreMenu); + +//CHECK the PERMISSION +if (await context.IsGrantedAsync(BookStorePermissions.Books.Default)) +{ + bookStoreMenu.AddItem(new ApplicationMenuItem( + "BooksStore.Books", + l["Menu:Books"], + url: "/books" + )); +} +```` + +You also need to add `async` keyword to the `ConfigureMenuAsync` method and re-arrange the return values. The final `BookStoreMenuContributor` class should be the following: + +````csharp +using System.Threading.Tasks; +using Acme.BookStore.Localization; +using Acme.BookStore.Permissions; +using Volo.Abp.UI.Navigation; + +namespace Acme.BookStore.Blazor +{ + public class BookStoreMenuContributor : IMenuContributor + { + public async Task ConfigureMenuAsync(MenuConfigurationContext context) + { + if(context.Menu.DisplayName != StandardMenus.Main) + { + return; + } + + var l = context.GetLocalizer(); + + context.Menu.Items.Insert( + 0, + new ApplicationMenuItem( + "BookStore.Home", + l["Menu:Home"], + "/", + icon: "fas fa-home" + ) + ); + + var bookStoreMenu = new ApplicationMenuItem( + "BooksStore", + l["Menu:BookStore"], + icon: "fa fa-book" + ); + + context.Menu.AddItem(bookStoreMenu); + + if (await context.IsGrantedAsync(BookStorePermissions.Books.Default)) + { + bookStoreMenu.AddItem(new ApplicationMenuItem( + "BooksStore.Books", + l["Menu:Books"], + url: "/books" + )); + } + } + } +} +```` + +{{end}} + ## The Next Part See the [next part](Part-6.md) of this tutorial. \ No newline at end of file diff --git a/docs/en/Tutorials/Part-6.md b/docs/en/Tutorials/Part-6.md index b1b38f18dc..69c6574520 100644 --- a/docs/en/Tutorials/Part-6.md +++ b/docs/en/Tutorials/Part-6.md @@ -2,32 +2,15 @@ ````json //[doc-params] { - "UI": ["MVC","NG"], + "UI": ["MVC","Blazor","NG"], "DB": ["EF","Mongo"] } ```` -{{ -if UI == "MVC" - UI_Text="mvc" -else if UI == "NG" - UI_Text="angular" -else - UI_Text="?" -end -if DB == "EF" - DB_Text="Entity Framework Core" -else if DB == "Mongo" - DB_Text="MongoDB" -else - DB_Text="?" -end -}} - ## About This Tutorial In this tutorial series, you will build an ABP based web application named `Acme.BookStore`. This application is used to manage a list of books and their authors. It is developed using the following technologies: -* **{{DB_Text}}** as the ORM provider. +* **{{DB_Value}}** as the ORM provider. * **{{UI_Value}}** as the UI Framework. This tutorial is organized as the following parts; @@ -45,9 +28,10 @@ This tutorial is organized as the following parts; ### Download the Source Code -This tutorials has multiple versions based on your **UI** and **Database** preferences. We've prepared two combinations of the source code to be downloaded: +This tutorial has multiple versions based on your **UI** and **Database** preferences. We've prepared a few combinations of the source code to be downloaded: * [MVC (Razor Pages) UI with EF Core](https://github.com/abpframework/abp-samples/tree/master/BookStore-Mvc-EfCore) +* [Blazor UI with EF Core](https://github.com/abpframework/abp-samples/tree/master/BookStore-Blazor-EfCore) * [Angular UI with MongoDB](https://github.com/abpframework/abp-samples/tree/master/BookStore-Angular-MongoDb) ## Introduction @@ -242,16 +226,7 @@ This is a unique string represents the error code thrown by your application and "BookStore:00001": "There is already an author with the same name: {name}" ```` -Then open the `BookStoreDomainSharedModule` and add the following code block inside the `ConfigureServices` method: - -````csharp -Configure(options => -{ - options.MapCodeNamespace("BookStore", typeof(BookStoreResource)); -}); -```` - -Whenever you throw an `AuthorAlreadyExistsException`, the end use will see a nice error message on the UI. +Whenever you throw an `AuthorAlreadyExistsException`, the end use will see a this message on the UI. ## IAuthorRepository diff --git a/docs/en/Tutorials/Part-7.md b/docs/en/Tutorials/Part-7.md index 81fd07f1bf..32c9f6b9a4 100644 --- a/docs/en/Tutorials/Part-7.md +++ b/docs/en/Tutorials/Part-7.md @@ -2,32 +2,15 @@ ````json //[doc-params] { - "UI": ["MVC","NG"], + "UI": ["MVC","Blazor","NG"], "DB": ["EF","Mongo"] } ```` -{{ -if UI == "MVC" - UI_Text="mvc" -else if UI == "NG" - UI_Text="angular" -else - UI_Text="?" -end -if DB == "EF" - DB_Text="Entity Framework Core" -else if DB == "Mongo" - DB_Text="MongoDB" -else - DB_Text="?" -end -}} - ## About This Tutorial In this tutorial series, you will build an ABP based web application named `Acme.BookStore`. This application is used to manage a list of books and their authors. It is developed using the following technologies: -* **{{DB_Text}}** as the ORM provider. +* **{{DB_Value}}** as the ORM provider. * **{{UI_Value}}** as the UI Framework. This tutorial is organized as the following parts; @@ -45,9 +28,10 @@ This tutorial is organized as the following parts; ### Download the Source Code -This tutorials has multiple versions based on your **UI** and **Database** preferences. We've prepared two combinations of the source code to be downloaded: +This tutorial has multiple versions based on your **UI** and **Database** preferences. We've prepared a few combinations of the source code to be downloaded: * [MVC (Razor Pages) UI with EF Core](https://github.com/abpframework/abp-samples/tree/master/BookStore-Mvc-EfCore) +* [Blazor UI with EF Core](https://github.com/abpframework/abp-samples/tree/master/BookStore-Blazor-EfCore) * [Angular UI with MongoDB](https://github.com/abpframework/abp-samples/tree/master/BookStore-Angular-MongoDb) ## Introduction @@ -86,7 +70,7 @@ This is just like done for the `Book` entity before, so no need to explain again ## Create a new Database Migration -Open the **Package Manager Console** on Visual Studio and ensure that the **Default project** is `Acme.BookStore.EntityFrameworkCore.DbMigrations` in the Package Manager Console, as shown on the picture below. Also, set the `Acme.BookStore.Web` as the startup project (right click it on the solution explorer and click to "Set as Startup Project"). +Open the **Package Manager Console** on Visual Studio and ensure that the **Default project** is `Acme.BookStore.EntityFrameworkCore.DbMigrations` in the Package Manager Console, as shown on the picture below. Also, set the `Acme.BookStore.Web` (or `Acme.BookStore.HttpApi.Host`, depending on your solution) as the **startup project** (right click it on the solution explorer and click to "Set as Startup Project"). Run the following command to create a new database migration: diff --git a/docs/en/Tutorials/Part-8.md b/docs/en/Tutorials/Part-8.md index fc10a799f2..b7c805c17e 100644 --- a/docs/en/Tutorials/Part-8.md +++ b/docs/en/Tutorials/Part-8.md @@ -2,32 +2,15 @@ ````json //[doc-params] { - "UI": ["MVC","NG"], + "UI": ["MVC","Blazor","NG"], "DB": ["EF","Mongo"] } ```` -{{ -if UI == "MVC" - UI_Text="mvc" -else if UI == "NG" - UI_Text="angular" -else - UI_Text="?" -end -if DB == "EF" - DB_Text="Entity Framework Core" -else if DB == "Mongo" - DB_Text="MongoDB" -else - DB_Text="?" -end -}} - ## About This Tutorial In this tutorial series, you will build an ABP based web application named `Acme.BookStore`. This application is used to manage a list of books and their authors. It is developed using the following technologies: -* **{{DB_Text}}** as the ORM provider. +* **{{DB_Value}}** as the ORM provider. * **{{UI_Value}}** as the UI Framework. This tutorial is organized as the following parts; @@ -45,9 +28,10 @@ This tutorial is organized as the following parts; ### Download the Source Code -This tutorials has multiple versions based on your **UI** and **Database** preferences. We've prepared two combinations of the source code to be downloaded: +This tutorial has multiple versions based on your **UI** and **Database** preferences. We've prepared a few combinations of the source code to be downloaded: * [MVC (Razor Pages) UI with EF Core](https://github.com/abpframework/abp-samples/tree/master/BookStore-Mvc-EfCore) +* [Blazor UI with EF Core](https://github.com/abpframework/abp-samples/tree/master/BookStore-Blazor-EfCore) * [Angular UI with MongoDB](https://github.com/abpframework/abp-samples/tree/master/BookStore-Angular-MongoDb) ## Introduction @@ -318,7 +302,7 @@ public async Task UpdateAsync(Guid id, UpdateAuthorDto input) {{if DB == "EF"}} -> **EF Core tip**: Entity Framework Core has a **change tracking** system and **automatically saves** any change to an entity at the end of the unit of work (You can simply think that the ABP Framework automatically calls `SaveChanges` at the end of the method). So, it will work as expected even if you don't call the `_authorRepository.UpdateAsync(...)` in the end of the method. If you don't consider to change the EF Core later, you can just remove this line. +> **EF Core Tip**: Entity Framework Core has a **change tracking** system and **automatically saves** any change to an entity at the end of the unit of work (You can simply think that the ABP Framework automatically calls `SaveChanges` at the end of the method). So, it will work as expected even if you don't call the `_authorRepository.UpdateAsync(...)` in the end of the method. If you don't consider to change the EF Core later, you can just remove this line. {{end}} diff --git a/docs/en/Tutorials/Part-9.md b/docs/en/Tutorials/Part-9.md index 0d78d584b8..841d2fb3cb 100644 --- a/docs/en/Tutorials/Part-9.md +++ b/docs/en/Tutorials/Part-9.md @@ -2,32 +2,15 @@ ````json //[doc-params] { - "UI": ["MVC","NG"], + "UI": ["MVC","Blazor","NG"], "DB": ["EF","Mongo"] } ```` -{{ -if UI == "MVC" - UI_Text="mvc" -else if UI == "NG" - UI_Text="angular" -else - UI_Text="?" -end -if DB == "EF" - DB_Text="Entity Framework Core" -else if DB == "Mongo" - DB_Text="MongoDB" -else - DB_Text="?" -end -}} - ## About This Tutorial In this tutorial series, you will build an ABP based web application named `Acme.BookStore`. This application is used to manage a list of books and their authors. It is developed using the following technologies: -* **{{DB_Text}}** as the ORM provider. +* **{{DB_Value}}** as the ORM provider. * **{{UI_Value}}** as the UI Framework. This tutorial is organized as the following parts; @@ -45,18 +28,19 @@ This tutorial is organized as the following parts; ### Download the Source Code -This tutorials has multiple versions based on your **UI** and **Database** preferences. We've prepared two combinations of the source code to be downloaded: +This tutorial has multiple versions based on your **UI** and **Database** preferences. We've prepared a few combinations of the source code to be downloaded: * [MVC (Razor Pages) UI with EF Core](https://github.com/abpframework/abp-samples/tree/master/BookStore-Mvc-EfCore) +* [Blazor UI with EF Core](https://github.com/abpframework/abp-samples/tree/master/BookStore-Blazor-EfCore) * [Angular UI with MongoDB](https://github.com/abpframework/abp-samples/tree/master/BookStore-Angular-MongoDb) ## Introduction -This part explains how to create a CRUD page for the `Author` entity introduced in previous parts. +This part explains how to create a CRUD page for the `Author` entity introduced in the previous parts. {{if UI == "MVC"}} -## The Book List Page +## The Authors List Page Create a new razor page, `Index.cshtml` under the `Pages/Authors` folder of the `Acme.BookStore.Web` project and change the content as given below. @@ -509,7 +493,7 @@ That's all! You can run the application and try to edit an author. {{else if UI == "NG"}} -## The Author List Page, Create & Delete Authors +## The Author Management Page Run the following command line to create a new module, named `AuthorModule` in the root folder of the angular application: @@ -848,6 +832,353 @@ That's all! This is a fully working CRUD page, you can create, edit and delete a {{end}} +{{if UI == "Blazor"}} + +## The Author Management Page + +### Authors Razor Component + +Create a new Razor Component Page, `/Pages/Authors.razor`, in the `Acme.BookStore.Blazor` project with the following content: + +````xml +@page "/authors" +@using Acme.BookStore.Authors +@using Acme.BookStore.Localization +@using Microsoft.AspNetCore.Authorization +@using Microsoft.Extensions.Localization +@using Volo.Abp.ObjectMapping +@inject IAuthorAppService AuthorAppService +@inject IStringLocalizer L +@inject IAuthorizationService AuthorizationService +@inject IUiMessageService UiMessageService +@inject IObjectMapper ObjectMapper + + + + +

@L["Authors"]

+
+ + + @if (CanCreateAuthor) + { + + } + + +
+
+ + + + + + + + @L["Actions"] + + + @if (CanEditAuthor) + { + + @L["Edit"] + + } + @if (CanDeleteAuthor) + { + + @L["Delete"] + + } + + + + + + + + @context.BirthDate.ToShortDateString() + + + + + +
+ + + + + + @L["NewAuthor"] + + + + + @L["Name"] + + + + @L["BirthDate"] + + + + @L["ShortBio"] + + + + + + + + + + + + + + + @EditingAuthor.Name + + + + + @L["Name"] + + + + @L["BirthDate"] + + + + @L["ShortBio"] + + + + + + + + + +```` + +* This code is similar to the `Books.razor`, except it doesn't inherit from the `BlazorisePageBase`, but uses its own implementation. +* Injects the `IAuthorAppService` to consume the server side HTTP APIs from the UI. We can directly inject application service interfaces and use just like regular method calls by the help of [Dynamic C# HTTP API Client Proxy System](../API/Dynamic-CSharp-API-Clients.md), which performs REST API calls for us. See the `Authors` class below to see the usage. +* Injects the `IAuthorizationService` to check [permissions](../Authorization.md). +* Injects the `IObjectMapper` for [object to object mapping](../Object-To-Object-Mapping.md). + +Create a new code behind file, `Authors.razor.cs`, under the `Pages` folder, with the following content: + +````csharp +using System; +using System.Collections.Generic; +using System.Linq; +using System.Threading.Tasks; +using Acme.BookStore.Authors; +using Acme.BookStore.Permissions; +using Blazorise; +using Blazorise.DataGrid; +using Microsoft.AspNetCore.Authorization; +using Volo.Abp.Application.Dtos; + +namespace Acme.BookStore.Blazor.Pages +{ + public partial class Authors + { + private IReadOnlyList AuthorList { get; set; } + + private int PageSize { get; } = LimitedResultRequestDto.DefaultMaxResultCount; + private int CurrentPage { get; set; } + private string CurrentSorting { get; set; } + private int TotalCount { get; set; } + + private bool CanCreateAuthor { get; set; } + private bool CanEditAuthor { get; set; } + private bool CanDeleteAuthor { get; set; } + + private CreateAuthorDto NewAuthor { get; set; } + + private Guid EditingAuthorId { get; set; } + private UpdateAuthorDto EditingAuthor { get; set; } + + private Modal CreateAuthorModal { get; set; } + private Modal EditAuthorModal { get; set; } + + public Authors() + { + NewAuthor = new CreateAuthorDto(); + EditingAuthor = new UpdateAuthorDto(); + } + + protected override async Task OnInitializedAsync() + { + await SetPermissionsAsync(); + await GetAuthorsAsync(); + } + + private async Task SetPermissionsAsync() + { + CanCreateAuthor = await AuthorizationService + .IsGrantedAsync(BookStorePermissions.Authors.Create); + + CanEditAuthor = await AuthorizationService + .IsGrantedAsync(BookStorePermissions.Authors.Edit); + + CanDeleteAuthor = await AuthorizationService + .IsGrantedAsync(BookStorePermissions.Authors.Delete); + } + + private async Task GetAuthorsAsync() + { + var result = await AuthorAppService.GetListAsync( + new GetAuthorListDto + { + MaxResultCount = PageSize, + SkipCount = CurrentPage * PageSize, + Sorting = CurrentSorting + } + ); + + AuthorList = result.Items; + TotalCount = (int)result.TotalCount; + } + + private async Task OnDataGridReadAsync(DataGridReadDataEventArgs e) + { + CurrentSorting = e.Columns + .Where(c => c.Direction != SortDirection.None) + .Select(c => c.Field + (c.Direction == SortDirection.Descending ? " DESC" : "")) + .JoinAsString(","); + CurrentPage = e.Page - 1; + + await GetAuthorsAsync(); + + StateHasChanged(); + } + + private void OpenCreateAuthorModal() + { + NewAuthor = new CreateAuthorDto(); + CreateAuthorModal.Show(); + } + + private void CloseCreateAuthorModal() + { + CreateAuthorModal.Hide(); + } + + private void OpenEditAuthorModal(AuthorDto author) + { + EditingAuthorId = author.Id; + EditingAuthor = ObjectMapper.Map(author); + EditAuthorModal.Show(); + } + + private async Task DeleteAuthorAsync(AuthorDto author) + { + var confirmMessage = L["AuthorDeletionConfirmationMessage", author.Name]; + if (!await UiMessageService.ConfirmAsync(confirmMessage)) + { + return; + } + + await AuthorAppService.DeleteAsync(author.Id); + await GetAuthorsAsync(); + } + + private void CloseEditAuthorModal() + { + EditAuthorModal.Hide(); + } + + private async Task CreateAuthorAsync() + { + await AuthorAppService.CreateAsync(NewAuthor); + await GetAuthorsAsync(); + CreateAuthorModal.Hide(); + } + + private async Task UpdateAuthorAsync() + { + await AuthorAppService.UpdateAsync(EditingAuthorId, EditingAuthor); + await GetAuthorsAsync(); + EditAuthorModal.Hide(); + } + } +} +```` + +This class typically defines the properties and methods used by the `Authors.razor` page. + +### Object Mapping + +`Authors` class uses the `IObjectMapper` in the `OpenEditAuthorModal` method. So, we need to define this mapping. + +Open the `BookStoreBlazorAutoMapperProfile.cs` in the `Acme.BookStore.Blazor` project and add the following mapping code in the constructor: + +````csharp +CreateMap(); +```` + +You will need to declare a `using Acme.BookStore.Authors;` statement to the beginning of the file. + +### Add to the Main Menu + +Open the `BookStoreMenuContributor.cs` in the `Acme.BookStore.Blazor` project and add the following code to the end of the `ConfigureMainMenuAsync` method: + +````csharp +if (await context.IsGrantedAsync(BookStorePermissions.Authors.Default)) +{ + bookStoreMenu.AddItem(new ApplicationMenuItem( + "BooksStore.Authors", + l["Menu:Authors"], + url: "/authors" + )); +} +```` + +### Localizations + +We should complete the localizations we've used above. Open the `en.json` file under the `Localization/BookStore` folder of the `Acme.BookStore.Domain.Shared` project and add the following entries: + +````json +"Menu:Authors": "Authors", +"Authors": "Authors", +"AuthorDeletionConfirmationMessage": "Are you sure to delete the author '{0}'?", +"BirthDate": "Birth date", +"NewAuthor": "New author" +```` + +{{end}} + ## The Next Part See the [next part](Part-10.md) of this tutorial. \ No newline at end of file diff --git a/docs/en/Tutorials/images/blazor-add-book-button.png b/docs/en/Tutorials/images/blazor-add-book-button.png new file mode 100644 index 0000000000..58a607d3b1 Binary files /dev/null and b/docs/en/Tutorials/images/blazor-add-book-button.png differ diff --git a/docs/en/Tutorials/images/blazor-add-books-component.png b/docs/en/Tutorials/images/blazor-add-books-component.png new file mode 100644 index 0000000000..ec0412d31e Binary files /dev/null and b/docs/en/Tutorials/images/blazor-add-books-component.png differ diff --git a/docs/en/Tutorials/images/blazor-bookstore-book-list-with-authors.png b/docs/en/Tutorials/images/blazor-bookstore-book-list-with-authors.png new file mode 100644 index 0000000000..75c5306c3c Binary files /dev/null and b/docs/en/Tutorials/images/blazor-bookstore-book-list-with-authors.png differ diff --git a/docs/en/Tutorials/images/blazor-bookstore-book-list.png b/docs/en/Tutorials/images/blazor-bookstore-book-list.png new file mode 100644 index 0000000000..91450f47c2 Binary files /dev/null and b/docs/en/Tutorials/images/blazor-bookstore-book-list.png differ diff --git a/docs/en/Tutorials/images/blazor-edit-book-action.png b/docs/en/Tutorials/images/blazor-edit-book-action.png new file mode 100644 index 0000000000..f1179dae58 Binary files /dev/null and b/docs/en/Tutorials/images/blazor-edit-book-action.png differ diff --git a/docs/en/Tutorials/images/blazor-edit-book-modal.png b/docs/en/Tutorials/images/blazor-edit-book-modal.png new file mode 100644 index 0000000000..e63e796d34 Binary files /dev/null and b/docs/en/Tutorials/images/blazor-edit-book-modal.png differ diff --git a/docs/en/Tutorials/images/blazor-menu-bookstore.png b/docs/en/Tutorials/images/blazor-menu-bookstore.png new file mode 100644 index 0000000000..f9f334aa1d Binary files /dev/null and b/docs/en/Tutorials/images/blazor-menu-bookstore.png differ diff --git a/docs/en/Tutorials/images/blazor-new-book-modal.png b/docs/en/Tutorials/images/blazor-new-book-modal.png new file mode 100644 index 0000000000..dd284a0ffd Binary files /dev/null and b/docs/en/Tutorials/images/blazor-new-book-modal.png differ diff --git a/docs/en/Tutorials/images/book-create-modal-with-author.png b/docs/en/Tutorials/images/book-create-modal-with-author.png new file mode 100644 index 0000000000..5e662553aa Binary files /dev/null and b/docs/en/Tutorials/images/book-create-modal-with-author.png differ diff --git a/docs/en/UI/Angular/Environment.md b/docs/en/UI/Angular/Environment.md index 402e110f94..3cf0aae395 100644 --- a/docs/en/UI/Angular/Environment.md +++ b/docs/en/UI/Angular/Environment.md @@ -54,7 +54,7 @@ Everything else will be sent to `"https://localhost:8080"` * `rootNamespace` **(new)** : Root namespace of the related API. e.g. Acme.BookStore -## Application +## Application ```typescript export interface Application { @@ -69,7 +69,7 @@ Everything else will be sent to `"https://localhost:8080"` * `baseUrl`: [For detailed information](./Multi-Tenancy.md#domain-tenant-resolver) -## AuthConfig +## AuthConfig For authentication, we use angular-oauth2-oidc. Please check their [docs](https://github.com/manfredsteyer/angular-oauth2-oidc) out diff --git a/docs/en/docs-params.json b/docs/en/docs-params.json index 23d079f9bb..f28a3b49ef 100644 --- a/docs/en/docs-params.json +++ b/docs/en/docs-params.json @@ -5,6 +5,7 @@ "displayName": "UI", "values": { "MVC": "MVC / Razor Pages", + "Blazor": "Blazor", "NG": "Angular" } }, diff --git a/docs/zh-Hans/Getting-Started.md b/docs/zh-Hans/Getting-Started.md index bf46816d32..c6b3bd70df 100644 --- a/docs/zh-Hans/Getting-Started.md +++ b/docs/zh-Hans/Getting-Started.md @@ -153,6 +153,19 @@ abp new Acme.BookStore{{if UI == "NG"}} -u angular {{end}}{{if DB == "Mongo"}} - > 请参阅[应用程序模板文档](Startup-Templates/Application.md)详细了解解决方案结构. +{{ if DB == "Mongo" }} + +> [启动模板](Startup-templates/Index.md)默认在 `.MongoDB` 项目中**禁用**了工作单元事务. 如果你的MongoDB服务器支持事务,你可以手动启用工作单元的事务: + + ```csharp + Configure(options => + { + options.TransactionBehavior = UnitOfWorkTransactionBehavior.Enabled; + }); + ``` + +{{ end }} + ## 创建数据库 ### 连接字符串 diff --git a/docs/zh-Hans/MongoDB.md b/docs/zh-Hans/MongoDB.md index 64df7d180b..c90b9b5740 100644 --- a/docs/zh-Hans/MongoDB.md +++ b/docs/zh-Hans/MongoDB.md @@ -233,6 +233,19 @@ public class BookService > 重要:如果你想访问MongoDB API,你需要在你的项目中引用`Volo.Abp.MongoDB`.这会破坏封装,但在这种情况下,这就是你想要的. +#### 事务 + +MongoDB在4.0版本开始支持事务, ABP在3.2版本加入了对MongoDb事务的支持. 如果你升级到3.2版本,需要将[MongoDbSchemaMigrator](https://github.com/abpframework/abp/blob/dev/templates/app/aspnet-core/src/MyCompanyName.MyProjectName.MongoDB/MongoDb/MongoDbMyProjectNameDbSchemaMigrator.cs)添加到你的 `.MongoDB` 项目中. + +[启动模板](Startup-templates/Index.md)默认在 `.MongoDB` 项目中**禁用**了工作单元事务. 如果你的MongoDB服务器支持事务,你可以手动启用工作单元的事务: + +```csharp +Configure(options => +{ + options.TransactionBehavior = UnitOfWorkTransactionBehavior.Enabled; +}); +``` + #### 高级主题 ##### 设置默认的仓储类 diff --git a/docs/zh-Hans/Multi-Tenancy.md b/docs/zh-Hans/Multi-Tenancy.md index 3e65a97cef..863e9cfb4b 100644 --- a/docs/zh-Hans/Multi-Tenancy.md +++ b/docs/zh-Hans/Multi-Tenancy.md @@ -305,6 +305,7 @@ Volo.Abp.AspNetCore.MultiTenancy 添加了下面这些租户解析器,从当前W * **CurrentUserTenantResolveContributor**: 如果当前用户已登录,从当前用户的声明中获取租户Id. **出于安全考虑,应该始终将其做为第一个Contributor**. * **QueryStringTenantResolveContributor**: 尝试从query string参数中获取当前租户,默认参数名为"__tenant". +* **FormTenantResolveContributor**: 尝试从form参数中获取当前租户,默认参数名为"__tenant". * **RouteTenantResolveContributor**:尝试从当前路由中获取(URL路径),默认是变量名是"__tenant".所以,如果你的路由中定义了这个变量,就可以从路由中确定当前租户. * **HeaderTenantResolveContributor**: 尝试从HTTP header中获取当前租户,默认的header名称是"__tenant". * **CookieTenantResolveContributor**: 尝试从当前cookie中获取当前租户.默认的Cookie名称是"__tenant". diff --git a/docs/zh-Hans/Tutorials/Part-1.md b/docs/zh-Hans/Tutorials/Part-1.md index 101835559b..99a7e3d9fb 100644 --- a/docs/zh-Hans/Tutorials/Part-1.md +++ b/docs/zh-Hans/Tutorials/Part-1.md @@ -270,18 +270,8 @@ namespace Acme.BookStore ![bookstore-dbmigrator-on-solution](images/bookstore-dbmigrator-on-solution.png) -{{if DB == "EF"}} - `.DbMigrator` 是一个控制台使用程序,可以在**开发**和**生产**环境**迁移数据库架构**和**初始化种子数据**. -{{end}} - -{{if DB == "Mongo"}} - -尽管MongoDB**不需要**数据库架构迁移,但仍建议运行该应用程序,因为它可以在数据库上播种初始数据. 可以在**开发**和**生产**环境中使用. - -{{end}} - ## 创建应用程序 应用程序层由两个分离的项目组成: diff --git a/framework/src/Volo.Abp.AspNetCore.MultiTenancy/Volo/Abp/AspNetCore/MultiTenancy/FormTenantResolveContributor.cs b/framework/src/Volo.Abp.AspNetCore.MultiTenancy/Volo/Abp/AspNetCore/MultiTenancy/FormTenantResolveContributor.cs index 5e70559f0c..f334b4d434 100644 --- a/framework/src/Volo.Abp.AspNetCore.MultiTenancy/Volo/Abp/AspNetCore/MultiTenancy/FormTenantResolveContributor.cs +++ b/framework/src/Volo.Abp.AspNetCore.MultiTenancy/Volo/Abp/AspNetCore/MultiTenancy/FormTenantResolveContributor.cs @@ -12,7 +12,7 @@ namespace Volo.Abp.AspNetCore.MultiTenancy protected override string GetTenantIdOrNameFromHttpContextOrNull(ITenantResolveContext context, HttpContext httpContext) { - if (httpContext.Request == null || !httpContext.Request.Form.Any()) + if (httpContext.Request == null || !httpContext.Request.HasFormContentType || !httpContext.Request.Form.Any()) { return null; } diff --git a/framework/src/Volo.Abp.AspNetCore.Mvc.UI.Theme.Shared.Demo/Views/Components/Themes/Shared/Demos/BordersDemo/Default.cshtml b/framework/src/Volo.Abp.AspNetCore.Mvc.UI.Theme.Shared.Demo/Views/Components/Themes/Shared/Demos/BordersDemo/Default.cshtml index 281f6c73ed..7733f51fdf 100644 --- a/framework/src/Volo.Abp.AspNetCore.Mvc.UI.Theme.Shared.Demo/Views/Components/Themes/Shared/Demos/BordersDemo/Default.cshtml +++ b/framework/src/Volo.Abp.AspNetCore.Mvc.UI.Theme.Shared.Demo/Views/Components/Themes/Shared/Demos/BordersDemo/Default.cshtml @@ -9,11 +9,11 @@ - - - - - + + + + + diff --git a/framework/src/Volo.Abp.AspNetCore.Mvc.UI.Theme.Shared/wwwroot/libs/abp/aspnetcore-mvc-ui-theme-shared/datatables/datatables-extensions.js b/framework/src/Volo.Abp.AspNetCore.Mvc.UI.Theme.Shared/wwwroot/libs/abp/aspnetcore-mvc-ui-theme-shared/datatables/datatables-extensions.js index 8d85f6f6d8..f7defe4f79 100644 --- a/framework/src/Volo.Abp.AspNetCore.Mvc.UI.Theme.Shared/wwwroot/libs/abp/aspnetcore-mvc-ui-theme-shared/datatables/datatables-extensions.js +++ b/framework/src/Volo.Abp.AspNetCore.Mvc.UI.Theme.Shared/wwwroot/libs/abp/aspnetcore-mvc-ui-theme-shared/datatables/datatables-extensions.js @@ -15,19 +15,19 @@ return; } - var getVisibilityValue = function (visibilityField, record) { + var getVisibilityValue = function (visibilityField, record, tableInstance) { if (visibilityField === undefined) { return true; } if (abp.utils.isFunction(visibilityField)) { - return visibilityField(record); + return visibilityField(record, tableInstance); } else { return visibilityField; } }; - var _createDropdownItem = function (record, fieldItem) { + var _createDropdownItem = function (record, fieldItem, tableInstance) { var $li = $('
  • '); var $a = $(''); @@ -50,14 +50,14 @@ if (!$(this).closest('li').hasClass('disabled')) { if (fieldItem.confirmMessage) { - abp.message.confirm(fieldItem.confirmMessage({ record: record })) + abp.message.confirm(fieldItem.confirmMessage({ record: record, table: tableInstance })) .done(function (accepted) { if (accepted) { - fieldItem.action({ record: record }); + fieldItem.action({ record: record, table: tableInstance }); } }); } else { - fieldItem.action({ record: record }); + fieldItem.action({ record: record, table: tableInstance }); } } }); @@ -67,17 +67,60 @@ return $li; }; - var _createButtonDropdown = function (record, field) { + var _createButtonDropdown = function (record, field, tableInstance) { + if(field.items.length === 1) { + var firstItem = field.items[0]; + if (!getVisibilityValue(firstItem.visible, record, tableInstance)) { + return ""; + } + + var $button = $(''); + + if (firstItem.displayNameHtml) { + $button.html(firstItem.text); + } else { + if (firstItem.icon !== undefined && firstItem.icon) { + $button.append($("").addClass("fa fa-" + firstItem.icon + " mr-1")); + } else if (firstItem.iconClass) { + $button.append($("").addClass(firstItem.iconClass + " mr-1")); + } + $button.append(firstItem.text); + } + + if (firstItem.enabled && !firstItem.enabled({ record: record, table: tableInstance })) { + $button.addClass('disabled'); + } + + if (firstItem.action) { + $button.click(function (e) { + e.preventDefault(); + + if (!$(this).hasClass('disabled')) { + if (firstItem.confirmMessage) { + abp.message.confirm(firstItem.confirmMessage({ record: record, table: tableInstance })) + .done(function (accepted) { + if (accepted) { + firstItem.action({ record: record, table: tableInstance }); + } + }); + } else { + firstItem.action({ record: record, table: tableInstance }); + } + } + }); + } + + return $button; + } + var $container = $('
    ') .addClass('dropdown') .addClass('action-button'); var $dropdownButton = $('