From b42ccdee63fc568314b65befddc3135fe77f681b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Halil=20=C4=B0brahim=20Kalkan?= Date: Wed, 30 Nov 2022 16:42:38 +0300 Subject: [PATCH 01/16] Initial Configuring Production document --- docs/en/Deployment/Configuring-Production.md | 23 ++++++++++++++++++++ docs/en/Deployment/Index.md | 1 + docs/en/docs-nav.json | 4 ++++ 3 files changed, 28 insertions(+) create mode 100644 docs/en/Deployment/Configuring-Production.md diff --git a/docs/en/Deployment/Configuring-Production.md b/docs/en/Deployment/Configuring-Production.md new file mode 100644 index 0000000000..b9b9253ca7 --- /dev/null +++ b/docs/en/Deployment/Configuring-Production.md @@ -0,0 +1,23 @@ +# Configuring for Production + +ABP Framework has a lot of options to configure and fine-tune its features. They are all explained their own documents. Default values for these options are pretty well for most of the deployment environments. However, you may need to care about some options based on how you've structured your deployment environment. In this document, we will highlight these kind of options. So, it is highly recommended to read this document to not have unexpected behaviors in your system in production. + +## Distributed Cache Prefix + +ABP's [distributed cache infrastructure](../Caching.md) provides an option to set a key prefix for all of your data saved into your distributed cache provider. The default value of this option is not set (it is `null`). If you are using a distributed cache server that is concurrently used by different applications, then you can set a prefix value to isolate an application's cache data from others. + +````csharp +Configure(options => +{ + options.KeyPrefix = "MyCrmApp"; +}); +```` + +That's all. ABP, then will add this prefix to all of your cache keys in your application as along as you use ABP's `IDistributedCache` or `IDistributedCache` services. See the [caching documentation](../Caching.md) if you are new to the distributed caching. + +> **Warning #1**: If you use ASP.NET Core's standard `IDistributedCache` service, it's your responsibility to add the key prefix (you can get the value by injecting `IOptions`). ABP can not do it. + +> **Warning #2**: Even if you never used distributed caching in your own codebase, ABP still uses it for some systems. So, you should always configure this prefix if your server is shared among multiple systems. + +> **Warning #3**: Some of the ABP's startup templates are pre-configured to set a prefix value for the distributed cache. So, please check your application code if it is already configured. + diff --git a/docs/en/Deployment/Index.md b/docs/en/Deployment/Index.md index 6503f8b664..852efa3d43 100644 --- a/docs/en/Deployment/Index.md +++ b/docs/en/Deployment/Index.md @@ -6,4 +6,5 @@ However, there are some topics that you should care about when you are deploying ## Guides +* [Configuring for production](Configuring-Production.md): Notes for some important configurations for production environments. * [Deploying to a clustered environment](Clustered-Environment.md): Explains how to configure your application when you want to run multiple instances of your application concurrently. diff --git a/docs/en/docs-nav.json b/docs/en/docs-nav.json index ef6b0cad07..d7cf2a5389 100644 --- a/docs/en/docs-nav.json +++ b/docs/en/docs-nav.json @@ -1299,6 +1299,10 @@ "text": "Deployment", "path": "Deployment/Index.md", "items": [ + { + "text": "Configuring for Production", + "path": "Deployment/Configuring-Production.md" + }, { "text": "Deploying to a Clustered Environment", "path": "Deployment/Clustered-Environment.md" From c5fac16161337abc27e221f8000fe4f5e2466cb6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Halil=20=C4=B0brahim=20Kalkan?= Date: Wed, 30 Nov 2022 16:49:40 +0300 Subject: [PATCH 02/16] Added section: Distributed Lock Prefix --- docs/en/Deployment/Configuring-Production.md | 23 +++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/docs/en/Deployment/Configuring-Production.md b/docs/en/Deployment/Configuring-Production.md index b9b9253ca7..160885c5d0 100644 --- a/docs/en/Deployment/Configuring-Production.md +++ b/docs/en/Deployment/Configuring-Production.md @@ -4,7 +4,7 @@ ABP Framework has a lot of options to configure and fine-tune its features. They ## Distributed Cache Prefix -ABP's [distributed cache infrastructure](../Caching.md) provides an option to set a key prefix for all of your data saved into your distributed cache provider. The default value of this option is not set (it is `null`). If you are using a distributed cache server that is concurrently used by different applications, then you can set a prefix value to isolate an application's cache data from others. +ABP's [distributed cache infrastructure](../Caching.md) provides an option to set a key prefix for all of your data saved into your distributed cache provider. The default value of this option is not set (it is `null`). If you are using a distributed cache server that shared by different applications, then you can set a prefix value to isolate an application's cache data from others. ````csharp Configure(options => @@ -13,11 +13,28 @@ Configure(options => }); ```` -That's all. ABP, then will add this prefix to all of your cache keys in your application as along as you use ABP's `IDistributedCache` or `IDistributedCache` services. See the [caching documentation](../Caching.md) if you are new to the distributed caching. +That's all. ABP, then will add this prefix to all of your cache keys in your application as along as you use ABP's `IDistributedCache` or `IDistributedCache` services. See the [Caching documentation](../Caching.md) if you are new to the distributed caching. > **Warning #1**: If you use ASP.NET Core's standard `IDistributedCache` service, it's your responsibility to add the key prefix (you can get the value by injecting `IOptions`). ABP can not do it. -> **Warning #2**: Even if you never used distributed caching in your own codebase, ABP still uses it for some systems. So, you should always configure this prefix if your server is shared among multiple systems. +> **Warning #2**: Even if you have never used distributed caching in your own codebase, ABP still uses it for some features. So, you should always configure this prefix if your caching server is shared among multiple systems. > **Warning #3**: Some of the ABP's startup templates are pre-configured to set a prefix value for the distributed cache. So, please check your application code if it is already configured. +## Distributed Lock Prefix + +ABP's [distributed locking infrastructure](../Distributed-Locking.md) provides an option to set a prefix for all keys you are using in the distributed lock server. The default value of this option is not set (it is `null`). If you are using a distributed lock server that is shared by different applications, then you can set a prefix value to isolate an application's locks from others. + +````csharp +Configure(options => +{ + options.KeyPrefix = "MyCrmApp"; +}); +```` + +That's all. ABP, then will add this prefix to all of your keys in your application. See the [Distributed Locking documentation](../Distributed-Locking.md) if you are new to the distributed locking. + +> **Warning #1**: Even if you have never used distributed locking in your own codebase, ABP still uses it for some features. So, you should always configure this prefix if your distributed lock server is shared among multiple systems. + +> **Warning #2**: Some of the ABP's startup templates are pre-configured to set a prefix value for the distributed locking. So, please check your application code if it is already configured. + From b22d701ecc5a0dea54b2eafadf6f545ec35bc6c3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Halil=20=C4=B0brahim=20Kalkan?= Date: Wed, 30 Nov 2022 17:43:12 +0300 Subject: [PATCH 03/16] Update Configuring-Production.md --- docs/en/Deployment/Configuring-Production.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/en/Deployment/Configuring-Production.md b/docs/en/Deployment/Configuring-Production.md index 160885c5d0..5cf39f1d60 100644 --- a/docs/en/Deployment/Configuring-Production.md +++ b/docs/en/Deployment/Configuring-Production.md @@ -19,7 +19,9 @@ That's all. ABP, then will add this prefix to all of your cache keys in your app > **Warning #2**: Even if you have never used distributed caching in your own codebase, ABP still uses it for some features. So, you should always configure this prefix if your caching server is shared among multiple systems. -> **Warning #3**: Some of the ABP's startup templates are pre-configured to set a prefix value for the distributed cache. So, please check your application code if it is already configured. +> **Warning #3**: If you are building a microservice system, then you will have multiple applications that share the same distributed cache server. In such systems, all applications (or services) normally should use the same cache prefix, because you want all the applications use the same cache data to have consistency between applications. + +> **Warning #4**: Some of the ABP's startup templates are pre-configured to set a prefix value for the distributed cache. So, please check your application code if it is already configured. ## Distributed Lock Prefix @@ -36,5 +38,7 @@ That's all. ABP, then will add this prefix to all of your keys in your applicati > **Warning #1**: Even if you have never used distributed locking in your own codebase, ABP still uses it for some features. So, you should always configure this prefix if your distributed lock server is shared among multiple systems. -> **Warning #2**: Some of the ABP's startup templates are pre-configured to set a prefix value for the distributed locking. So, please check your application code if it is already configured. +> **Warning #2**: If you are building a microservice system, then you will have multiple applications that share the same distributed locking server. In such systems, all applications (or services) normally should use the same lock prefix, because you want to lock your resources globally in your system. + +> **Warning #3**: Some of the ABP's startup templates are pre-configured to set a prefix value for the distributed locking. So, please check your application code if it is already configured. From c20859560d79be972d22d1556da202cfe579412f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Halil=20=C4=B0brahim=20Kalkan?= Date: Wed, 30 Nov 2022 17:52:47 +0300 Subject: [PATCH 04/16] Added section: Email Sender --- docs/en/Deployment/Configuring-Production.md | 25 ++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/docs/en/Deployment/Configuring-Production.md b/docs/en/Deployment/Configuring-Production.md index 5cf39f1d60..2078cc0cb4 100644 --- a/docs/en/Deployment/Configuring-Production.md +++ b/docs/en/Deployment/Configuring-Production.md @@ -42,3 +42,28 @@ That's all. ABP, then will add this prefix to all of your keys in your applicati > **Warning #3**: Some of the ABP's startup templates are pre-configured to set a prefix value for the distributed locking. So, please check your application code if it is already configured. +## Email Sender + +ABP's [Email Sending](../Emailing.md) system abstracts sending emails from your application and module code and allows you to configure the email provider and settings in a single place. + +Email service is configured to write email contents to the standard [application log](../Logging.md) in development environment. You should configure the email settings to be able to send emails to users in your production environment. + +Please see the [Email Sending](../Emailing.md) document to learn how to configure its settings to really send emails. + +> **Warning**: If you don't configure the email settings, you will get errors while trying to send emails. For example, the [Account module](../Modules/Account.md)'s *Password Reset* feature sends email to the users to reset their passwords if they forget it. + +## SMS Sender + +TODO + +## BLOB Provider + +TODO + +## String Encryption + +TODO + +## Swagger + +TODO From 828756a10253c6b507215dab5b047a648c24645c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Halil=20=C4=B0brahim=20Kalkan?= Date: Wed, 30 Nov 2022 18:02:04 +0300 Subject: [PATCH 05/16] Added section: SMS Sender --- docs/en/Deployment/Configuring-Production.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/docs/en/Deployment/Configuring-Production.md b/docs/en/Deployment/Configuring-Production.md index 2078cc0cb4..197cd21d2f 100644 --- a/docs/en/Deployment/Configuring-Production.md +++ b/docs/en/Deployment/Configuring-Production.md @@ -54,7 +54,21 @@ Please see the [Email Sending](../Emailing.md) document to learn how to configur ## SMS Sender -TODO +ABP's [SMS Sending abstraction](https://docs.abp.io/en/abp/latest/SMS-Sending) provides a unified interface to send SMS to users. However, its implementation is left to you. Because, typically a paid SMS service is used to send SMS, and ABP doesn't depend on a specific SMS provider. + +So, if you are using the `ISmsSender` service, you must implement it yourself, as shown in the following code block: + +````csharp +public class MySmsSender : ISmsSender, ITransientDependency +{ + public async Task SendAsync(SmsMessage smsMessage) + { + // TODO: Send it using your provider... + } +} +```` + +> [ABP Commercial](https://commercial.abp.io/) provide a [Twilio SMS Module](https://docs.abp.io/en/commercial/latest/modules/twilio-sms) as a pre-built integration with the popular [Twilio](https://www.twilio.com/) platform. ## BLOB Provider From 882d5b7e62d6e0d1ca89783b2611e7854463ab21 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Halil=20=C4=B0brahim=20Kalkan?= Date: Wed, 30 Nov 2022 18:18:55 +0300 Subject: [PATCH 06/16] Added BLOB Provider section --- docs/en/Deployment/Configuring-Production.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/en/Deployment/Configuring-Production.md b/docs/en/Deployment/Configuring-Production.md index 197cd21d2f..fce19ba273 100644 --- a/docs/en/Deployment/Configuring-Production.md +++ b/docs/en/Deployment/Configuring-Production.md @@ -72,7 +72,11 @@ public class MySmsSender : ISmsSender, ITransientDependency ## BLOB Provider -TODO +If you use ABP's [BLOB Storing](https://docs.abp.io/en/abp/latest/Blob-Storing) infrastructure, you should care about the BLOB provider in your production environment. For example, if you use the [File System](../Blob-Storing-File-System.md) provider and running your application in a Docker container, you should configure a volume map for the BLOB storage path. Otherwise, your data is lost when the container has been restarted. Also, File System is not a good provider for production if you have a [clustered deployment](Clustered-Environment.md) or a microservice system. + +Check the [BLOB Storing](../Blob-Storing.md) document to see all the available BLOG storage providers. + +> **Warning**: Even if you don't directly use the BLOB Storage system, a module you are depending may use it. For example, ABP Commercial's [File Management](https://docs.abp.io/en/commercial/latest/modules/file-management) module stores file contents, and the [Account](https://docs.abp.io/en/commercial/latest/modules/account) module stores user profile pictures in the BLOB Storage system. So, be careful on the BLOB Storing configuration in production. Note that ABP Commercial uses the [Database Provider](../Blob-Storing-Database.md) as pre-configured BLOB storage provider, which works in production without any problem, but you may still want to use another provider. ## String Encryption From c29995772c7275ac55558ca1c2e2db97d1ac25df Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Halil=20=C4=B0brahim=20Kalkan?= Date: Wed, 30 Nov 2022 20:42:39 +0300 Subject: [PATCH 07/16] Added sections --- docs/en/Deployment/Configuring-Production.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/docs/en/Deployment/Configuring-Production.md b/docs/en/Deployment/Configuring-Production.md index fce19ba273..6b038d444b 100644 --- a/docs/en/Deployment/Configuring-Production.md +++ b/docs/en/Deployment/Configuring-Production.md @@ -72,15 +72,24 @@ public class MySmsSender : ISmsSender, ITransientDependency ## BLOB Provider -If you use ABP's [BLOB Storing](https://docs.abp.io/en/abp/latest/Blob-Storing) infrastructure, you should care about the BLOB provider in your production environment. For example, if you use the [File System](../Blob-Storing-File-System.md) provider and running your application in a Docker container, you should configure a volume map for the BLOB storage path. Otherwise, your data is lost when the container has been restarted. Also, File System is not a good provider for production if you have a [clustered deployment](Clustered-Environment.md) or a microservice system. +If you use ABP's [BLOB Storing](https://docs.abp.io/en/abp/latest/Blob-Storing) infrastructure, you should care about the BLOB provider in your production environment. For example, if you use the [File System](../Blob-Storing-File-System.md) provider and running your application in a Docker container, you should configure a volume mapping for the BLOB storage path. Otherwise, your data is lost when the container has been restarted. Also, File System is not a good provider for production if you have a [clustered deployment](Clustered-Environment.md) or a microservice system. -Check the [BLOB Storing](../Blob-Storing.md) document to see all the available BLOG storage providers. +Check the [BLOB Storing](../Blob-Storing.md) document to see all the available BLOB storage providers. > **Warning**: Even if you don't directly use the BLOB Storage system, a module you are depending may use it. For example, ABP Commercial's [File Management](https://docs.abp.io/en/commercial/latest/modules/file-management) module stores file contents, and the [Account](https://docs.abp.io/en/commercial/latest/modules/account) module stores user profile pictures in the BLOB Storage system. So, be careful on the BLOB Storing configuration in production. Note that ABP Commercial uses the [Database Provider](../Blob-Storing-Database.md) as pre-configured BLOB storage provider, which works in production without any problem, but you may still want to use another provider. ## String Encryption -TODO +ABP's [`IStringEncryptionService` Service](../String-Encryption.md) simply encrypts and decrypts given strings based on a password phrase. You should configure the `AbpStringEncryptionOptions` options for the production with a strong password and keep it as a secret. You can also configure the other properties of that options class. See the following example: + +````csharp +Configure(options => +{ + options.DefaultPassPhrase = "gs5nTT042HAL4it1"; +}); +```` + +Note that ABP CLI automatically sets the password to a random value on a new project creation. However, it is stored in the `appsettings.json` file and generally added to your source control. It is suggested to use [User Secrets](https://learn.microsoft.com/en-us/aspnet/core/security/app-secrets) or [Environment Variables](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration) to set that value. ## Swagger From d215d5faca4ef671b9da8b873d5cf2abde0a2a12 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Halil=20=C4=B0brahim=20Kalkan?= Date: Wed, 30 Nov 2022 20:53:18 +0300 Subject: [PATCH 08/16] Update Configuring-Production.md --- docs/en/Deployment/Configuring-Production.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/en/Deployment/Configuring-Production.md b/docs/en/Deployment/Configuring-Production.md index 6b038d444b..40fcca62fa 100644 --- a/docs/en/Deployment/Configuring-Production.md +++ b/docs/en/Deployment/Configuring-Production.md @@ -91,6 +91,10 @@ Configure(options => Note that ABP CLI automatically sets the password to a random value on a new project creation. However, it is stored in the `appsettings.json` file and generally added to your source control. It is suggested to use [User Secrets](https://learn.microsoft.com/en-us/aspnet/core/security/app-secrets) or [Environment Variables](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration) to set that value. -## Swagger +## The Swagger UI -TODO +ABP's startup solution templates come with the [Swagger UI](https://swagger.io/) pre-installed. Swagger is a pretty standard and useful tool to discover and test your HTTP APIs on a built-in UI that is embedded into your application or service. It is typically used in development environment, but you may want to enable it on staging or production environments too. + +While you will always secure your HTTP APIs with other techniques (like the [Authorization](../Authorization.md) system), allowing malicious software and people to easily discover your HTTP API endpoint details can be considered as a security problem for some systems. So, be careful while taking the decision of enabling or disabling Swagger for the production environment. + +> You may also want to see the [ABP Swagger integration](../API/Swagger-Integration.md) document. From 97ccf603c4fdd0dfc902edb245903461965aee16 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Halil=20=C4=B0brahim=20Kalkan?= Date: Wed, 30 Nov 2022 20:58:36 +0300 Subject: [PATCH 09/16] Change warnings --- docs/en/Deployment/Configuring-Production.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/en/Deployment/Configuring-Production.md b/docs/en/Deployment/Configuring-Production.md index 40fcca62fa..1e562473ba 100644 --- a/docs/en/Deployment/Configuring-Production.md +++ b/docs/en/Deployment/Configuring-Production.md @@ -15,13 +15,13 @@ Configure(options => That's all. ABP, then will add this prefix to all of your cache keys in your application as along as you use ABP's `IDistributedCache` or `IDistributedCache` services. See the [Caching documentation](../Caching.md) if you are new to the distributed caching. -> **Warning #1**: If you use ASP.NET Core's standard `IDistributedCache` service, it's your responsibility to add the key prefix (you can get the value by injecting `IOptions`). ABP can not do it. +> **Warning**: If you use ASP.NET Core's standard `IDistributedCache` service, it's your responsibility to add the key prefix (you can get the value by injecting `IOptions`). ABP can not do it. -> **Warning #2**: Even if you have never used distributed caching in your own codebase, ABP still uses it for some features. So, you should always configure this prefix if your caching server is shared among multiple systems. +> **Warning**: Even if you have never used distributed caching in your own codebase, ABP still uses it for some features. So, you should always configure this prefix if your caching server is shared among multiple systems. -> **Warning #3**: If you are building a microservice system, then you will have multiple applications that share the same distributed cache server. In such systems, all applications (or services) normally should use the same cache prefix, because you want all the applications use the same cache data to have consistency between applications. +> **Warning**: If you are building a microservice system, then you will have multiple applications that share the same distributed cache server. In such systems, all applications (or services) normally should use the same cache prefix, because you want all the applications use the same cache data to have consistency between applications. -> **Warning #4**: Some of the ABP's startup templates are pre-configured to set a prefix value for the distributed cache. So, please check your application code if it is already configured. +> **Warning**: Some of the ABP's startup templates are pre-configured to set a prefix value for the distributed cache. So, please check your application code if it is already configured. ## Distributed Lock Prefix @@ -36,11 +36,11 @@ Configure(options => That's all. ABP, then will add this prefix to all of your keys in your application. See the [Distributed Locking documentation](../Distributed-Locking.md) if you are new to the distributed locking. -> **Warning #1**: Even if you have never used distributed locking in your own codebase, ABP still uses it for some features. So, you should always configure this prefix if your distributed lock server is shared among multiple systems. +> **Warning**: Even if you have never used distributed locking in your own codebase, ABP still uses it for some features. So, you should always configure this prefix if your distributed lock server is shared among multiple systems. -> **Warning #2**: If you are building a microservice system, then you will have multiple applications that share the same distributed locking server. In such systems, all applications (or services) normally should use the same lock prefix, because you want to lock your resources globally in your system. +> **Warning**: If you are building a microservice system, then you will have multiple applications that share the same distributed locking server. In such systems, all applications (or services) normally should use the same lock prefix, because you want to lock your resources globally in your system. -> **Warning #3**: Some of the ABP's startup templates are pre-configured to set a prefix value for the distributed locking. So, please check your application code if it is already configured. +> **Warning**: Some of the ABP's startup templates are pre-configured to set a prefix value for the distributed locking. So, please check your application code if it is already configured. ## Email Sender From b6e28c17851d03d468fe5d0f156daac66bff30ee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Halil=20=C4=B0brahim=20Kalkan?= Date: Thu, 1 Dec 2022 10:02:57 +0300 Subject: [PATCH 10/16] Document for: Separated localization endpoint from configuration endpoint --- docs/en/API/Application-Configuration.md | 7 ++--- docs/en/API/Application-Localization.md | 33 ++++++++++++++++++++++++ 2 files changed, 37 insertions(+), 3 deletions(-) create mode 100644 docs/en/API/Application-Localization.md diff --git a/docs/en/API/Application-Configuration.md b/docs/en/API/Application-Configuration.md index 8441459e02..5f2f2a9c6d 100644 --- a/docs/en/API/Application-Configuration.md +++ b/docs/en/API/Application-Configuration.md @@ -2,13 +2,14 @@ ABP Framework provides a pre-built and standard endpoint that contains some useful information about the application/service. Here, the list of some fundamental information at this endpoint: -* [Localization](../Localization.md) values, supported and the current language of the application. -* Available and granted [policies](../Authorization.md) (permissions) for the current user. +* Granted [policies](../Authorization.md) (permissions) for the current user. * [Setting](../Settings.md) values for the current user. * Info about the [current user](../CurrentUser.md) (like id and user name). * Info about the current [tenant](../Multi-Tenancy.md) (like id and name). * [Time zone](../Timing.md) information for the current user and the [clock](../Timing.md) type of the application. +> If you have started with ABP's startup solution templates and using one of the official UI options, then all these are set up for you and you don't need to know these details. However, if you are building a UI application from scratch, you may want to know this endpoint. + ## HTTP API If you navigate to the `/api/abp/application-configuration` URL of an ABP Framework based web application or HTTP Service, you can access the configuration as a JSON object. This endpoint is useful to create the client of your application. @@ -19,5 +20,5 @@ For ASP.NET Core MVC (Razor Pages) applications, the same configuration values a See the [JavaScript API document](../UI/AspNetCore/JavaScript-API/Index.md) for the ASP.NET Core UI. -Other UI types provide services native to the related platform. For example, see the [Angular UI localization documentation](../UI/Angular/Localization.md) to learn how to use the localization values exposes by this endpoint. +Other UI types provide services native to the related platform. For example, see the [Angular UI settings documentation](../UI/Angular/Settings.md) to learn how to use the setting values exposes by this endpoint. diff --git a/docs/en/API/Application-Localization.md b/docs/en/API/Application-Localization.md new file mode 100644 index 0000000000..adf26c8fa8 --- /dev/null +++ b/docs/en/API/Application-Localization.md @@ -0,0 +1,33 @@ +# Application Localization Endpoint + +ABP Framework provides a pre-built and standard endpoint that returns all the [localization](../Localization.md) resources and texts defined in the server. + +> If you have started with ABP's startup solution templates and using one of the official UI options, then all these are set up for you and you don't need to know these details. However, if you are building a UI application from scratch, you may want to know this endpoint. + +## HTTP API + +`/api/abp/application-localization` is the main URL of the HTTP API that returns the localization data as a JSON string. I accepts the following query string parameters: + +* `cultureName` (required): A culture code to get the localization data, like `en` or `en-US`. +* `onlyDynamics` (optional, default: `false`): Can be set to `true` to only get the dynamically defined localization resources and texts. If your client-side application shares the same localization resources with the server (like ABP's Blazor and MVC UIs), you can set `onlyDynamics` to `true`. + +**Example request:** + +```` +/api/abp/application-localization?cultureName=en +```` + +## Script + +For [ASP.NET Core MVC (Razor Pages)](../UI/AspNetCore/Overall.md) applications, the same localization data is also available on the JavaScript side. `/Abp/ApplicationLocalizationScript` is the URL of the script that is auto-generated based on the HTTP API above. + +**Example request:** + +```` +/Abp/ApplicationLocalizationScript?cultureName=en +```` + +See the [JavaScript API document](../UI/AspNetCore/JavaScript-API/Index.md) for the ASP.NET Core UI. + +Other UI types provide services native to the related platform. For example, see the [Angular UI localization documentation](../UI/Angular/Localization.md) to learn how to use the localization values exposes by this endpoint. + From 87c4aafa6c48010abfde14433afc0804a75e44b6 Mon Sep 17 00:00:00 2001 From: Hamza Albreem <94292623+braim23@users.noreply.github.com> Date: Thu, 1 Dec 2022 10:08:49 +0300 Subject: [PATCH 11/16] quick fix --- docs/en/Deployment/Configuring-Production.md | 28 ++++++++++---------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/en/Deployment/Configuring-Production.md b/docs/en/Deployment/Configuring-Production.md index 1e562473ba..e4938bea44 100644 --- a/docs/en/Deployment/Configuring-Production.md +++ b/docs/en/Deployment/Configuring-Production.md @@ -1,10 +1,10 @@ # Configuring for Production -ABP Framework has a lot of options to configure and fine-tune its features. They are all explained their own documents. Default values for these options are pretty well for most of the deployment environments. However, you may need to care about some options based on how you've structured your deployment environment. In this document, we will highlight these kind of options. So, it is highly recommended to read this document to not have unexpected behaviors in your system in production. +ABP Framework has a lot of options to configure and fine-tune its features. They are all explained in their own documents. Default values for these options are pretty well for most of the deployment environments. However, you may need to care about some options based on how you've structured your deployment environment. In this document, we will highlight these kind of options. So, it is highly recommended to read this document in order to not have unexpected behaviors in your system in production. ## Distributed Cache Prefix -ABP's [distributed cache infrastructure](../Caching.md) provides an option to set a key prefix for all of your data saved into your distributed cache provider. The default value of this option is not set (it is `null`). If you are using a distributed cache server that shared by different applications, then you can set a prefix value to isolate an application's cache data from others. +ABP's [distributed cache infrastructure](../Caching.md) provides an option to set a key prefix for all of your data that is saved into your distributed cache provider. The default value of this option is not set (it is `null`). If you are using a distributed cache server that is shared by different applications, then you can set a prefix value to isolate an application's cache data from others. ````csharp Configure(options => @@ -13,19 +13,19 @@ Configure(options => }); ```` -That's all. ABP, then will add this prefix to all of your cache keys in your application as along as you use ABP's `IDistributedCache` or `IDistributedCache` services. See the [Caching documentation](../Caching.md) if you are new to the distributed caching. +That's all. ABP, then will add this prefix to all of your cache keys in your application as along as you use ABP's `IDistributedCache` or `IDistributedCache` services. See the [Caching documentation](../Caching.md) if you are new to distributed caching. > **Warning**: If you use ASP.NET Core's standard `IDistributedCache` service, it's your responsibility to add the key prefix (you can get the value by injecting `IOptions`). ABP can not do it. > **Warning**: Even if you have never used distributed caching in your own codebase, ABP still uses it for some features. So, you should always configure this prefix if your caching server is shared among multiple systems. -> **Warning**: If you are building a microservice system, then you will have multiple applications that share the same distributed cache server. In such systems, all applications (or services) normally should use the same cache prefix, because you want all the applications use the same cache data to have consistency between applications. +> **Warning**: If you are building a microservice system, then you will have multiple applications that share the same distributed cache server. In such systems, all applications (or services) should normally use the same cache prefix, because you want all the applications to use the same cache data to have consistency between them. > **Warning**: Some of the ABP's startup templates are pre-configured to set a prefix value for the distributed cache. So, please check your application code if it is already configured. ## Distributed Lock Prefix -ABP's [distributed locking infrastructure](../Distributed-Locking.md) provides an option to set a prefix for all keys you are using in the distributed lock server. The default value of this option is not set (it is `null`). If you are using a distributed lock server that is shared by different applications, then you can set a prefix value to isolate an application's locks from others. +ABP's [distributed locking infrastructure](../Distributed-Locking.md) provides an option to set a prefix for all the keys you are using in the distributed lock server. The default value of this option is not set (it is `null`). If you are using a distributed lock server that is shared by different applications, then you can set a prefix value to isolate an application's lock from others. ````csharp Configure(options => @@ -34,13 +34,13 @@ Configure(options => }); ```` -That's all. ABP, then will add this prefix to all of your keys in your application. See the [Distributed Locking documentation](../Distributed-Locking.md) if you are new to the distributed locking. +That's all. ABP, then will add this prefix to all of your keys in your application. See the [Distributed Locking documentation](../Distributed-Locking.md) if you are new to distributed locking. > **Warning**: Even if you have never used distributed locking in your own codebase, ABP still uses it for some features. So, you should always configure this prefix if your distributed lock server is shared among multiple systems. -> **Warning**: If you are building a microservice system, then you will have multiple applications that share the same distributed locking server. In such systems, all applications (or services) normally should use the same lock prefix, because you want to lock your resources globally in your system. +> **Warning**: If you are building a microservice system, then you will have multiple applications that share the same distributed locking server. In such systems, all applications (or services) should normally use the same lock prefix, because you want to globally lock your resources in your system. -> **Warning**: Some of the ABP's startup templates are pre-configured to set a prefix value for the distributed locking. So, please check your application code if it is already configured. +> **Warning**: Some of ABP's startup templates are pre-configured to set a prefix value for distributed locking. So, please check your application code if it is already configured. ## Email Sender @@ -68,19 +68,19 @@ public class MySmsSender : ISmsSender, ITransientDependency } ```` -> [ABP Commercial](https://commercial.abp.io/) provide a [Twilio SMS Module](https://docs.abp.io/en/commercial/latest/modules/twilio-sms) as a pre-built integration with the popular [Twilio](https://www.twilio.com/) platform. +> [ABP Commercial](https://commercial.abp.io/) provides a [Twilio SMS Module](https://docs.abp.io/en/commercial/latest/modules/twilio-sms) as a pre-built integration with the popular [Twilio](https://www.twilio.com/) platform. ## BLOB Provider -If you use ABP's [BLOB Storing](https://docs.abp.io/en/abp/latest/Blob-Storing) infrastructure, you should care about the BLOB provider in your production environment. For example, if you use the [File System](../Blob-Storing-File-System.md) provider and running your application in a Docker container, you should configure a volume mapping for the BLOB storage path. Otherwise, your data is lost when the container has been restarted. Also, File System is not a good provider for production if you have a [clustered deployment](Clustered-Environment.md) or a microservice system. +If you use ABP's [BLOB Storing](https://docs.abp.io/en/abp/latest/Blob-Storing) infrastructure, you should care about the BLOB provider in your production environment. For example, if you use the [File System](../Blob-Storing-File-System.md) provider and your application is running in a Docker container, you should configure a volume mapping for the BLOB storage path. Otherwise, your data will be lost when the container is restarted. Also, the File System is not a good provider for production if you have a [clustered deployment](Clustered-Environment.md) or a microservice system. Check the [BLOB Storing](../Blob-Storing.md) document to see all the available BLOB storage providers. -> **Warning**: Even if you don't directly use the BLOB Storage system, a module you are depending may use it. For example, ABP Commercial's [File Management](https://docs.abp.io/en/commercial/latest/modules/file-management) module stores file contents, and the [Account](https://docs.abp.io/en/commercial/latest/modules/account) module stores user profile pictures in the BLOB Storage system. So, be careful on the BLOB Storing configuration in production. Note that ABP Commercial uses the [Database Provider](../Blob-Storing-Database.md) as pre-configured BLOB storage provider, which works in production without any problem, but you may still want to use another provider. +> **Warning**: Even if you don't directly use the BLOB Storage system, a module you are depending on may use it. For example, ABP Commercial's [File Management](https://docs.abp.io/en/commercial/latest/modules/file-management) module stores file contents, and the [Account](https://docs.abp.io/en/commercial/latest/modules/account) module stores user profile pictures in the BLOB Storage system. So, be careful with the BLOB Storing configuration in production. Note that ABP Commercial uses the [Database Provider](../Blob-Storing-Database.md) as a pre-configured BLOB storage provider, which works in production without any problem, but you may still want to use another provider. ## String Encryption -ABP's [`IStringEncryptionService` Service](../String-Encryption.md) simply encrypts and decrypts given strings based on a password phrase. You should configure the `AbpStringEncryptionOptions` options for the production with a strong password and keep it as a secret. You can also configure the other properties of that options class. See the following example: +ABP's [`IStringEncryptionService` Service](../String-Encryption.md) simply encrypts and decrypts given strings based on a password phrase. You should configure the `AbpStringEncryptionOptions` options for the production with a strong password and keep it as a secret. You can also configure the other properties of those options class. See the following example: ````csharp Configure(options => @@ -89,11 +89,11 @@ Configure(options => }); ```` -Note that ABP CLI automatically sets the password to a random value on a new project creation. However, it is stored in the `appsettings.json` file and generally added to your source control. It is suggested to use [User Secrets](https://learn.microsoft.com/en-us/aspnet/core/security/app-secrets) or [Environment Variables](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration) to set that value. +Note that ABP CLI automatically sets the password to a random value on a new project creation. However, it is stored in the `appsettings.json` file and is generally added to your source control. It is suggested to use [User Secrets](https://learn.microsoft.com/en-us/aspnet/core/security/app-secrets) or [Environment Variables](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration) to set that value. ## The Swagger UI -ABP's startup solution templates come with the [Swagger UI](https://swagger.io/) pre-installed. Swagger is a pretty standard and useful tool to discover and test your HTTP APIs on a built-in UI that is embedded into your application or service. It is typically used in development environment, but you may want to enable it on staging or production environments too. +ABP's startup solution templates come with [Swagger UI](https://swagger.io/) pre-installed. Swagger is a pretty standard and useful tool to discover and test your HTTP APIs on a built-in UI that is embedded into your application or service. It is typically used in development environment, but you may want to enable it on staging or production environments too. While you will always secure your HTTP APIs with other techniques (like the [Authorization](../Authorization.md) system), allowing malicious software and people to easily discover your HTTP API endpoint details can be considered as a security problem for some systems. So, be careful while taking the decision of enabling or disabling Swagger for the production environment. From eba100097cd2b991e1abb64646ebf7b777db000e Mon Sep 17 00:00:00 2001 From: Hamza Albreem <94292623+braim23@users.noreply.github.com> Date: Thu, 1 Dec 2022 10:21:58 +0300 Subject: [PATCH 12/16] tiny fix --- docs/en/Deployment/Configuring-Production.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/Deployment/Configuring-Production.md b/docs/en/Deployment/Configuring-Production.md index e4938bea44..5efa560621 100644 --- a/docs/en/Deployment/Configuring-Production.md +++ b/docs/en/Deployment/Configuring-Production.md @@ -21,7 +21,7 @@ That's all. ABP, then will add this prefix to all of your cache keys in your app > **Warning**: If you are building a microservice system, then you will have multiple applications that share the same distributed cache server. In such systems, all applications (or services) should normally use the same cache prefix, because you want all the applications to use the same cache data to have consistency between them. -> **Warning**: Some of the ABP's startup templates are pre-configured to set a prefix value for the distributed cache. So, please check your application code if it is already configured. +> **Warning**: Some of ABP's startup templates are pre-configured to set a prefix value for the distributed cache. So, please check your application code if it is already configured. ## Distributed Lock Prefix From 9d51af23eeef4ec3b08031e364ebb47421401932 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Halil=20=C4=B0brahim=20Kalkan?= Date: Thu, 1 Dec 2022 10:27:10 +0300 Subject: [PATCH 13/16] Fix abp.localization.localize method. --- npm/packs/core/src/abp.js | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/npm/packs/core/src/abp.js b/npm/packs/core/src/abp.js index 5a2747a3c7..7a82f58e98 100644 --- a/npm/packs/core/src/abp.js +++ b/npm/packs/core/src/abp.js @@ -135,14 +135,20 @@ var abp = abp || {}; if (sourceName === '_') { //A convention to suppress the localization return key; } + + if (sourceName) { + return abp.localization.internal.localize.apply(this, arguments).value; + } - sourceName = sourceName || abp.localization.defaultResourceName; - if (!sourceName) { + if (!abp.localization.defaultResourceName) { abp.log.warn('Localization source name is not specified and the defaultResourceName was not defined!'); return key; } - return abp.localization.internal.localize.apply(this, arguments).value; + var copiedArguments = Array.prototype.slice.call(arguments, 0); + copiedArguments.splice(1, 1, abp.localization.defaultResourceName); + + return abp.localization.internal.localize.apply(this, copiedArguments).value; }; abp.localization.isLocalized = function (key, sourceName) { From f96e8b3c859d61f98263a6899ba7a7fe8be20cfd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Halil=20=C4=B0brahim=20Kalkan?= Date: Thu, 1 Dec 2022 10:30:33 +0300 Subject: [PATCH 14/16] Update Localization.md --- docs/en/UI/AspNetCore/JavaScript-API/Localization.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/en/UI/AspNetCore/JavaScript-API/Localization.md b/docs/en/UI/AspNetCore/JavaScript-API/Localization.md index 0897b99268..0f6851799a 100644 --- a/docs/en/UI/AspNetCore/JavaScript-API/Localization.md +++ b/docs/en/UI/AspNetCore/JavaScript-API/Localization.md @@ -54,9 +54,9 @@ Assuming the `HelloWelcomeMessage` is localized as `Hello {0}, welcome!`, both o ## Other Properties & Methods -### abp.localization.values +### abp.localization.resources -`abp.localization.values` property stores all the localization resources, keys and their values. +`abp.localization.resources` property stores all the localization resources, keys and their values. ### abp.localization.isLocalized From 13431a1a21be288404dafef070c7621ec3a5d830 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Halil=20=C4=B0brahim=20Kalkan?= Date: Thu, 1 Dec 2022 12:54:22 +0300 Subject: [PATCH 15/16] Add Application Localization to document navigation --- docs/en/docs-nav.json | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/en/docs-nav.json b/docs/en/docs-nav.json index d7cf2a5389..21638f313e 100644 --- a/docs/en/docs-nav.json +++ b/docs/en/docs-nav.json @@ -614,6 +614,10 @@ { "text": "Application Configuration", "path": "API/Application-Configuration.md" + }, + { + "text": "Application Localization", + "path": "API/Application-Localization.md" } ] }, From cea5f34b43a7428125189729bdd9dc4b525b7f7a Mon Sep 17 00:00:00 2001 From: liangshiwei Date: Fri, 2 Dec 2022 13:57:47 +0800 Subject: [PATCH 16/16] Enhance ABP CLI --- .../Abp/Cli/ProjectBuilding/Templates/App/AppTemplateBase.cs | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/framework/src/Volo.Abp.Cli.Core/Volo/Abp/Cli/ProjectBuilding/Templates/App/AppTemplateBase.cs b/framework/src/Volo.Abp.Cli.Core/Volo/Abp/Cli/ProjectBuilding/Templates/App/AppTemplateBase.cs index b3bdf2d7e9..44b9c20423 100644 --- a/framework/src/Volo.Abp.Cli.Core/Volo/Abp/Cli/ProjectBuilding/Templates/App/AppTemplateBase.cs +++ b/framework/src/Volo.Abp.Cli.Core/Volo/Abp/Cli/ProjectBuilding/Templates/App/AppTemplateBase.cs @@ -154,6 +154,11 @@ public abstract class AppTemplateBase : TemplateInfo steps.Add(new RemoveProjectFromSolutionStep("MyCompanyName.MyProjectName.Blazor.Server.Tiered")); } + if (context.BuildArgs.UiFramework != UiFramework.MauiBlazor) + { + steps.Add(new RemoveProjectFromSolutionStep("MyCompanyName.MyProjectName.MauiBlazor")); + } + if (context.BuildArgs.UiFramework != UiFramework.Angular) { steps.Add(new RemoveFolderStep("/angular"));