Architecture Guidelines

先檢視 README 和 repository 中現有的程式碼撰寫指南文件，然後將它們與提議的 Project documentation、General Architecture 和 Web Application Architecture 區段進行比較。issue 未指明檔案，也未定義已達成共識的範圍；要視為完成，需要一套已接受且可執行的指南，以及明確的存放位置。

Some proposals for guidelines based on things I've seen recently, and over the years:

Project documentation:

1. All projects should have a README file in their repository root that includes the following information, or contains links or instructions on where to find the following information:

   1. How to setup a local development environment for working on the project, including:
      1. Prerequisite installed software (IDEs, SDKs, Databases, other tooling, recommended IDE extensions, etc.), including version requirements.
      2. How to open the project in the recommended IDE/editor (e.g. "Open the .sln file in the repository root with Visual Studio 2019")
   2. How to build and run the project, including:
      1. How to restore any packages that aren't automatically restored. For example, Nuget packages are auto-restored by dotnet tooling, but npm packages are not.
      2. How to obtain a local copy of any required database, if necessary.
   3. How to run the project's tests
   4. How to contribute to the project's tests, including a brief summary of the different types of testing that are utilized in the application (unit testing, integration testing, UI testing, etc).
   5. How to contribute changes to the primary branch of the project, including a description of branching strategy, the project's pull request process & requirements, any review processes the project is subject to, including code reviews, architecture review, security reviews, etc.
   6. How the project is deployed, including:
      1. A description of each environment that the project may be deployed to
      2. Any URL(s) where the deployed/published project may be found
      3. A description of the process for promotion from one environment to another, including necessary approvals, manual testing/verification, and actual actions that must be taken to achieve the environment promotion (e.g. release pipelines).

2. All possible sources of application configuration that is environment-dependent MUST be clearly enumerated in a README file in the root of the project's repository, or must otherwise be linked to from such a README file. This file MUST be updated when changes are made to how an application is configured.

   1. Possible sources of configuration include, but are not limited to:
      1. Injection by an automated build or release process
      2. Stored on a cloud service, such as Azure App Service configuration (injected into the app via Environment Variables), or Azure Key Vault
      3. Stored in database table(s)
      4. Stored in files checked into the repository, including appsettings.*.json, launchSettings.json, package.json, app.config, and any other file containing configuration.
      5. Stored from predefined files/directories in environments where the application is running.
      6. Hardcoded configuration (DO NOT use hardcoded configuration, but if it truly cannot be moved elsewhere, please document it.)
   2. Possible types of configuration include, but are not limited to:
      1. Any credentials, including username/password pairs and API keys
      2. Any configuration the instructs the application how to locate an external resource, including database connection strings, URLs, IP addresses, email addresses, cloud provider subscription IDs, resource IDs, or any other external resource.

General Architecture:

1. Utilize Dependency Injection in all projects whenever possible This probably needs to be expanded upon - its maybe too open-ended and vague
2. In projects utilizing dependency injection:
   1. DO NOT store global singletons in static fields/properties. Always resolve such objects from the DI container, including services, configuration, or any other singleton.
   2. DO NOT manually instantiate classes that are registered with the DI container. This is especially applicable to Entity Framework DbContext instances, because manual instantiation implies that the DbContextOptions<> are also being manually created, are hardcoded into the DbContext constructor, or are being stored as a global singleton.
      1. Exception: Instantiating DbContext instances during setup when the instance is being configured with some an in-memory provider.
   3. AVOID using the service locator pattern, PREFER using the standard mechanisms of injection provided by your DI framework (e.g. constructor injection, ASP.NET Core parameter injection via [FromServices], etc.)

Web Application Architecture:

1. When an application needs to run long-running or recurring background jobs, you SHOULD prefer Hangfire (https://www.hangfire.io/) over homegrown out-of-process job engines, manual spawning of threads, using Task.Run, or utilizing a cloud-native solution.
   1. Exceptions may be made if:
      1. The principal purpose of the web application is to spawn, facilitate, manage, execute, or monitor such background jobs, or
      2. Running background jobs in the same process as the web application will cause significant performance, stability, or security issues.
2. DO NOT write business logic in controller classes. DO write business logic in service classes that do not have any concerns or knowledge of web requests & responses. Such classes can be directly tested with unit tests, can be easily called from other services classes to facilitate code re-use and consistency.