Azure Architecture guidance (#6140)

Author: timbussmann

.vscode/settings.json

@@ -5,5 +5,6 @@
         "MD025": {
             "front_matter_title": ""
         }
-    }
+    },
+    "dotnet.defaultSolution": "disable"
 }

README.md

@@ -206,6 +206,14 @@ upgradeGuideCoreVersions:
 
 To mark a page as belonging to the [Particular Software Learning Path](https://particular.net/learn) use `isLearningPath: true`.
 
+#### Calls to action
+
+```yaml
+callsToAction: ['architecture-review', 'solution-architect']
+```
+
+Calls to action are defined in `calls-to-action.yaml`.
+
 ### An example header for an article
 
 In the following example, whenever the URLs `/servicecontrol/sc-si` or `/servicecontrol/debugging-servicecontrol` are being requested, the given article will be rendered.

architecture/Architecture Guidance Diagrams.vsdx

@@ -0,0 +1,72 @@
+---
+title: Azure compute services
+summary:
+reviewed: 2023-07-18
+callsToAction: ['solution-architect', 'poc-help']
+---
+
+Azure offers a [wide range of options](https://learn.microsoft.com/en-us/azure/architecture/guide/technology-choices/compute-decision-tree) for hosting and running system components, ranging from full control of a virtual machine, including the operating system, to fully managed services.
+
+The Particular Service Platform may be hosted using several Azure hosting models:
+
+![](azure-compute-overview.png)
+
+## Serverless
+
+In serverless (also referred to as "Functions as a service (FaaS)") models, code is deployed directly to the service which runs it.
+
+[Azure Functions](https://azure.microsoft.com/en-us/products/functions) is Azure's serverless hosting model. NServiceBus supports integration with Azure Functions that allows deployment of new or existing NServiceBus applications into serverless environments with minimal effort. NServiceBus applications on Azure Functions can directly consume messages from Azure Service Bus. [Other Azure Functions triggers](https://learn.microsoft.com/en-us/azure/azure-functions/functions-triggers-bindings?tabs=csharp) can also [use NServiceBus to send messages to Azure Service Bus](/nservicebus/hosting/azure-functions-service-bus/#basic-usage-dispatching-outside-a-message-handler.md).
+
+![](azure-functions-host.png)
+
+[**Host NServiceBus applications on Azure Functions →**](/nservicebus/hosting/azure-functions-service-bus/)
+
+## Platform as a Service
+
+[Platform as a Service (PaaS)](https://en.wikipedia.org/wiki/Platform_as_a_service) models provide managed hosting environments where applications can be deployed without having to manage the underlying infrastructure, operating system, or runtime environments.
+
+### Azure App Services
+
+[Azure App Services](https://azure.microsoft.com/en-us/products/app-service/) has native support for deployment of .NET applications. NServiceBus endpoints can be integrated into [ASP.NET Core web applications](/nservicebus/hosting/asp-net.md) or run as background tasks using [WebJobs](https://learn.microsoft.com/en-us/azure/app-service/webjobs-create).
+
+### Containers
+
+[Containers](https://en.wikipedia.org/wiki/Containerization_(computing)) are a popular mechanism to deploy and host applications in PaaS services. NServiceBus can be used by containerized applications and deployed to services like:
+
+* [Azure App Services](https://azure.microsoft.com/en-us/products/app-service/) (using containers)
+* [Azure Container Instances](https://azure.microsoft.com/en-us/products/container-instances/)
+* [Azure Container Apps](https://azure.microsoft.com/en-us/products/container-apps/)
+* [Azure Kubernetes Services](https://azure.microsoft.com/en-us/products/kubernetes-service/)
+
+![](azure-container-host.png)
+
+[**Host NServiceBus applications in Docker containers →**](/nservicebus/hosting/docker-host/)
+
+## Infrastructure as a Service
+
+Infrastructure as a Service (IaaS) provides virtualized computing resources like virtual machines, storage, and networking that can be used to build and manage the required infrastructure.
+
+NServiceBus applications can easily be hosted on virtual machines. Popular techniques include:
+
+* [Integrating NServiceBus with the Microsoft Generic Host](/nservicebus/hosting/extensions-hosting.md)
+* [Custom hosted web applications](/nservicebus/hosting/web-application.md)
+* [Installing NServiceBus endpoints as Windows Services](/nservicebus/hosting/windows-service.md)
+* [Manually controlling NServiceBus lifecycle in an executable (e.g. Console or GUI applications)](/nservicebus/hosting/#self-hosting)
+* [Custom-managed Kubernetes clusters hosting container applications](/nservicebus/hosting/docker-host)
+
+## Choosing a hosting model
+
+The best choice of hosting model depends on the desired characteristics, such as:
+
+* **Scalability**: Different hosting options offer different approaches to scaling. Managed solutions are typically easier to scale on demand and can scale on more granular levels. In addition to the scalability, elasticity (the time required to scale up or down) may also factor into the choice. Azure documentation provides more information about [subscription and service limits](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/azure-subscription-service-limits).
+* **Pricing:** Managed services typically offer more dynamic pricing models that adjust with the demands of an application, in comparison with more rigid pricing models for infrastructure services. However, managed services typically charge more for their pricing units, so infrastructure services may be more economical for consistent demand. Azure offers a [pricing calculator](https://azure.microsoft.com/en-us/pricing/calculator/) to help understand a given service's pricing model.
+* **Portability:** Serverless models are primarily built on proprietary programming models, heavily tied to the cloud service vendor. Hosting models built on open standards make it easier to run components in other hosting environments. Additionally, it may also be desirable to run components using on-premises servers or workstations.
+* **Flexibility:** Lower-level infrastructure provides more control over the configuration and management of applications. Serverless offerings offer less flexibility due to the higher level of abstractions exposed to the code.
+* **Manageability:** Serverless and PaaS models remove the concerns about the underlying infrastructure challenges (e.g. automatic scaling, OS updates, load balancing, etc.), typically at the cost of flexibility. Managing and maintaining infrastructure using other models may require significant resources and knowledge.
+
+## Additional resources
+
+* [Microsoft compute service overview](https://learn.microsoft.com/en-us/azure/architecture/guide/technology-choices/compute-decision-tree)
+* [Selecting a host for NServiceBus endpoints](/nservicebus/hosting/selecting.md)
+* [Azure compute options for microservices](https://learn.microsoft.com/en-us/azure/architecture/microservices/design/compute-options)
+* [Azure pricing](https://azure.microsoft.com/en-us/pricing/)

architecture/azure/azure-compute-overview.png

@@ -0,0 +1,142 @@
+---
+title: Azure data stores
+summary:
+reviewed: 2023-07-18
+callsToAction: ['solution-architect', 'poc-help']
+---
+
+Azure offers [several data stores](https://learn.microsoft.com/en-us/azure/architecture/guide/technology-choices/data-store-decision-tree) which can be used with the Particular Service Platform.
+
+## Azure Cosmos DB
+
+[Azure Cosmos DB](https://learn.microsoft.com/en-us/azure/cosmos-db/introduction) is a globally distributed, multi-model, managed database service. It offers high availability, low latency, and automatic scaling to handle massive workloads across various data models, including document, key-value, graph, and column-family. Cosmos DB relies on partitioning to achieve high performance and scalability. When working with Cosmos DB, it is important to be familiar with the [partitioning model](https://learn.microsoft.com/en-us/azure/cosmos-db/partitioning-overview).
+
+:heavy_plus_sign: Pros:
+
+- Built and optimized for scalability
+- Multi-region support for high availability deployment
+- Supports multiple [data models](https://learn.microsoft.com/en-us/azure/cosmos-db/choose-api)
+- Fully managed
+- [Cosmos DB Emulator](https://learn.microsoft.com/en-us/azure/cosmos-db/local-emulator) can be used for local development and testing
+
+:heavy_minus_sign: Cons:
+
+- Atomic transactions only within the same partition
+- Careful partition planning is required
+- Fairly expensive
+
+[**Try the NServiceBus Cosmos DB sample →**](/samples/cosmosdb/simple/)
+
+Note: Cosmos DB offers _serverless_ and _provisioned throughput_ pricing models. When using _provisioned throughput_, Cosmos DB rejects further requests after the reserved Request Units are used. The [Cosmos DB pricing model documentation](https://learn.microsoft.com/en-us/azure/cosmos-db/how-pricing-works) has further information.
+
+## Azure Table Storage
+
+[Azure Table Storage](https://learn.microsoft.com/en-us/azure/storage/tables/table-storage-overview) is a NoSQL managed database service. It is a cost-effective and scalable solution for storing semi-structured and structured data, using a key-value pair schema. Designed for fast and efficient data retrieval, it is suitable for applications that require high-performance read and write operations, especially for large-scale, low-latency data storage and retrieval needs.
+
+:heavy_plus_sign: Pros:
+
+- Cost-effective
+- Partitioning is managed by the service
+- [Azurite emulator](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite) can be used for local development and testing
+
+:heavy_minus_sign: Cons:
+
+- Limited number of columns and single entity (row) size
+- Limited query capabilities
+- Multi-document transactions are limited to the same partition
+- No built-in support for complicated relationships
+
+[**Try the NServiceBus Azure Table Storage sample →**](/samples/azure/azure-table/simple/)
+
+Note: Applications built for Table Storage are compatible with Cosmos DB. See [this table](https://learn.microsoft.com/en-us/azure/cosmos-db/table/support) for a more in-depth comparison.
+
+## Azure SQL Database
+
+[Azure SQL Database](https://azure.microsoft.com/en-us/products/azure-sql/database/) is a fully managed database service based on the [Microsoft SQL Server database engine](https://learn.microsoft.com/en-us/sql/sql-server/?view=sql-server-ver16). 
+
+:heavy_plus_sign: Pros:
+
+- Fully managed
+- Rich built-in scaling options
+- Automatic backups and point-in-time restores
+- Active Geo-replication and zone-redundancy
+- Different pricing tiers for more cost control
+
+:heavy_minus_sign: Cons:
+
+- Migrating existing SQL server instances might be challenging
+
+Azure SQL Database is supported via the [NServiceBus SQL persistence package](/persistence/sql/).
+
+[**Try the NServiceBus SQL persistence sample →**](/samples/sql-persistence/simple/)
+
+## Azure SQL Managed Instance
+
+[Azure SQL Managed Instance](https://azure.microsoft.com/en-us/products/azure-sql/managed-instance) is a fully managed database service that provides a near-complete compatibility with the [Microsoft SQL Server database engine](https://learn.microsoft.com/en-us/sql/sql-server/?view=sql-server-ver16). It offers a managed solution for migrating and modernizing existing SQL Server applications with minimal code changes.
+
+:heavy_plus_sign: Pros:
+
+- High degree of compatibility with SQL Server
+- Supports cross-database queries
+- Predictable performance for large databases due to isolation
+- More database configuration options compared to Azure SQL Database
+
+:heavy_minus_sign: Cons:
+
+- Higher costs compared to manually managed database servers or Azure SQL Database
+
+Azure SQL Managed Instances is supported via the [NServiceBus SQL persistence package](/persistence/sql/).
+
+[**Try the NServiceBus SQL persistence sample →**](/samples/sql-persistence/simple/)
+
+## Other data store options
+
+Azure provides further relational database services compatible with NServiceBus, e.g. [Azure Database for MySQL](https://azure.microsoft.com/en-us/products/mysql) and [Azure Database for PostgreSQL](https://azure.microsoft.com/en-us/products/postgresql).
+
+While the presented storage options provide the best experience and integration with Azure, other storage options are available and may be valid options depending on the specific requirements. [Explore all supported data stores](/persistence/#supported-persisters).
+
+## Choosing a data store
+
+The following factors should be considered when choosing a data store:
+
+### Existing infrastructure
+
+Using existing infrastructure and know-how can significantly speed up the development process and lower the risks associated with using unfamiliar data store technologies. Unless the existing infrastructure and technologies do not meet the architectural requirements, they are a good default choice.
+
+### Compatibility
+
+When migrating or modernizing existing applications, data stores that are compatible with currently used protocols and languages simplify the switch to cloud-based services significantly. For example, a data store may understand PostgreSQL, SQL Server, and MongoDB dialects which allow applications using any of these dialects to connect with minimal changes required.
+
+### Transactions and consistency model
+
+Transaction capabilities can vary considerably between different data stores. Some only provide transactional consistency within the same partition or have limited transaction isolation levels. It is important to consider whether [eventual consistency](https://en.wikipedia.org/wiki/Eventual_consistency) is acceptable or [ACID](https://en.wikipedia.org/wiki/ACID) guarantees are required.
+
+### Storage model
+
+Data stores may have [different storage models](https://learn.microsoft.com/en-us/azure/architecture/guide/technology-choices/data-store-overview), optimized for different use cases. Data access patterns, the type of information to be stored, and relations between data should be considered when choosing the most appropriate storage model.
+
+### Scalability
+
+It may be important to consider how easily a data store's capacity and performance can be scaled up when required. Scaling requirements may also depend on the expected access patterns (e.g. the number of reads vs writes) or availability goals.
+
+### Legal and compliance
+
+Sometimes, data may be subject to legal requirements (e.g. data privacy) that require additional consideration of how a data store operates to ensure compliance. See the [Azure compliance offerings](https://learn.microsoft.com/en-us/compliance/regulatory/offering-home) for more detailed information on specific national, regional, and industry-specific regulations.
+
+### Costs
+
+Data stores can have significantly different pricing models. Charges may be based on a number of factors such as storage size, read/write operations, data transfer, or higher consistency guarantees. Some serverless pricing models may be optimized for when data is accessed infrequently or in bursts. The licensing model for a specific data store may also significantly impact the overall cost.
+
+### Portability
+
+Some data stores are only available in the cloud, with no on-premises equivalent. This may affect hosting, CI, testing and development. Some data stores support open standards or protocols which allows the use of on-premises or local data stores in those scenarios. For example, Cosmos DB supports PostgreSQL and MongoDB dialects.
+
+### Security
+
+Data stores offer various approaches to securing data using authentication and authorization. This may be provided by the data store itself or the data store may integrate with third party security services such as Azure IAM.
+
+## Additional resources
+
+- [Azure Architecture Center: Criteria for choosing a data store](https://learn.microsoft.com/en-us/azure/architecture/guide/technology-choices/data-store-considerations)
+- [What is Azure SQL Database?](https://learn.microsoft.com/en-us/azure/azure-sql/database/sql-database-paas-overview?view=azuresql)
+- [What is Azure SQL Managed Instance?](https://learn.microsoft.com/en-us/azure/azure-sql/managed-instance/sql-managed-instance-paas-overview?view=azuresql)

architecture/azure/azure-container-host.png

@@ -0,0 +1,33 @@
+---
+title: Event-driven architecture style on Azure
+summary:
+reviewed: 2023-07-18
+callsToAction: ['solution-architect', 'ADSD']
+---
+
+The Azure Architecture Center describes the [event-driven architecture style](https://learn.microsoft.com/en-us/azure/architecture/guide/architecture-styles/event-driven) as consisting of event producers and event consumers which can use the [publish/subscribe](https://learn.microsoft.com/en-us/azure/architecture/patterns/publisher-subscriber) (also called pub/sub) model.
+
+The Particular Service Platform implements [pub/sub](/nservicebus/messaging/publish-subscribe/), with each [NServiceBus endpoint](/nservicebus/endpoints) acting as a publisher (event producer) and/or subscriber (endpoint consumer).
+
+![](azure-event-driven-architecture.png)
+
+### Components
+
+* NServiceBus publisher (event producer): Publishes events with business meaning in a reliable fire-and-forget style and has no knowledge of subscribers (there may be none).
+* NServiceBus subscriber (event consumer): Subscribed to a specific event type and reacts to it. A subscriber may also be an event publisher, since processing an event may lead to publishing more events.
+* Azure Service Bus: The messaging service that brings together publisher and subscriber without explicitly referencing or depending on each other.
+
+### Challenges
+
+* Events order: Subscribers cannot rely on the order they receive published events, which may be affected by many factors such as concurrency, scaling, retries, partitioning, etc. Events and subscribers should be designed so that they [do not rely on strict ordering to execute business processes](https://particular.net/blog/you-dont-need-ordered-delivery).
+* Event data: Putting too much data on messages couples publishers and subscribers, defeating one of the main benefits of messaging in the first place. Bloated event contracts indicate sub-optimal service boundaries, perhaps drawn along technical constraints rather than business rules, or [data distribution](/nservicebus/concepts/data-distribution.md) over messaging. Well designed events are [lightweight contracts](https://particular.net/blog/putting-your-events-on-a-diet), focusing on sharing IDs rather than data.
+
+### Technology choices
+
+In event-driven architectures, components are decoupled, allowing choice of the most suitable [compute](compute.md) and [data store](data-stores.md) options for a specific component or set of components.
+
+An event-driven approach requires support for the publish-subscribe model. NServiceBus supports the publish-subscribe model for [Azure Service Bus and Azure Storage Queues](messaging.md), independent of the underlying service capabilities.
+
+## Additional resources
+
+* [Azure Architecture Center—Event-driven architecture style](https://learn.microsoft.com/en-us/azure/architecture/guide/architecture-styles/event-driven)