Merge pull request #337 from aspnetzero/add-subdomain-based-multi-tenancy-doc

Add reference subdomain-based multi-tenant in overview document

Author: ismcagdas

docs/en/Overview-Angular.md

@@ -109,6 +109,8 @@ There may be other ways of doing it but this is the simplest way.
 
 > In the development time, you don't need to use subdomains for tenants for a simpler development experience. When you do like that, a 'tenant switch' dialog is used to manually switch between tenants.
 
+> For advanced scenarios and production-level configuration of subdomain-based multi-tenancy in ASP.NET Zero Angular applications, including SSL setup, IIS configuration, local development strategies, and tenant resolution internals, please refer to the extended documentation here: [Subdomain-Based Multi-Tenancy in ASP.NET Zero (Angular)](Subdomain-Based-Multi-Tenancy-Angular.md)
+
 Check out the [multi tenant documentation](https://aspnetboilerplate.com/Pages/Documents/Multi-Tenancy) if you are building multi-tenant applications.
 
 ### Angular Solution

docs/en/Overview-Core.md

@@ -87,6 +87,8 @@ There may be other ways of doing it but this is the simplest way.
 
 > In the development time, you don't need to use subdomains for tenants for a simpler development experience. When you do like that, a 'tenant switch' dialog is used to manually switch between tenants.
 
+> For advanced scenarios and production-level configuration of subdomain-based multi-tenancy in ASP.NET Zero MVC applications, including SSL setup, IIS configuration, local development strategies, and tenant resolution internals, please refer to the extended documentation here: [Subdomain-Based Multi-Tenancy in ASP.NET Zero (MVC)](Subdomain-Based-Multi-Tenancy-MVC.md)
+
 Check out the [multi tenant documentation](https://aspnetboilerplate.com/Pages/Documents/Multi-Tenancy) if you are building multi-tenant applications.
 
 Similar to **WebSiteRootAddress**, **ServerRootAddress** setting is also exists in `appsettings.json` in .Web.Host project.

docs/en/Subdomain-Based-Multi-Tenancy-Angular.md

@@ -1,12 +1,12 @@
-# Subdomain-Based Multi-Tenancy in ASP.NET Zero (Angular)
+# Subdomain Based Multi Tenancy in ASP.NET Zero (Angular)
 
 ## Introduction
 
-This document provides detailed guidance for configuring and troubleshooting subdomain based multi-tenancy in ASP.NET Zero projects utilizing an Angular frontend. It expands upon the foundational knowledge offered in the official documentation, aiming to cover advanced configurations, development environment strategies, and common issues.
+This document provides detailed guidance for configuring and troubleshooting subdomain based multi tenancy in ASP.NET Zero projects utilizing an Angular frontend. It expands upon the foundational knowledge offered in the official documentation, aiming to cover advanced configurations, development environment strategies, and common issues.
 
 This document assumes you have a basic understanding of ASP.NET Zero's multi tenancy concepts and have reviewed the main [Overview Angular](Overview-Angular.md) documentation.
 
-## 1. Configuration for Subdomain-Based Tenancy
+## 1. Configuration for Subdomain Based Tenancy
 
 This section involves SSL management, web server setup, and specific Angular application settings.
 
@@ -26,7 +26,7 @@ This section involves SSL management, web server setup, and specific Angular app
     * For HTTP binding (port 80), you can often leave the "Host Name" field empty if it's the only site on that IP, or specify each primary domain if needed.
     * For HTTPS binding (port 443), select the appropriate wildcard SSL certificate. The host name field might be left blank or set if your IIS version supports specific SNI configurations with wildcards, but often the wildcard nature is primarily handled by the certificate itself. The key is that IIS listens for traffic on the IP and port, and the certificate validates for `*.mydomain.com`.
 * **Default Document/Application:** Ensure your IIS site is configured to correctly serve the Angular application (typically `index.html` and other static assets from your `dist` folder) for all subdomain requests that point to the client application.
-* **URL Rewrite (If Necessary):** While ASP.NET Zero's framework handles tenant resolution based on the host, complex infrastructures involving reverse proxies might require URL Rewrite rules. However, for standard deployments, this is generally not needed for the core multi-tenancy functionality.
+* **URL Rewrite (If Necessary):** While ASP.NET Zero's framework handles tenant resolution based on the host, complex infrastructures involving reverse proxies might require URL Rewrite rules. However, for standard deployments, this is generally not needed for the core multi tenancy functionality.
 
 ### Angular Application (`appsettings.json`) Specifics
 
@@ -43,13 +43,13 @@ This section involves SSL management, web server setup, and specific Angular app
         }
         ```
 * **Tenant Resolution in Angular:**
-    * ASP.NET Zero's client-side infrastructure typically uses the `ServerRootAddress`. The framework includes logic to dynamically replace the `{TENANCY_NAME}` placeholder based on the current browser URL's subdomain.
+    * ASP.NET Zero's client side infrastructure typically uses the `ServerRootAddress`. The framework includes logic to dynamically replace the `{TENANCY_NAME}` placeholder based on the current browser URL's subdomain.
     * This ensures that API calls generated by `NSwag` or other service proxies are directed to the correct tenant specific backend endpoints.
-    * While largely abstracted, the Angular application inherently becomes tenant-aware through these configured, dynamic URLs.
+    * While largely abstracted, the Angular application inherently becomes tenant aware through these configured, dynamic URLs.
 
 ## 2. Development Environment Strategies for Subdomain Testing
 
-Testing subdomain-based multi-tenancy locally requires a few extra steps compared to path-based tenancy or using the tenant switch dialog.
+Testing subdomain based multi tenancy locally requires a few extra steps compared to path based tenancy or using the tenant switch dialog.
 
 ### Using the `hosts` File
 
@@ -77,7 +77,7 @@ Testing subdomain-based multi-tenancy locally requires a few extra steps compare
 
 * Standard `localhost` development certificates provided by `dotnet dev-certs https` will not be valid for custom local subdomains like `tenant1.localhost`. This will result in browser SSL warnings.
 * **Solutions:**
-    1.  **HTTP Locally:** For simplicity, you can develop and test the subdomain logic using HTTP locally and rely on the tenant switch dialog if HTTPS-specific features are not being tested.
+    1.  **HTTP Locally:** For simplicity, you can develop and test the subdomain logic using HTTP locally and rely on the tenant switch dialog if HTTPS specific features are not being tested.
     2.  **`mkcert` Tool:** Use a tool like `mkcert` to create a locally trusted Certificate Authority (CA) and then generate wildcard certificates (e.g., `*.localhost`). You would then configure Kestrel and potentially the Angular dev server to use these certificates. This provides a more accurate simulation of a production HTTPS environment.
 
 ### Interaction with Tenant Switch Dialog
@@ -87,37 +87,37 @@ Testing subdomain-based multi-tenancy locally requires a few extra steps compare
 
 ## 3. Tenant Resolution Flow Clarification
 
-A clear understanding of the tenant resolution process is essential to ensure accurate tenant identification and proper request routing in a multi-tenant architecture. This step determines which tenant context should be applied based on the incoming request, typically using elements like the subdomain, header, or query string.
+A clear understanding of the tenant resolution process is essential to ensure accurate tenant identification and proper request routing in a multi tenant architecture. This step determines which tenant context should be applied based on the incoming request, typically using elements like the subdomain, header, or query string.
 
 ### Backend (ASP.NET Core)
 
 1.  An incoming HTTP request arrives at the ASP.NET Core application.
 2.  ASP.NET Zero's middleware, specifically implementations of `ITenantResolveContributor` (like `DomainTenantResolveContributor`), inspects the request's host header (e.g., `tenant1.api.mydomain.com`).
 3.  If the host matches the configured subdomain pattern (derived from `ServerRootAddress` with the `{TENANCY_NAME}` placeholder), the middleware extracts the tenancy name (`tenant1` in this example).
 4.  It then attempts to find this tenant in the database.
-5.  If found, the current tenant context is set for the duration of that request, ensuring data isolation and that tenant-specific settings and services are used.
+5.  If found, the current tenant context is set for the duration of that request, ensuring data isolation and that tenant specific settings and services are used.
 
 ### Frontend (Angular)
 
 1.  The Angular application is loaded from a URL like `https://tenant1.app.mydomain.com`.
 2.  The `ServerRootAddress` in `appsettings.json` (e.g., `https://{TENANCY_NAME}.api.mydomain.com`) is used by the generated service proxies.
-3.  ASP.NET Zero's client-side JavaScript utilities dynamically replace the `{TENANCY_NAME}` placeholder in `ServerRootAddress` with the actual tenancy name extracted from the current browser window's hostname (`tenant1.app.mydomain.com`).
-4.  All subsequent API calls made through these service proxies will correctly target the tenant-specific backend API endpoints (e.g., `https://tenant1.api.mydomain.com/api/services/app/User/GetUsers`).
+3.  ASP.NET Zero's client side JavaScript utilities dynamically replace the `{TENANCY_NAME}` placeholder in `ServerRootAddress` with the actual tenancy name extracted from the current browser window's hostname (`tenant1.app.mydomain.com`).
+4.  All subsequent API calls made through these service proxies will correctly target the tenant specific backend API endpoints (e.g., `https://tenant1.api.mydomain.com/api/services/app/User/GetUsers`).
 
-## 4. Troubleshooting Common Subdomain Multi-Tenancy Issues
+## 4. Troubleshooting Common Subdomain Multi Tenancy Issues
 
 Here are some common problems and how to address them:
 
 ### DNS Not Resolving
 
 * **Propagation Time:** DNS changes (especially for new wildcard records) can take time to propagate globally (minutes to hours).
-* **Record Verification:** Double-check your DNS provider's settings. Ensure the `A` record or `CNAME` record for the wildcard (e.g., `*.mydomain.com`) correctly points to your web server's public IP address.
+* **Record Verification:** Double check your DNS provider's settings. Ensure the `A` record or `CNAME` record for the wildcard (e.g., `*.mydomain.com`) correctly points to your web server's public IP address.
 * **Local `hosts` File:** For local development, ensure your `hosts` file entries are correctly spelled, saved, and that your browser or OS is not caching old DNS lookups aggressively (try clearing cache or an incognito window).
 
 ### CORS Errors
 
 * **CorsOrigins Configuration:** In the `appsettings.json` of your `*.Web.Host` project, meticulously check the `App:CorsOrigins` setting. It must accurately include the URLs of your Angular application, including the wildcard for subdomains.
-    * Example: `"CorsOrigins": "https://*.app.mydomain.com,http://*.app.mydomain.com"` (include both HTTP and HTTPS if applicable, and consider ports if non-standard).
+    * Example: `"CorsOrigins": "https://*.app.mydomain.com,http://*.app.mydomain.com"` (include both HTTP and HTTPS if applicable, and consider ports if non standard).
 * **Browser Console:** Always inspect the browser's developer console (Network tab) for detailed CORS error messages. The error often indicates which origin is being blocked and what headers are missing or mismatched from the preflight (OPTIONS) request.
 * **Scheme and Port:** CORS is sensitive to scheme (HTTP vs. HTTPS) and port numbers. Ensure these match exactly in your `CorsOrigins` configuration.
 
@@ -127,7 +127,7 @@ Here are some common problems and how to address them:
     * Ensure your certificate is a true wildcard (e.g., `*.mydomain.com`) or a SAN certificate that explicitly lists all required tenant subdomains or the relevant wildcard.
 * **Untrusted Certificate:**
     * For production, ensure your certificate is issued by a reputable CA.
-    * For local development with self-signed or `mkcert`-generated certificates, ensure the root CA certificate used to sign them is trusted by your operating system and browser.
+    * For local development with self signed or `mkcert` generated certificates, ensure the root CA certificate used to sign them is trusted by your operating system and browser.
 * **Mixed Content:** Ensure all resources are loaded over HTTPS if your site is HTTPS.
 
 ### Incorrect Tenant Loaded or Redirected to Host