Hacktoberfest 2026: as issues que os mantenedores marcaram para outubro, abertas e boas para iniciantes. Ver issues do Hacktoberfest

Architecture Guidelines

Aberta
  • Algo errado?
#84 11 comentários 3 reações 0 responsáveis Ver no GitHub

Mantenedores costumam responder em até 1 dia

Ninguém assumiu esta issue ainda.

Avaliação

Dificuldade
5/5
Tempo estimado
Mais de uma semana
Facilidade para iniciantes
20/100
Tipo de issue
Documentação
Clareza
Precisa de esclarecimento
Status de atividade
Estagnada
Stack de tecnologia
csharp
Domínio
documentation

Direção de pesquisa

Comece revisando o README e os documentos existentes de diretrizes de codificação no repositório e, em seguida, compare-os com as seções propostas Project documentation, General Architecture e Web Application Architecture. A issue não nomeia arquivos nem define um escopo acordado; para considerá-la concluída, seria necessário um conjunto de diretrizes aceito e acionável, além de um local claro para elas.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

proposal

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.
Linguagem predominante
C#
Estrelas
12
Forks
16
Merge médio
2min
PRs com merge (30d)
10

Preparar o ambiente

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de IntelliTect/CodingGuidelines

Todas as issues de IntelliTect/CodingGuidelines

Issues semelhantes

Mais issues de C#

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.