<commit_before># Development Guide

## Introduction

### About This Document

In [Getting Started](Getting-Started.md) document, a new sample
project is created named "**Acme.PhoneBook**". This document is a guide
while developing your project. We definitely suggest to read this
document before starting to the development. Since ASP.NET Zero is built
on [ASP.NET Boilerplate](https://aspnetboilerplate.com/) application
framework, this document highly refers it's
[documentation](https://aspnetboilerplate.com/Pages/Documents).

Before reading this document, it's suggested to run the application and
explore the user interface. This will help you to have a better
understanding of concepts defined here.

About Server Side

This document is only for the **Angular** application. For **server
side**, see [ASP.NET Core documentation](Development-Guide-Core.md)
too.

### Pre Requirements

Following tools are needed in order to use the solution:

-   [nodejs 6.9+ and Npm 3.10+](https://nodejs.org)
-   [Typescript 2.0+](https://www.typescriptlang.org/)
-   [yarn](https://yarnpkg.com/)

In addition, see [ASP.NET Core](Development-Guide-Core.md)
documentation for server side requirements and other server side
features.

#### IDE

It's suggested to use an IDE to develop your project. We used [Visual
Studio 2017](https://www.visualstudio.com), but you can use VS Code or
any other IDE/Editor you like (VS Code, for instance). You can also use
any OS you like (MacOS/Linux/Windows).

## Overall

### Architecture

The diagram below shows the overall architecture:

<img src="images/angular2-core-overall-architecture.png" alt="Angular ASP.NET Core Architecture Overall" class="thumbnail" width="683" height="163" />

-   **Angular** project is designed so it can be **deployed separately**
    from the backend ASP.NET Core solution, to a different port in same
    server or to a different server. When it's deployed, it's actually a
    plain HTML+JS+CSS web application that can be served on any operating
    system and any web server.
-   **Angular** solution consists of 2 fundamental modules:
    -   **AccountModule** is for login, register, remember password and
        so on. It's mainly used to authenticate a user using
        TokenAuthController in the server side.
    -   **AppModule** is for authenticated users. Once a user logged in
        successfully, they are redirected to the main application.
        Communication performed via AJAX requests using header based
        token authentication.
-   **ASP.NET Core** solution does not have any HTML, JS or CSS code. It
    simply provides end points for token based authentication and to use
    the application services.

### Angular Solution

Entry point of the Angular solution is src/**main.ts**. It simply
bootstraps the root [Angular
module](https://angular.io/docs/ts/latest/guide/ngmodule.html):
**RootModule**. Fundamental modules of the solution are shown below:

<img src="images/ng2-modules.png" alt="Angular 2 modules" class="img-thumbnail" width="501" height="221" />

-   **RootModule** is responsible to bootstrap the application.
-   **AccountModule** provides login, two factor authentication,
    register, password forget/reset, email activation...
    functionalities. It's [lazy
    loaded](https://angular.io/docs/ts/latest/guide/router.html).
-   **AppModule** is just to group application modules and provide a
    base layout. It contains 2 sub modules:
    -   **AdminModule** contains pages like user management, role
        management, tenant management, language management, settings and
        so on. It's lazy loaded.
    -   **MainModule** is the main module to develop your own
        application. It only contains a demo dashboard page which you
        can modify or delete. It's suggested to divide your application
        into smaller modules like we did in the startup project, instead
        of adding all functionality into the main module. It's lazy
        loaded.

Fundamental modules have their own **routes**. For example;
AccountModule views start with "**/account**" (like "/account/login"),
AdminModule views starts with "**/app/admin**" (like
"/app/admin/users"). Angular's router lazy loads modules based on their
url. For instance, when you request a url starts with "app/admin", the
AdminModule and all it's components are loaded. They are not loaded if
you don't request those pages. That brings better startup time (and also
better development time since they are independently splitted to
chunks).

In addition to those fundamental modules, there are some share modules:

-   app/shared/common/**app-common.module**: a common module used by
    main and admin modules as shared functionality.
-   shared/common/**common.module**: A common module used by account and
    app modules (and their sub modules).
-   shared/utils/**utils.module**: Another common module used by all
    modules (and their sub modules). We tried to collect general purpose
    code here those can be used even in different applications.
-   shared/service-proxies/**service-proxy.module**: Auto generated
    nswag code. It's used to communicate to backend ASP.NET Core API. We
    will see "how to generate automatic proxies" later.

### Configuration

Angular solution contains src/assets/**appconfig.json** file which
contains some configuration for the client side:

-   **remoteServiceBaseUrl**: Used to configure base address of the
    server side APIs. Default value: http://localhost:22742
-   **appBaseUrl**: Used to configure base address of the client
    application. Default value: http://localhost:4200

**appBaseUrl** is configured since we use it to define format of our
URL. If we want to use tenancy name as subdomain for a multi-tenant
application then we can define **appBaseUrl** as

http://**{TENANCY\_NAME}**.mydomain.com

{TENANCY\_NAME} is the place holder here for tenant names. Tenancy name
can also be configured for **remoteServiceBaseUrl** as similar. To make
tenancy name subdomains properly work, we should also make two
configurations beside the application:

1.  We should configure DNS to redirect all subdomains to a static IP
    address. To declare 'all subdomains', we can use wildcard like
    **\*.mydomain.com**.<commit_msg>Expanded the explaination of subdomain tenancy<commit_after># Development Guide

## Introduction

### About This Document

In [Getting Started](Getting-Started.md) document, a new sample
project is created named "**Acme.PhoneBook**". This document is a guide
while developing your project. We definitely suggest to read this
document before starting to the development. Since ASP.NET Zero is built
on [ASP.NET Boilerplate](https://aspnetboilerplate.com/) application
framework, this document highly refers it's
[documentation](https://aspnetboilerplate.com/Pages/Documents).

Before reading this document, it's suggested to run the application and
explore the user interface. This will help you to have a better
understanding of concepts defined here.

About Server Side

This document is only for the **Angular** application. For **server
side**, see [ASP.NET Core documentation](Development-Guide-Core.md)
too.

### Pre Requirements

Following tools are needed in order to use the solution:

-   [nodejs 6.9+ and Npm 3.10+](https://nodejs.org)
-   [Typescript 2.0+](https://www.typescriptlang.org/)
-   [yarn](https://yarnpkg.com/)

In addition, see [ASP.NET Core](Development-Guide-Core.md)
documentation for server side requirements and other server side
features.

#### IDE

It's suggested to use an IDE to develop your project. We used [Visual
Studio 2017](https://www.visualstudio.com), but you can use VS Code or
any other IDE/Editor you like (VS Code, for instance). You can also use
any OS you like (MacOS/Linux/Windows).

## Overall

### Architecture

The diagram below shows the overall architecture:

<img src="images/angular2-core-overall-architecture.png" alt="Angular ASP.NET Core Architecture Overall" class="thumbnail" width="683" height="163" />

-   **Angular** project is designed so it can be **deployed separately**
    from the backend ASP.NET Core solution, to a different port in same
    server or to a different server. When it's deployed, it's actually a
    plain HTML+JS+CSS web application that can be served on any operating
    system and any web server.
-   **Angular** solution consists of 2 fundamental modules:
    -   **AccountModule** is for login, register, remember password and
        so on. It's mainly used to authenticate a user using
        TokenAuthController in the server side.
    -   **AppModule** is for authenticated users. Once a user logged in
        successfully, they are redirected to the main application.
        Communication performed via AJAX requests using header based
        token authentication.
-   **ASP.NET Core** solution does not have any HTML, JS or CSS code. It
    simply provides end points for token based authentication and to use
    the application services.

### Angular Solution

Entry point of the Angular solution is src/**main.ts**. It simply
bootstraps the root [Angular
module](https://angular.io/docs/ts/latest/guide/ngmodule.html):
**RootModule**. Fundamental modules of the solution are shown below:

<img src="images/ng2-modules.png" alt="Angular 2 modules" class="img-thumbnail" width="501" height="221" />

-   **RootModule** is responsible to bootstrap the application.
-   **AccountModule** provides login, two factor authentication,
    register, password forget/reset, email activation...
    functionalities. It's [lazy
    loaded](https://angular.io/docs/ts/latest/guide/router.html).
-   **AppModule** is just to group application modules and provide a
    base layout. It contains 2 sub modules:
    -   **AdminModule** contains pages like user management, role
        management, tenant management, language management, settings and
        so on. It's lazy loaded.
    -   **MainModule** is the main module to develop your own
        application. It only contains a demo dashboard page which you
        can modify or delete. It's suggested to divide your application
        into smaller modules like we did in the startup project, instead
        of adding all functionality into the main module. It's lazy
        loaded.

Fundamental modules have their own **routes**. For example;
AccountModule views start with "**/account**" (like "/account/login"),
AdminModule views starts with "**/app/admin**" (like
"/app/admin/users"). Angular's router lazy loads modules based on their
url. For instance, when you request a url starts with "app/admin", the
AdminModule and all it's components are loaded. They are not loaded if
you don't request those pages. That brings better startup time (and also
better development time since they are independently splitted to
chunks).

In addition to those fundamental modules, there are some share modules:

-   app/shared/common/**app-common.module**: a common module used by
    main and admin modules as shared functionality.
-   shared/common/**common.module**: A common module used by account and
    app modules (and their sub modules).
-   shared/utils/**utils.module**: Another common module used by all
    modules (and their sub modules). We tried to collect general purpose
    code here those can be used even in different applications.
-   shared/service-proxies/**service-proxy.module**: Auto generated
    nswag code. It's used to communicate to backend ASP.NET Core API. We
    will see "how to generate automatic proxies" later.

### Configuration

The Angular solution file src/assets/**appconfig.json** contains some 
configuration for the client side. At runtime, the client scripts will 
download this file, and use it to calculate the address of the server-side
API:

-   **remoteServiceBaseUrl**: Used to configure the base address of the
    server side APIs. Default value: http://localhost:22742
-   **appBaseUrl**: Used to configure the base address of the client
    application. Default value: http://localhost:4200

**appBaseUrl** is configured since we use it to define format of our
URL. 

#### Subdomain Multi-Tenancy:
If we want to use the tenancy name as a subdomain for a multi-tenant
application then we can define **appBaseUrl** as

http://**{TENANCY\_NAME}**.mydomain.com

{TENANCY\_NAME} is the place holder here for tenant names. Tenancy name
must be similarly configured for **remoteServiceBaseUrl**. 

It's important to understand that subdomain multi-tenancy is a function
of the `DomainTenantResolveContributor` ***server-side*** module.
This means that the server API **must** be accessed via a sub-domain that
conforms to the format you have defined during your configuration of 
AspNetBoilerplate (see 
[these notes](https://github.com/aspnetboilerplate/aspnetboilerplate/blob/dev/doc/WebSite/Multi-Tenancy.md#determining-current-tenant) regarding preinitialization).

<img src="images/angular2-core-subdomain-tenant-resolution-sequence.png" alt="Angular ASP.NET Core Sub-Domain Tenancy Overview" class="img-thumbnail" width="540" height="379" />

To complete the setup of subdomain tenancy, we should also make two
infrastructural configurations:

1.  We should configure DNS to redirect all subdomains to a static IP
    address. To declare 'all subdomains', we can use wildcard like
    **\*.mydomain.com**. Note that if you have a split Angular/API
    setup, then you will need 2 subdomain formats, such as:
    **\*.app.mydomain.com** and **\*.api.mydomain.com**
{'fraction_non_alphanumeric': 0.08712344949793266, 'fraction_numerical': 0.0062020082693443595, 'mean_word_length': 4.0353159851301115, 'pattern_counts': {'":': 0, '<': 8, '<?xml version=': 0, '>': 8, 'https://': 17, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 7, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '905715', 'n_tokens_mistral': 3648, 'n_tokens_neox': 3455, 'n_words': 1650}