From 55b94660049389d716cf2832339e2af3b5c1b950 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andreas=20=C3=96hlund?= Date: Thu, 31 Oct 2024 11:36:39 +0100 Subject: [PATCH 1/6] Asm loading docs review --- nservicebus/security/assembly-loading.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/nservicebus/security/assembly-loading.md b/nservicebus/security/assembly-loading.md index c051dcb09a4..e76c09a8694 100644 --- a/nservicebus/security/assembly-loading.md +++ b/nservicebus/security/assembly-loading.md @@ -1,8 +1,8 @@ --- title: Assembly loading -summary: Describes security-related aspects with assembly loading and how to further control the endpoint's behavior +summary: Describes security-related aspects with assembly loading and how to control the endpoint's behavior further component: Core -reviewed: 2022-02-15 +reviewed: 2024-10-31 related: - nservicebus/security - nservicebus/hosting/assembly-scanning @@ -10,7 +10,7 @@ related: ## Assembly scanning -NServiceBus relies on [assembly scanning](/nservicebus/hosting/assembly-scanning.md) to detect and load user-defined extension points into the endpoint. Depending on the assembly scanning configuration, endpoints will automatically load assemblies deployed to the configured probing paths. This behavior implies a high level of trust in assemblies being deployed along with the application and appropriate infrastructure configuration to prevent foreign access to the applications binary folders (e.g., using file system permissions and appropriate system accounts). +NServiceBus relies on [assembly scanning](/nservicebus/hosting/assembly-scanning.md) to detect and load user-defined extension points into the endpoint. Depending on the configuration, endpoints will automatically load assemblies deployed to the configured probing paths. This behavior implies a high level of trust in assemblies being deployed along with the application and appropriate infrastructure configuration to prevent foreign access to the application's binary folders (e.g., using file system permissions and appropriate system accounts). partial: disable-scanning @@ -21,4 +21,4 @@ Due to the various ways of defining, sharing, and deploying message contracts, a partial: disable-type-loading > [!NOTE] -> Loading types does not automatically create instances of the loaded type. NServiceBus prevents instantiation of types that are not considered [valid message types](/nservicebus/messaging/conventions.md). +> Loading types do not automatically create instances of the loaded type. NServiceBus prevents instantiation of types that are not considered [valid message types](/nservicebus/messaging/conventions.md). From 08af2228dee2dde08da516f6cf2c83570f46f351 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andreas=20=C3=96hlund?= Date: Thu, 31 Oct 2024 11:40:47 +0100 Subject: [PATCH 2/6] Oracle dialect docs review (#6882) --- persistence/sql/dialect-oracle.md | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/persistence/sql/dialect-oracle.md b/persistence/sql/dialect-oracle.md index dfb34246d8d..9b8e5a28aa9 100644 --- a/persistence/sql/dialect-oracle.md +++ b/persistence/sql/dialect-oracle.md @@ -2,7 +2,7 @@ title: Oracle dialect component: SqlPersistence related: -reviewed: 2022-02-18 +reviewed: 2024-10-31 versions: "[2,)" redirects: - nservicebus/sql-persistence/oracle-caveats @@ -10,14 +10,12 @@ redirects: --- > [!WARNING] -> SQL Persistence will run on [Oracle XE](https://www.oracle.com/technetwork/database/database-technologies/express-edition/overview/index.html). However it is strongly recommended to use commercial versions for any production system. It is also recommended to ensure that support agreements are in place. See [Oracle Support](https://www.oracle.com/support/index.html) for details. - +> SQL Persistence will run on [Oracle XE](https://www.oracle.com/technetwork/database/database-technologies/express-edition/overview/index.html). However it is strongly recommended to use commercial versions for production systems. It is also recommended to ensure that [Oracle support agreements](https://www.oracle.com/support/index.html) are in place. ## Supported database versions SQL persistence supports [Oracle 11g Release 2](https://docs.oracle.com/cd/E11882_01/readmes.112/e41331/chapter11204.htm) and above. - ## Usage Using the [Oracle.ManagedDataAccess NuGet Package](https://www.nuget.org/packages/Oracle.ManagedDataAccess). @@ -52,11 +50,10 @@ snippet: OracleSchema include: name-lengths -The SQL Persistence provides autonomy between endpoints by using separate tables for every endpoint based on the endpoint name. However, due to Oracle's 30-character limit on table names and index names in [Oracle 12.1 and below](https://docs.oracle.com/database/121/SQLRF/sql_elements008.htm#SQLRF00223), the SQL Persistence must make some compromises. +The SQL Persistence provides autonomy between endpoints by using separate tables for each endpoint based on the endpoint name. However, due to Oracle's 30-character limit on table names and index names in [Oracle 12.1 and below](https://docs.oracle.com/database/121/SQLRF/sql_elements008.htm#SQLRF00223), the SQL Persistence must make some compromises. include: name-length-validation-on - ### Table Names > [!NOTE] @@ -76,12 +73,11 @@ If an endpoint name is longer than 24 characters, an exception will be thrown, a snippet: TablePrefix - ### Sagas Tables generated for sagas reserve 27 characters for the saga name, leaving 3 characters for the `_PK` suffix for the table's primary key. -In order to accommodate as many characters for the saga name as possible, the [table prefix](/persistence/sql/install.md#table-prefix) is omitted from the saga table name. +To accommodate as many characters for the saga name as possible, the [table prefix](/persistence/sql/install.md#table-prefix) is omitted from the saga table name. | Saga Class Name | Table Name | Primary Key | |-----------------|:-------------:|:----------------:| @@ -98,7 +94,7 @@ where INDEX_NAME = 'SAGAIDX_525D1D4DC0C3DCD96947E1'; ``` > [!NOTE] -> If saga name or correlation property name change, the name of the index will also change. +> If the saga name or correlation property name changes, the name of the index will also change. If a saga name is longer than 27 characters, an exception will be thrown, and a [substitute table name must be specified](saga.md#table-structure-table-name). From 0fa5c4630485b31183e5e759fceda39993b4c9c2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andreas=20=C3=96hlund?= Date: Thu, 31 Oct 2024 11:58:52 +0100 Subject: [PATCH 3/6] Sharing contracts docs review --- nservicebus/messaging/sharing-contracts.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/nservicebus/messaging/sharing-contracts.md b/nservicebus/messaging/sharing-contracts.md index 7507c95a886..33e74353447 100644 --- a/nservicebus/messaging/sharing-contracts.md +++ b/nservicebus/messaging/sharing-contracts.md @@ -2,7 +2,7 @@ title: Sharing message contracts summary: How to define and share message contracts between endpoints. component: Core -reviewed: 2022-02-27 +reviewed: 2024-10-31 related: - nservicebus/messaging/messages-events-commands - nservicebus/messaging/unobtrusive-mode @@ -18,13 +18,14 @@ To minimize the amount of information and dependencies shared between endpoints, A sender and receiver of a given message must use the same message contract. Message contracts may be shared in various ways: * When all endpoints are located in a single solution, message contract assemblies may be directly referenced as project dependencies. -* When endpoints are located in multiple solutions, message contracts may be shared as [NuGet packages](https://docs.microsoft.com/en-us/nuget/create-packages/creating-a-package-msbuild). NuGet packages may be published on the file system or on a NuGet server. A [custom NuGet config file](https://docs.microsoft.com/en-us/nuget/reference/nuget-config-file) may be used to configure additional NuGet package sources. +* When endpoints are located in multiple solutions, message contracts may be shared as [NuGet packages](https://docs.microsoft.com/en-us/nuget/create-packages/creating-a-package-msbuild). NuGet packages may be published on the file system or a NuGet server. A [custom NuGet config file](https://docs.microsoft.com/en-us/nuget/reference/nuget-config-file) may be used to configure additional NuGet package sources. * Messages contracts may be shared as C# source files. ### NServiceBus dependency When [marker interfaces](/nservicebus/messaging/messages-events-commands.md#identifying-messages-marker-interfaces) are used to define messages, message contract projects have a dependency on the NServiceBus package. This may cause version conflicts when message contracts are updated in endpoints targeting older major versions of NServiceBus. This may be avoided by either: +* Use the [`NServiceBus.MessageInterfaces` assembly](t/samples/message-assembly-sharing/) available from Version 8.2 and onwards * Referencing the oldest used NServiceBus major version from message contracts projects. [NuGet dependency resolution](https://docs.microsoft.com/en-us/nuget/concepts/dependency-resolution) allows endpoints on newer major versions of NServiceBus to reference assemblies that target an older version of NServiceBus, but not vice versa. * Switching to [unobtrusive mode](/nservicebus/messaging/unobtrusive-mode.md). Unobtrusive mode allows an assembly to define message contracts without a dependency on the NServiceBus package, making it easy to share message contracts with endpoints targeting multiple versions of NServiceBus and running on various frameworks and platforms. @@ -38,7 +39,7 @@ When endpoints are updated independently from each other, it is important to tak After updating message contracts in an endpoint: * Other endpoints must be able to process messages sent or published by the updated endpoint. -* The updated endpoint must able to process messages sent or published by other endpoints. +* The updated endpoint must be able to process messages sent or published by other endpoints. NServiceBus includes a message header containing the message type's fully qualified name, which includes the assembly name and version number. Therefore, for best compatibility, it is recommended to maintain a stable [*assembly version*](https://docs.microsoft.com/en-us/dotnet/standard/library-guidance/versioning#assembly-version). The version of the contracts may be stated in the [*assembly file version*](https://docs.microsoft.com/en-us/dotnet/standard/library-guidance/versioning#assembly-file-version), [*assembly informational version*](https://docs.microsoft.com/en-us/dotnet/standard/library-guidance/versioning#assembly-informational-version), or *NuGet package version*. @@ -46,7 +47,7 @@ The [evolving message contracts guidance](/nservicebus/messaging/evolving-contra ## Breaking down large contract assemblies -In the early stages of developing a system, combining all events, commands, and messages in a single contracts assembly is often a good way to start. As the system grows, breaking down the contracts into smaller parts makes it easier to evolve a system safely. +In the early stages of developing a system, combining all events, commands, and messages in a single contract assembly is often a good way to start. As the system grows, breaking down the contracts into smaller parts makes it easier to evolve a system safely. For example, an endpoint may have many subscribers to its events, but only one or two endpoints sending it commands. A good way to evolve the command senders without requiring the subscribers to update their contract assemblies would be to separate the command and events into two assemblies: From a88df725c919b75811ea275854e7819363b1aa80 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andreas=20=C3=96hlund?= Date: Thu, 31 Oct 2024 12:00:12 +0100 Subject: [PATCH 4/6] Heartbeats docs review --- monitoring/heartbeats/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/monitoring/heartbeats/index.md b/monitoring/heartbeats/index.md index a889bb24dcb..e3ca7018a23 100644 --- a/monitoring/heartbeats/index.md +++ b/monitoring/heartbeats/index.md @@ -1,7 +1,7 @@ --- title: Heartbeats summary: Use the Heartbeat plugin to monitor the health of the endpoints -reviewed: 2022-02-28 +reviewed: 2024-10-31 component: Heartbeats isLearningPath: true versions: 'Heartbeats:*' @@ -14,7 +14,7 @@ redirects: The Heartbeat plugin enables endpoint health monitoring by sending regular heartbeat messages from the endpoint to a ServiceControl instance. The ServiceControl instance keeps track of which endpoint instances are sending heartbeats and which ones are not. > [!NOTE] -> Even if an endpoint is able to send heartbeat messages, other failures may occur within the endpoint and its host that prevent it from performing as expected. For example, the endpoint may not be able to process incoming messages, or it may be able to send messages to the ServiceControl queue but not to another queue. [Performance metrics](/monitoring/metrics/) can be used to monitor the processing of messages within an endpoint. +> Even if an endpoint can send heartbeat messages, other failures may occur within the endpoint and its host that prevent it from performing as expected. For example, the endpoint may not be able to process incoming messages, or it may be able to send messages to the ServiceControl queue but not to another queue. [Performance metrics](/monitoring/metrics/) can be used to monitor the processing of messages within an endpoint. ```mermaid graph LR @@ -43,4 +43,4 @@ To enable heartbeat monitoring in an environment: When an endpoint starts sending heartbeat messages, the ServiceControl instance will mark the endpoint as "active". If the ServiceControl instance stops receiving heartbeat messages from an endpoint, it will mark that endpoint as "inactive". -The heartbeats plugin is only able to determine if the endpoint is running and sending heartbeat messages. For more sophisticated endpoint health checks, develop a [custom check](/monitoring/custom-checks/) +The Heartbeats plugin is only able to determine if the endpoint is running and sending heartbeat messages. For more sophisticated endpoint health checks, develop a [custom check](/monitoring/custom-checks/) From e70406389a7565a125fcd7531d7dba4e2b7b0685 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andreas=20=C3=96hlund?= Date: Thu, 31 Oct 2024 12:05:44 +0100 Subject: [PATCH 5/6] Only show for version 9 --- nservicebus/messaging/sharing-contracts.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/nservicebus/messaging/sharing-contracts.md b/nservicebus/messaging/sharing-contracts.md index 33e74353447..551f3abfd35 100644 --- a/nservicebus/messaging/sharing-contracts.md +++ b/nservicebus/messaging/sharing-contracts.md @@ -25,7 +25,12 @@ A sender and receiver of a given message must use the same message contract. Mes When [marker interfaces](/nservicebus/messaging/messages-events-commands.md#identifying-messages-marker-interfaces) are used to define messages, message contract projects have a dependency on the NServiceBus package. This may cause version conflicts when message contracts are updated in endpoints targeting older major versions of NServiceBus. This may be avoided by either: +#if-version [9, ) + * Use the [`NServiceBus.MessageInterfaces` assembly](t/samples/message-assembly-sharing/) available from Version 8.2 and onwards + +#end-if + * Referencing the oldest used NServiceBus major version from message contracts projects. [NuGet dependency resolution](https://docs.microsoft.com/en-us/nuget/concepts/dependency-resolution) allows endpoints on newer major versions of NServiceBus to reference assemblies that target an older version of NServiceBus, but not vice versa. * Switching to [unobtrusive mode](/nservicebus/messaging/unobtrusive-mode.md). Unobtrusive mode allows an assembly to define message contracts without a dependency on the NServiceBus package, making it easy to share message contracts with endpoints targeting multiple versions of NServiceBus and running on various frameworks and platforms. From 6bc684496ab574cd80f816c4784bdebc294d9bf3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andreas=20=C3=96hlund?= Date: Thu, 31 Oct 2024 12:08:37 +0100 Subject: [PATCH 6/6] Fix link --- nservicebus/messaging/sharing-contracts.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/nservicebus/messaging/sharing-contracts.md b/nservicebus/messaging/sharing-contracts.md index 551f3abfd35..e2c40e935ef 100644 --- a/nservicebus/messaging/sharing-contracts.md +++ b/nservicebus/messaging/sharing-contracts.md @@ -25,12 +25,7 @@ A sender and receiver of a given message must use the same message contract. Mes When [marker interfaces](/nservicebus/messaging/messages-events-commands.md#identifying-messages-marker-interfaces) are used to define messages, message contract projects have a dependency on the NServiceBus package. This may cause version conflicts when message contracts are updated in endpoints targeting older major versions of NServiceBus. This may be avoided by either: -#if-version [9, ) - -* Use the [`NServiceBus.MessageInterfaces` assembly](t/samples/message-assembly-sharing/) available from Version 8.2 and onwards - -#end-if - +* Use the [`NServiceBus.MessageInterfaces` assembly](/samples/message-assembly-sharing/) available from Version 8.2 and onwards * Referencing the oldest used NServiceBus major version from message contracts projects. [NuGet dependency resolution](https://docs.microsoft.com/en-us/nuget/concepts/dependency-resolution) allows endpoints on newer major versions of NServiceBus to reference assemblies that target an older version of NServiceBus, but not vice versa. * Switching to [unobtrusive mode](/nservicebus/messaging/unobtrusive-mode.md). Unobtrusive mode allows an assembly to define message contracts without a dependency on the NServiceBus package, making it easy to share message contracts with endpoints targeting multiple versions of NServiceBus and running on various frameworks and platforms.