From cf85b2b80cef3fc87bd3427155fb90d86e03bf21 Mon Sep 17 00:00:00 2001
From: Engincan VESKE <43685404+EngincanV@users.noreply.github.com>
Date: Wed, 21 Dec 2022 15:43:45 +0300
Subject: [PATCH] docs: Add a new section for `IAbpHostEnvironment` on the
 Application-Startup.md

---
 docs/en/Application-Startup.md | 51 ++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/docs/en/Application-Startup.md b/docs/en/Application-Startup.md
index 1c5bf9b139..d808574ab4 100644
--- a/docs/en/Application-Startup.md
+++ b/docs/en/Application-Startup.md
@@ -204,6 +204,7 @@ We've passed a lambda method to configure the `ApplicationName` option. Here's a
 
 * `ApplicationName`: A human-readable name for the application. It is a unique value for an application.
 * `Configuration`: Can be used to setup the [application configuration](Configuration.md) when it is not provided by the hosting system. It is not needed for ASP.NET Core and other .NET hosted applications. However, if you've used `AbpApplicationFactory` with an internal service provider, you can use this option to configure how the application configuration is built.
+* `Environment`: Environment name for the application. 
 * `PlugInSources`: A list of plugin sources. See the [Plug-In Modules documentation](PlugIn-Modules) to learn how to work with plugins.
 * `Services`: The `IServiceCollection` object that can be used to register service dependencies. You generally don't need that, because you configure your services in your [module class](Module-Development-Basics.md). However, it can be used while writing extension methods for the `AbpApplicationCreationOptions` class.
 
@@ -253,6 +254,56 @@ The `IAbpApplication` interface extends the `IApplicationInfoAccessor` interface
 
 `IAbpApplication` is disposable. Always dispose of it before exiting your application.
 
+## IAbpHostEnvironment
+
+Sometimes, while creating an application, we need to get the current hosting environment and take actions according to that. In such cases, we can use some services such as [IWebHostEnvironment](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.hosting.iwebhostenvironment?view=aspnetcore-7.0) or [IWebAssemblyHostEnvironment](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.components.webassembly.hosting.iwebassemblyhostenvironment) provided by .NET, in the final application. 
+
+However, we can not use these services in a class library, which uses by the final application. We can only use these services in the final application. ABP Framework provides the `IAbpHostEnvironment` service to get the current environment name whenever you want, in a class library or a runnable application. 
+
+`IAbpHostEnvironment` is used by the ABP Framework in several places to perform specific actions by the environment. For example, ABP Framework reduces the cache duration on the **Development** environment for some services.
+
+`IAbpHostEnvironment` uses the following order to obtain the current environment name:
+
+1. Gets and sets the environment name if it's specified in the `AbpApplicationCreationOptions`.
+2. Tries to obtain the environment name from the `IWebHostEnvironment` or `IWebAssemblyHostEnvironment` services for ASP.NET Core & Blazor WASM applications, if the environment name doesn't specify in the `AbpApplicationCreationOptions`.
+3. Sets the environment name as **Production**, if the environment name does not specified or can not obtained from the services.
+
+You can configure the `AbpApplicationCreationOptions` [options class](Options.md) while creating the ABP application and set an environment name to its `Environment` property. You can find the `AddApplication` or `AddApplicationAsync` call in your solution (typically in the `Program.cs` file), and set the `Environment` option as shown below:
+
+```csharp
+await builder.AddApplicationAsync<OrderingServiceHttpApiHostModule>(options =>
+{
+    options.Environment = Environments.Staging; //or directly set as "Staging"
+});
+```
+
+Then, whenever you need to get the current environment name or check the environment, you can use the `IAbpHostEnvironment` interface:
+
+```csharp
+public class MyDemoService
+{
+    private readonly IAbpHostEnvironment _abpHostEnvironment;
+    
+    public MyDemoService(IAbpHostEnvironment abpHostEnvironment)
+    {
+        _abpHostEnvironment = abpHostEnvironment;
+    }
+
+    public void MyMethod()
+    {
+        var environmentName = _abpHostEnvironment.EnvironmentName;
+
+        if (_abpHostEnvironment.IsDevelopment()) { /* ... */ } 
+
+        if (_abpHostEnvironment.IsStaging()) { /* ... */ }
+
+        if (_abpHostEnvironment.IsProduction()) { /* ... */ }
+
+        if (_abpHostEnvironment.IsEnvironment("custom-environment")) { /* ... */ }
+    }
+}
+```
+
 ## .NET Generic Host & ASP.NET Core Integrations
 
 `AbpApplicationFactory` can create a standalone ABP application container without any external dependency. However, in most cases, you will want to integrate it with [.NET's generic host](https://learn.microsoft.com/en-us/dotnet/core/extensions/generic-host) or ASP.NET Core. For such usages, ABP provides built-in extension methods to easily create an ABP application container that is well-integrated to these systems.