Skip to content

Design Guidelines

Design Guidelines and Best Practices

Naming

Events

  • Add Event suffix for notifications: SomethingHappenedEvent
  • Add Message suffix for commands: DoSomethingMessage. Messages should have one consumer.
  • Add project name to Service Bus topic names: wallet-card
  • Event properties should use camelCase when serialized, meaning they need to be annotated with a JsonProperty attribute.

Models, DB Entities and DTOs

  • API models should have Model suffix: UserModel.
  • Service DTOs should not have any prefixes/suffixes: User.
  • DB entities should have Entity suffix: UserEntity.
  • Properties on classes that are exposed outside the service (i.e. Events and their respective Models in Service.Contracts) should use camelCase when serialized, meaning they need to be annotated with a JsonProperty attribute.

Configuration

Configuration files

  • Always create config files in app-settings folder when introducing new cinfiguration class.
  • Always specify all config class properties explicitly in config files.
  • Give your config file a meaningful name.
  • Add area prefix to config files.

Configuration classes

  • Secrets should not contain configuration values.
  • Configuration classes should not contain secrets.
  • Create two classes if you need both sensitive and non-sensitive values.
  • Don't set default values in the code. Set them in json files!
  • Don't hardcode connection strings/passwords/keys in secret classes.
  • Apply NotLogged/LogMasked attributes on all secret values.
  • Apply validation attributes.

Code organization

Namespaces

  • Split code into namespaces by domain, i.e. User namespace should contain code dealing with user stuff, i.e. repositories, models, entities, services and etc. Don't create namespaces, like Repositories, Services and etc.

General

try/catch blocks

  • Avoid generic try/catch blocks. Do it only if you really need to silence all errors, like in an event handler code that should never be retried.

HTTP Client

  • HTTP Client instances must be singletons
  • Use HttpClientFactory class to get HttpClient instances.

Event Handlers

  • Create event handlers as a separate class.
  • Call corresponding service(s) inside, do error handling and decide whether to retry the event, abandon or complete it.