diff --git a/develop/best_practices/Best_practices.md b/develop/best_practices/Best_practices.md index 2c3b7ab14f..fac01bd7da 100644 --- a/develop/best_practices/Best_practices.md +++ b/develop/best_practices/Best_practices.md @@ -8,3 +8,9 @@ In this section: - [Unit testing](xref:Unit_testing) - [XML documentation comments](xref:Xml_Documentation_Comments) + +> [!TIP] +> See also: +> +> - [Best practices for protocol development](xref:CodingGuidelines) +> - [Best practices for Automation script development](xref:Automation_best_practices) diff --git a/develop/codingguidelines/AdminMetadata/CODAdminMetadata.md b/develop/codingguidelines/AdminMetadata/CODAdminMetadata.md deleted file mode 100644 index c5328e0567..0000000000 --- a/develop/codingguidelines/AdminMetadata/CODAdminMetadata.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -uid: CODAdminMetadata ---- - -# Administrative metadata - -In this section: - -- [Comment metadata](xref:Comment_metadata) - -- [Protocol metadata](xref:Protocol_metadata) diff --git a/develop/codingguidelines/Attention/CODAttention.md b/develop/codingguidelines/Attention/CODAttention.md deleted file mode 100644 index 3730454fc6..0000000000 --- a/develop/codingguidelines/Attention/CODAttention.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -uid: CODAttention ---- - -# Points of attention - -In this section: - -- [Skyline Driver Passport Platform](xref:Skyline_Driver_Passport_Platform) - -- [Minimum DMA version](xref:Minimum_DMA_version) diff --git a/develop/codingguidelines/CodingGuidelines.md b/develop/codingguidelines/CodingGuidelines.md index 38d5682a9e..4d2f1194f1 100644 --- a/develop/codingguidelines/CodingGuidelines.md +++ b/develop/codingguidelines/CodingGuidelines.md @@ -2,28 +2,13 @@ uid: CodingGuidelines --- -# DataMiner Protocol Development Guidelines +# Best practices for protocol development -The guidelines specified in this section are designed to uphold the level of quality of DMS protocols by improving readability, maintainability, and performance. +This section lists best practices and guidelines designed to uphold the quality level of DataMiner protocols (a.k.a. connectors) by improving readability, maintainability, and performance. -By adhering to these guidelines, we can ensure that protocols have a consistent look, and thereby increase maintainability and readability. The guidelines also increase reusability, stability and performance. +By adhering to these best practices and guidelines, you can ensure that protocols have a consistent look and thereby increase maintainability and readability, and you will also increase the reusability, stability, and performance of the protocols you develop. -When a new protocol version is created, you must verify every item in the protocol development checklist and specify "OK", "Fail" or "NA" every time. +A checklist is available [on DataMiner Dojo](https://community.dataminer.services/protocol-development-downloads/), which should be used whenever a new protocol version is created. In the checklist, verify every item and specify "OK", "Fail", or "NA", as appropriate. -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 (see ). - -In this section: - -- [General](xref:CODGeneral#general) - -- [Administrative metadata](xref:CODAdminMetadata#administrative-metadata) - -- [User interface](xref:CODUserInterface#user-interface) - -- [Monitoring](xref:CODMonitoring#monitoring) - -- [Protocol](xref:CODProtocol#protocol) - -- [Validation](xref:CODValidation#validation) - -- [Points of attention](xref:CODAttention#points-of-attention) +> [!NOTE] +> The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this section are to be interpreted as described in RFC 2119 (see ). diff --git a/develop/codingguidelines/General/CODGeneral.md b/develop/codingguidelines/General/CODGeneral.md deleted file mode 100644 index 619bf4a13a..0000000000 --- a/develop/codingguidelines/General/CODGeneral.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -uid: CODGeneral ---- - -# General - -In this section: - -- [Protocol name](xref:Protocol_name) - -- [Formatting](xref:Formatting) - -- [Names](xref:Names) - -- [ID values](xref:ID_values) - -- [C code conventions](xref:C_code_conventions) diff --git a/develop/codingguidelines/General/C_code_conventions.md b/develop/codingguidelines/General/C_code_conventions.md deleted file mode 100644 index b524829d7d..0000000000 --- a/develop/codingguidelines/General/C_code_conventions.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -uid: C_code_conventions ---- - -# C# code conventions - -Try to use the C# code style guidelines described below. From 2018 onwards, these guidelines must always be followed. - -- [General](xref:CODGeneral) - -- [Capitalization style](xref:Capitalization_style) - -- [Namespaces](xref:Namespaces) - -- [Classes, structs and interfaces](xref:Classes_structs_and_interfaces) - -- [Enumerations](xref:Enumerations) - -- [Methods](xref:Methods) - -- [Properties](xref:Properties) - -- [Fields](xref:Fields) - -- [Parameters](xref:Parameters1#parameters) - -- [Local variables](xref:Local_variables) - -- [Ordering](xref:Ordering) - -- [Layout](xref:Layout) - -- [Spacing](xref:Spacing) - -- [Readability](xref:Readability) - -- [Maintainability](xref:Maintainability) - -- [XML documentation](xref:XML_documentation) - -- [Commenting](xref:Commenting) diff --git a/develop/codingguidelines/General/Formatting.md b/develop/codingguidelines/General/Formatting.md deleted file mode 100644 index 62394aa426..0000000000 --- a/develop/codingguidelines/General/Formatting.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -uid: Formatting ---- - -# Formatting - -- [Indentation](xref:Indentation) - -- [Alignment and wording](xref:Alignment_and_wording) diff --git a/develop/codingguidelines/General/ID_values.md b/develop/codingguidelines/General/ID_values.md deleted file mode 100644 index bc82dc28fc..0000000000 --- a/develop/codingguidelines/General/ID_values.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -uid: ID_values ---- - -# ID values - -- [ID range](xref:ID_range) - -- [ID gaps](xref:ID_gaps) - -- [ID ordering](xref:ID_ordering) - -- [ID grouping](xref:ID_grouping) diff --git a/develop/codingguidelines/General/Names.md b/develop/codingguidelines/General/Names.md deleted file mode 100644 index 8c3a38bb7b..0000000000 --- a/develop/codingguidelines/General/Names.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -uid: Names ---- - -# Names - -- [Unique and meaningful names](xref:Unique_and_meaningful_names) - -- [Parameter names](xref:Parameter_names) - -- [QAction and Action names](xref:QAction_and_Action_names) - -- [Trigger names](xref:Trigger_names) - -- [Group names](xref:Group_names) - -- [DMS element names](xref:DMS_element_names) diff --git a/develop/codingguidelines/Monitoring/CODMonitoring.md b/develop/codingguidelines/Monitoring/CODMonitoring.md deleted file mode 100644 index fc13d0e5db..0000000000 --- a/develop/codingguidelines/Monitoring/CODMonitoring.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -uid: CODMonitoring ---- - -# Monitoring - -In this section: - -- [Trending](xref:Trending1#trending) - -- [Alarming](xref:Alarming1#alarming) diff --git a/develop/codingguidelines/Protocol/API.md b/develop/codingguidelines/Protocol/API.md deleted file mode 100644 index 76b070bd9f..0000000000 --- a/develop/codingguidelines/Protocol/API.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -uid: API ---- - -# API - -- [Device API](xref:Device_API) - -- [DataMiner API](xref:DataMiner_API) diff --git a/develop/codingguidelines/Protocol/CODProtocol.md b/develop/codingguidelines/Protocol/CODProtocol.md deleted file mode 100644 index dc117f0a48..0000000000 --- a/develop/codingguidelines/Protocol/CODProtocol.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -uid: CODProtocol ---- - -# Protocol - -In this section: - -- [API](xref:API) - -- [Communication](xref:Communication1#communication) - -- [Logic](xref:Logic1#logic) - -- [Timers](xref:Timers1#timers) - -- [DVE](xref:DVE) - -- [Tables](xref:Tables1#tables) - -- [Parameters](xref:Parameters3#parameters) - -- [QActions](xref:QActions) - -- [.NET Recommendations](xref:_NET_Recommendations#net-recommendations) diff --git a/develop/codingguidelines/Protocol/DVE.md b/develop/codingguidelines/Protocol/DVE.md deleted file mode 100644 index 8b3b4842dd..0000000000 --- a/develop/codingguidelines/Protocol/DVE.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -uid: DVE ---- - -# DVE - -- [DVE names](xref:DVE_names) - -- [DVE export rules](xref:DVE_export_rules) - -- [DVE child element deletion](xref:DVE_child_element_deletion) diff --git a/develop/codingguidelines/Protocol/Logic1.md b/develop/codingguidelines/Protocol/Logic1.md deleted file mode 100644 index d053a3a315..0000000000 --- a/develop/codingguidelines/Protocol/Logic1.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -uid: Logic1 ---- - -# Logic - -- [Operation duration](xref:Operation_duration) - -- [Operation execution delay](xref:Operation_execution_delay) - -- [Value update verification](xref:Value_update_verification) - -- [Protocol threads](xref:Protocol_threads) diff --git a/develop/codingguidelines/Protocol/Parameters3.md b/develop/codingguidelines/Protocol/Parameters3.md deleted file mode 100644 index caca8c6d9f..0000000000 --- a/develop/codingguidelines/Protocol/Parameters3.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -uid: Parameters3 ---- - -# Parameters - -- [Saving parameters](xref:Saving_parameters) - -- [Loading parameters in SLElement](xref:Loading_parameters_in_SLElement) diff --git a/develop/codingguidelines/Protocol/QActions.md b/develop/codingguidelines/Protocol/QActions.md deleted file mode 100644 index 9f87508487..0000000000 --- a/develop/codingguidelines/Protocol/QActions.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -uid: QActions ---- - -# QActions - -- [Functionality](xref:Functionality) - -- [Maintainability](xref:Maintainability1#maintainability) - -- [Robustness](xref:Robustness) - -- [Conditional execution](xref:Conditional_execution) - -- [Localization](xref:Localization) - -- [Inter-process communication](xref:Inter-process_communication#inter-process-communication) - -- [Exception handling](xref:Exception_handling) - -- [Logging](xref:Logging) - -- [Multi-threading](xref:Multi-threading1#multi-threading) - -- [Thread.Sleep](xref:Thread_Sleep#threadsleep) - -- [StyleCop](xref:StyleCop) diff --git a/develop/codingguidelines/Protocol/Saving_parameters.md b/develop/codingguidelines/Protocol/Saving_parameters.md index 9eb8c15c0f..8e645478e0 100644 --- a/develop/codingguidelines/Protocol/Saving_parameters.md +++ b/develop/codingguidelines/Protocol/Saving_parameters.md @@ -4,4 +4,14 @@ uid: Saving_parameters # Saving parameters -- Parameters must only be saved when necessary. When a parameter is saved, it is saved in the database, leading to additional processing and memory usage. +To make sure your on-premises databases remain in good shape and do not get cluttered with unnecessary data, or to ensure a cost-efficient solution in case you make use of Storage as a Service, it is important to avoid storing unnecessary data. As a consequence, parameters must only be saved when this is really necessary. + +Here are some things you can do to make sure no more data is saved than necessary: + +- Only add a [save](xref:Protocol.Params.Param-save) attribute to a parameter if it is really necessary. + +- If you know a parameter will change frequently, but it definitely needs to be saved, specify a [saveInterval](xref:Protocol.Params.Param-saveInterval) attribute. + +- By default, the keys of a table are saved. Avoid fully cleaning and repopulating a table when updating values. + +- Consider using a [volatile table](xref:AdvancedDataMinerDataPersistencePersistingTables#volatile-tables). Table that do not contain any monitored parameters could be a good fit for this. diff --git a/develop/codingguidelines/Protocol/StyleCop.md b/develop/codingguidelines/Protocol/StyleCop.md index 1d30d3ac8d..565269e0bc 100644 --- a/develop/codingguidelines/Protocol/StyleCop.md +++ b/develop/codingguidelines/Protocol/StyleCop.md @@ -4,8 +4,7 @@ uid: StyleCop # StyleCop -- StyleCop does not indicate any warnings. For an overview of the StyleCop rules that need to be adhered to, refer to [C code conventions](xref:C_code_conventions). +- StyleCop does not indicate any warnings. For an overview of the StyleCop rules that need to be adhered to, refer to [C code conventions](xref:General_COD). > [!TIP] -> See also: -> +> See also: diff --git a/develop/codingguidelines/Protocol/Tables1.md b/develop/codingguidelines/Protocol/Tables1.md deleted file mode 100644 index dd65610c0b..0000000000 --- a/develop/codingguidelines/Protocol/Tables1.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -uid: Tables1 ---- - -# Tables - -- [Primary keys](xref:Primary_keys1#primary-keys) - -- [Display keys](xref:Display_keys1#display-keys) - -- [Data handling](xref:Data_handling) - -- [Integrity constraints](xref:Integrity_constraints) - -- [Preserve state option](xref:Preserve_state_option) - -- [Clear Table Data on Polling Disable](xref:Clear_Table_Data_on_Polling_Disable) diff --git a/develop/codingguidelines/Protocol/Timers1.md b/develop/codingguidelines/Protocol/Timers1.md deleted file mode 100644 index 41e9d4478d..0000000000 --- a/develop/codingguidelines/Protocol/Timers1.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -uid: Timers1 ---- - -# Timers - -- [Number of timers](xref:Number_of_timers) - -- [Default timer speeds](xref:Default_timer_speeds) - -- [Timer speed restrictions](xref:Timer_speed_restrictions) - -- [Starting/stopping timers](xref:Starting_stopping_timers#startingstopping-timers) - -- [Timer content](xref:Timer_content) diff --git a/develop/codingguidelines/UserInterface/CODUserInterface.md b/develop/codingguidelines/UserInterface/CODUserInterface.md deleted file mode 100644 index b82b954221..0000000000 --- a/develop/codingguidelines/UserInterface/CODUserInterface.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -uid: CODUserInterface ---- - -# User interface - -In this section: - -- [Element wizard](xref:Element_wizard) - -- [Protocol pages](xref:Protocol_pages) - -- [Displayed text](xref:Displayed_text) - -- [Parameters](xref:Parameters2#parameters) - -- [Tables](xref:Tables_COD) - -- [Buttons](xref:Buttons) - -- [Toggle buttons](xref:Toggle_buttons) - -- [Page buttons](xref:Page_buttons) - -- [Progress bars](xref:Progress_bars) diff --git a/develop/codingguidelines/UserInterface/Displayed_text.md b/develop/codingguidelines/UserInterface/Displayed_text.md index d82d9ccfd1..652c52e801 100644 --- a/develop/codingguidelines/UserInterface/Displayed_text.md +++ b/develop/codingguidelines/UserInterface/Displayed_text.md @@ -4,7 +4,7 @@ uid: Displayed_text # Displayed text -- All displayed textual items, e.g. parameter descriptions, button values, discrete values, tooltips, element wizard text etc. that will be displayed in DataMiner must be user-friendly and adhere to the following rules. +All displayed textual items, e.g. parameter descriptions, button values, discrete values, tooltips, element wizard text, etc. that will be displayed in DataMiner must be user-friendly and adhere to the following rules: - [Title case](xref:Title_case) diff --git a/develop/codingguidelines/UserInterface/Element_wizard.md b/develop/codingguidelines/UserInterface/Element_wizard.md deleted file mode 100644 index 9fec0a35a1..0000000000 --- a/develop/codingguidelines/UserInterface/Element_wizard.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -uid: Element_wizard ---- - -# Element wizard - -- [Default settings](xref:Default_settings) - -- [Connection names](xref:Connection_names) diff --git a/develop/codingguidelines/UserInterface/Page_buttons.md b/develop/codingguidelines/UserInterface/Page_buttons.md deleted file mode 100644 index 8ad1b0d8cf..0000000000 --- a/develop/codingguidelines/UserInterface/Page_buttons.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -uid: Page_buttons ---- - -# Page buttons - -- [Page button dimensions](xref:Page_button_dimensions) - -- [Page button labels](xref:Page_button_labels) - -- [Page button content](xref:Page_button_content) diff --git a/develop/codingguidelines/UserInterface/Parameters2.md b/develop/codingguidelines/UserInterface/Parameters2.md deleted file mode 100644 index 301290e873..0000000000 --- a/develop/codingguidelines/UserInterface/Parameters2.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -uid: Parameters2 ---- - -# Parameters - -- [Parameter descriptions and values](xref:Parameter_descriptions_and_values) - -- [Unit of measure](xref:Unit_of_measure) - -- [Value range](xref:Value_range) - -- [Date and time values](xref:Date_and_time_values) - -- [Exceptional states](xref:Exceptional_states) - -- [Tooltips](xref:Tooltips) - -- [Octet values](xref:Octet_values) - -- [Error Counter values](xref:Error_Counter_values) diff --git a/develop/codingguidelines/UserInterface/Protocol_pages.md b/develop/codingguidelines/UserInterface/Protocol_pages.md deleted file mode 100644 index b8c4adca1e..0000000000 --- a/develop/codingguidelines/UserInterface/Protocol_pages.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -uid: Protocol_pages ---- - -# Protocol pages - -- [Page layout](xref:Page_layout) - -- [Look and feel](xref:Look_and_feel) - -- [General page](xref:General_page) - -- [Core functionality pages](xref:Core_functionality_pages) - -- [Web interface page](xref:Web_interface_page) diff --git a/develop/codingguidelines/UserInterface/Tables_COD.md b/develop/codingguidelines/UserInterface/Tables_COD.md deleted file mode 100644 index e7930c5ea6..0000000000 --- a/develop/codingguidelines/UserInterface/Tables_COD.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -uid: Tables_COD ---- - -# Tables - -- [Column names](xref:Column_names) - -- [Column descriptions](xref:Column_descriptions) - -- [Column header options](xref:Column_header_options) diff --git a/develop/codingguidelines/Validation/CODValidation.md b/develop/codingguidelines/Validation/CODValidation.md deleted file mode 100644 index ba2e5c440b..0000000000 --- a/develop/codingguidelines/Validation/CODValidation.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -uid: CODValidation ---- - -# Validation - -In this section: - -- [General](xref:General1#general) - -- [Spell checker](xref:Spell_checker) - -- [DIS validator](xref:DIS_validator) - -- [Stream Viewer](xref:Stream_Viewer) - -- [Log files](xref:Log_files) - -- [Alarm Console](xref:Alarm_Console) diff --git a/develop/devguide/Automation/Automation_best_practices.md b/develop/devguide/Automation/Automation_best_practices.md new file mode 100644 index 0000000000..42e6b063a1 --- /dev/null +++ b/develop/devguide/Automation/Automation_best_practices.md @@ -0,0 +1,25 @@ +--- +uid: Automation_best_practices +--- + +# Best practices for Automation script development + +## Generating information events + +To make sure your on-premises databases remain in good shape and do not get cluttered with unnecessary data, or to ensure a cost-efficient solution in case you make use of Storage as a Service, it is important to avoid producing unnecessary information events. As a general rule of thumb, when developing Automation scripts, use information events in a meaningful way to do **audit trailing for events that are useful for end users**, e.g. CRUD actions on DataMiner objects such as "Start booking" or "Script x executed by y". Do not use them if they are only useful to you as a DevOps engineer creating the scripts in order to debug a flow. + +Keep the following best practices in mind: + +- Avoid *Engine.GenerateInformation* for tracing. While it is very informative to see the progress of a script that is running, if you have a script that runs a lot, this quickly becomes overhead. + + Instead, use *engine.Log* for tracing. This way, instead of generating information events, you will add lines in the Automation log file. If for some reason, you want convert these log lines to information events for a short amount of time, consider using preprocessor directives, or make a wrapper that allows you to quickly switch between information events and log lines. + +- Avoid generating information events when your script executes sets. + + By default, DataMiner generates an information event when an Automation script executes a set operation. If at all possible, avoid the generation of these information events by using the [Engine.SetFlag](xref:Skyline.DataMiner.Automation.Engine.SetFlag(Skyline.DataMiner.Automation.RunTimeFlags)) method. + +- Avoid generating information events at the start and end of a subscript. + + By default, DataMiner generates an information event when an Automation script is started and when it finishes. + + If you have created an Automation script that launches subscripts, use the [SkipStartedInfoEvent](xref:Skyline.DataMiner.Automation.SubScriptOptions.SkipStartedInfoEvent) option so that these information events are not generated for the subscripts. Alternatively, in case you run the script from code, you can add `SKIP_STARTED_INFO_EVENT:TRUE` in the options array of the *ExecuteScriptMessage* message. diff --git a/develop/devguide/Automation/index.md b/develop/devguide/Automation/index.md index bf5cea6be6..9248369e87 100644 --- a/develop/devguide/Automation/index.md +++ b/develop/devguide/Automation/index.md @@ -7,4 +7,5 @@ uid: AutomationDevGuideIndex - [Getting started with Automation script development](xref:GettingStartedWithAutomationScriptDevelopment) - [Automation script actions](xref:AutomationActions) - [UIBlockType overview](xref:UIBlockTypesOverview) +- [Best practices](xref:Automation_best_practices) - [How-tos](xref:How_to_make_your_automation_scripts_debug_ready) diff --git a/develop/devguide/Connector/AdvancedDVEs.md b/develop/devguide/Connector/AdvancedDVEs.md index aa6f763a21..496759189b 100644 --- a/develop/devguide/Connector/AdvancedDVEs.md +++ b/develop/devguide/Connector/AdvancedDVEs.md @@ -40,4 +40,4 @@ DataMiner Class Library: Coding guidelines: -- [DVE](xref:DVE) +- [DVE](xref:DVE_names) diff --git a/develop/devguide/Connector/Connections.md b/develop/devguide/Connector/Connections.md index 564c774a97..039f6dc248 100644 --- a/develop/devguide/Connector/Connections.md +++ b/develop/devguide/Connector/Connections.md @@ -25,6 +25,6 @@ In this section: Coding guidelines: -- [Element Wizard](xref:Element_wizard) +- [Element Wizard](xref:Default_settings) - [Communication](xref:Communication1) -- [Points of Attention](xref:CODAttention) +- [Points of Attention](xref:Skyline_Driver_Passport_Platform) diff --git a/develop/devguide/Connector/Logic.md b/develop/devguide/Connector/Logic.md index 932ecf3bb5..c248041ac9 100644 --- a/develop/devguide/Connector/Logic.md +++ b/develop/devguide/Connector/Logic.md @@ -33,6 +33,6 @@ DataMiner Protocol Markup Language: Coding guidelines: -- [Logic](xref:Logic1) -- [Timers](xref:Timers1) -- [QActions](xref:QActions) +- [Logic](xref:Operation_duration) +- [Timers](xref:Number_of_timers) +- [QActions](xref:Functionality) diff --git a/develop/devguide/Connector/Metadata.md b/develop/devguide/Connector/Metadata.md index bf477f0935..11b4c0b9f6 100644 --- a/develop/devguide/Connector/Metadata.md +++ b/develop/devguide/Connector/Metadata.md @@ -24,4 +24,4 @@ Every connector contains the following metadata: Coding guidelines: -- [Administrative Metadata](xref:CODAdminMetadata) +- [Administrative Metadata](xref:Comment_metadata) diff --git a/develop/devguide/Connector/Monitoring.md b/develop/devguide/Connector/Monitoring.md index 6231be715a..bd55d42fdc 100644 --- a/develop/devguide/Connector/Monitoring.md +++ b/develop/devguide/Connector/Monitoring.md @@ -18,4 +18,4 @@ DataMiner Protocol Markup Language: Coding Guidelines: -- [Monitoring](xref:CODMonitoring) \ No newline at end of file +- [Monitoring](xref:Trending1) \ No newline at end of file diff --git a/develop/devguide/Connector/Troubleshooting/Use_cases/Debugging_connectors_serial_communication_returning_command_echoes.md b/develop/devguide/Connector/Troubleshooting/Use_cases/Debugging_connectors_serial_communication_returning_command_echoes.md index 553b4ac7b9..ac7fbb84dd 100644 --- a/develop/devguide/Connector/Troubleshooting/Use_cases/Debugging_connectors_serial_communication_returning_command_echoes.md +++ b/develop/devguide/Connector/Troubleshooting/Use_cases/Debugging_connectors_serial_communication_returning_command_echoes.md @@ -103,6 +103,6 @@ The test above will reveal if the router is sensitive to sending too many comman For example: -- Reduce the speed of the polling cycle used to monitor the current state of the router. Make sure it is in line with the recommendations in the development guide (see [Timers](xref:Timers1)). +- Reduce the speed of the polling cycle used to monitor the current state of the router. Make sure it is in line with the recommendations in the development guide (see [Timers](xref:Number_of_timers)). - When setting a crosspoint, use the router’s “SET” confirmation to refresh the matrix component instead of sending the “Status Request” again. This will avoid an overload of this command when a large number of crosspoints are set. diff --git a/develop/devguide/Connector/UIComponents.md b/develop/devguide/Connector/UIComponents.md index 532b723a15..31b9fd61f9 100644 --- a/develop/devguide/Connector/UIComponents.md +++ b/develop/devguide/Connector/UIComponents.md @@ -34,4 +34,4 @@ A protocol typically contains a number of parameters that will be displayed (e.g Coding Guidelines -- [User interface](xref:CODUserInterface) +- [User interface](xref:Default_settings) diff --git a/develop/devguide/Connector/UIComponentsTreeControl.md b/develop/devguide/Connector/UIComponentsTreeControl.md index 87795e537c..6029a92857 100644 --- a/develop/devguide/Connector/UIComponentsTreeControl.md +++ b/develop/devguide/Connector/UIComponentsTreeControl.md @@ -27,4 +27,4 @@ DataMiner Protocol Markup Language: Coding guidelines -- [User Interface](xref:CODUserInterface) +- [User Interface](xref:Default_settings) diff --git a/develop/index.md b/develop/index.md index 0dc6b2cacc..9bb748ced0 100644 --- a/develop/index.md +++ b/develop/index.md @@ -21,29 +21,26 @@ uid: DevelopIndex
- +
- +
-
- -
-
- -
+
+ +
diff --git a/develop/schemadoc/Protocol/ColumnOptionOptionsOverview.md b/develop/schemadoc/Protocol/ColumnOptionOptionsOverview.md index 634cf46c96..0028d145cc 100644 --- a/develop/schemadoc/Protocol/ColumnOptionOptionsOverview.md +++ b/develop/schemadoc/Protocol/ColumnOptionOptionsOverview.md @@ -358,7 +358,7 @@ See also the [rowTextColor](xref:Protocol.Params.Param.Measurement.Discreets.Dis Specify this option if you want the column to be saved. > [!NOTE] -> From DataMiner 9.5.5 (RN 16743) onwards, all parameters used to create the display key are saved by default (except for volatile tables). +> From DataMiner 9.5.5 (RN 16743) onwards, all parameters used to create the display key are saved by default (except for [volatile tables](xref:AdvancedDataMinerDataPersistencePersistingTables#volatile-tables)). For guidelines on how to avoid storing unnecessary data, see [Saving parameters](xref:Saving_parameters). ## separator diff --git a/develop/schemadoc/Protocol/Protocol.Params.Param-save.md b/develop/schemadoc/Protocol/Protocol.Params.Param-save.md index d495c85077..0e9b7d9f14 100644 --- a/develop/schemadoc/Protocol/Protocol.Params.Param-save.md +++ b/develop/schemadoc/Protocol/Protocol.Params.Param-save.md @@ -6,6 +6,9 @@ uid: Protocol.Params.Param-save Specifies whether the parameter has to be saved each time its value changes. +> [!IMPORTANT] +> To make sure your on-premises databases remain in good shape and do not get cluttered with unnecessary data, or to ensure a cost-efficient solution in case you make use of Storage as a Service, it is important to avoid storing unnecessary data. As a consequence, parameters must only be saved when this is really necessary. See [saving parameters](xref:Saving_parameters). + ## Content Type [EnumTrueFalse](xref:Protocol-EnumTrueFalse) diff --git a/develop/toc.yml b/develop/toc.yml index 42fc6defe2..f691250776 100644 --- a/develop/toc.yml +++ b/develop/toc.yml @@ -624,6 +624,279 @@ items: topicUid: Connector_help_template - name: Questions & Answers topicUid: QuestionsAndAnswers + - name: Best practices + topicUid: CodingGuidelines + items: + - name: General + items: + - name: Protocol name + topicUid: Protocol_name + - name: Formatting + items: + - name: Indentation + topicUid: Indentation + - name: Alignment and wording + topicUid: Alignment_and_wording + - name: Names + items: + - name: Unique and meaningful names + topicUid: Unique_and_meaningful_names + - name: Parameter names + topicUid: Parameter_names + - name: QAction and Action names + topicUid: QAction_and_Action_names + - name: Trigger names + topicUid: Trigger_names + - name: Group names + topicUid: Group_names + - name: DMS element names + topicUid: DMS_element_names + - name: ID values + items: + - name: ID range + topicUid: ID_range + - name: ID gaps + topicUid: ID_gaps + - name: ID ordering + topicUid: ID_ordering + - name: ID grouping + topicUid: ID_grouping + - name: C# code conventions + items: + - name: General + topicUid: General_COD + - name: Capitalization style + topicUid: Capitalization_style + - name: Namespaces + topicUid: Namespaces + - name: Classes, structs and interfaces + topicUid: Classes_structs_and_interfaces + - name: Enumerations + topicUid: Enumerations + - name: Methods + topicUid: Methods + - name: Properties + topicUid: Properties + - name: Fields + topicUid: Fields + - name: Parameters + topicUid: Parameters1 + - name: Local variables + topicUid: Local_variables + - name: Ordering + topicUid: Ordering + - name: Layout + topicUid: Layout + - name: Spacing + topicUid: Spacing + - name: Readability + topicUid: Readability + - name: Maintainability + topicUid: Maintainability + - name: XML documentation + topicUid: XML_documentation + - name: Commenting + topicUid: Commenting + - name: Administrative metadata + items: + - name: Comment metadata + topicUid: Comment_metadata + - name: Protocol metadata + topicUid: Protocol_metadata + - name: User interface + items: + - name: Element wizard + items: + - name: Default settings + topicUid: Default_settings + - name: Connection names + topicUid: Connection_names + - name: Protocol pages + items: + - name: Page layout + topicUid: Page_layout + - name: Look and feel + topicUid: Look_and_feel + - name: General page + topicUid: General_page + - name: Core functionality pages + topicUid: Core_functionality_pages + - name: Web interface page + topicUid: Web_interface_page + - name: Displayed text + topicUid: Displayed_text + items: + - name: Title case + topicUid: Title_case + - name: Brand and product names + topicUid: Brand_and_product_names + - name: Acronyms and initialisms + topicUid: Acronyms_and_initialisms + - name: Parameters + items: + - name: Parameter descriptions and values + topicUid: Parameter_descriptions_and_values + - name: Unit of measure + topicUid: Unit_of_measure + - name: Value range + topicUid: Value_range + - name: Date and time values + topicUid: Date_and_time_values + - name: Exceptional states + topicUid: Exceptional_states + - name: Tooltips + topicUid: Tooltips + - name: Octet values + topicUid: Octet_values + - name: Error Counter values + topicUid: Error_Counter_values + - name: Tables + items: + - name: Column names + topicUid: Column_names + - name: Column descriptions + topicUid: Column_descriptions + - name: Column header options + topicUid: Column_header_options + - name: Buttons + topicUid: Buttons + - name: Toggle buttons + topicUid: Toggle_buttons + - name: Page buttons + items: + - name: Page button dimensions + topicUid: Page_button_dimensions + - name: Page button labels + topicUid: Page_button_labels + - name: Page button content + topicUid: Page_button_content + - name: Progress bars + topicUid: Progress_bars + - name: Monitoring + items: + - name: Trending + topicUid: Trending1 + - name: Alarming + topicUid: Alarming1 + - name: Protocol + items: + - name: API + items: + - name: Device API + topicUid: Device_API + - name: DataMiner API + topicUid: DataMiner_API + - name: Communication + topicUid: Communication1 + - name: Logic + items: + - name: Operation duration + topicUid: Operation_duration + - name: Operation execution delay + topicUid: Operation_execution_delay + - name: Value update verification + topicUid: Value_update_verification + - name: Protocol threads + topicUid: Protocol_threads + - name: Timers + items: + - name: Number of timers + topicUid: Number_of_timers + - name: Default timer speeds + topicUid: Default_timer_speeds + - name: Timer speed restrictions + topicUid: Timer_speed_restrictions + - name: Starting/stopping timers + topicUid: Starting_stopping_timers + - name: Timer content + topicUid: Timer_content + - name: DVE + items: + - name: DVE names + topicUid: DVE_names + - name: DVE export rules + topicUid: DVE_export_rules + - name: DVE child element deletion + topicUid: DVE_child_element_deletion + - name: Tables + items: + - name: Primary keys + topicUid: Primary_keys1 + - name: Display keys + topicUid: Display_keys1 + - name: Data handling + topicUid: Data_handling + - name: Integrity constraints + topicUid: Integrity_constraints + - name: Preserve state option + topicUid: Preserve_state_option + - name: Clear Table Data on Polling Disable + topicUid: Clear_Table_Data_on_Polling_Disable + - name: Parameters + items: + - name: Saving parameters + topicUid: Saving_parameters + - name: Loading parameters in SLElement + topicUid: Loading_parameters_in_SLElement + - name: QActions + items: + - name: Functionality + topicUid: Functionality + - name: Maintainability + topicUid: Maintainability1 + - name: Robustness + topicUid: Robustness + - name: Conditional execution + topicUid: Conditional_execution + - name: Localization + topicUid: Localization + - name: Inter-process communication + topicUid: Inter-process_communication + - name: Exception handling + topicUid: Exception_handling + - name: Logging + topicUid: Logging + - name: Multi-threading + topicUid: Multi-threading1 + - name: Thread.Sleep + topicUid: Thread_Sleep + - name: StyleCop + topicUid: StyleCop + - name: .NET Recommendations + topicUid: _NET_Recommendations + items: + - name: Microbenchmarking + topicUid: Microbenchmarking + - name: String vs. StringBuilder + topicUid: String_vs_StringBuilder + - name: Conditional statements + topicUid: Conditional_statements + - name: Loops + topicUid: Loops + - name: Collections + topicUid: Collections + - name: Linq + topicUid: Linq + - name: Validation + items: + - name: General + topicUid: General1 + - name: Spell checker + topicUid: Spell_checker + - name: DIS validator + topicUid: DIS_validator + - name: Stream Viewer + topicUid: Stream_Viewer + - name: Log files + topicUid: Log_files + - name: Alarm Console + topicUid: Alarm_Console + - name: Points of attention + items: + - name: Skyline Driver Passport Platform + topicUid: Skyline_Driver_Passport_Platform + - name: Minimum DMA version + topicUid: Minimum_DMA_version - name: How-tos items: - name: How to aggregate alarm severities @@ -746,6 +1019,8 @@ items: topicUid: AutomationActionUi - name: UIBlockType overview topicUid: UIBlockTypesOverview + - name: Best practices + topicUid: Automation_best_practices - name: How-tos items: - name: How to make your Automation scripts debug ready @@ -4920,302 +5195,6 @@ items: topicUid: DMAElement1 - name: ParamValue topicUid: ParamValue -- name: DataMiner Protocol Development Guidelines - topicUid: CodingGuidelines - items: - - name: General - topicUid: CODGeneral - items: - - name: Protocol name - topicUid: Protocol_name - - name: Formatting - topicUid: Formatting - items: - - name: Indentation - topicUid: Indentation - - name: Alignment and wording - topicUid: Alignment_and_wording - - name: Names - topicUid: Names - items: - - name: Unique and meaningful names - topicUid: Unique_and_meaningful_names - - name: Parameter names - topicUid: Parameter_names - - name: QAction and Action names - topicUid: QAction_and_Action_names - - name: Trigger names - topicUid: Trigger_names - - name: Group names - topicUid: Group_names - - name: DMS element names - topicUid: DMS_element_names - - name: ID values - topicUid: ID_values - items: - - name: ID range - topicUid: ID_range - - name: ID gaps - topicUid: ID_gaps - - name: ID ordering - topicUid: ID_ordering - - name: ID grouping - topicUid: ID_grouping - - name: C# code conventions - topicUid: C_code_conventions - items: - - name: General - topicUid: General_COD - - name: Capitalization style - topicUid: Capitalization_style - - name: Namespaces - topicUid: Namespaces - - name: Classes, structs and interfaces - topicUid: Classes_structs_and_interfaces - - name: Enumerations - topicUid: Enumerations - - name: Methods - topicUid: Methods - - name: Properties - topicUid: Properties - - name: Fields - topicUid: Fields - - name: Parameters - topicUid: Parameters1 - - name: Local variables - topicUid: Local_variables - - name: Ordering - topicUid: Ordering - - name: Layout - topicUid: Layout - - name: Spacing - topicUid: Spacing - - name: Readability - topicUid: Readability - - name: Maintainability - topicUid: Maintainability - - name: XML documentation - topicUid: XML_documentation - - name: Commenting - topicUid: Commenting - - name: Administrative metadata - topicUid: CODAdminMetadata - items: - - name: Comment metadata - topicUid: Comment_metadata - - name: Protocol metadata - topicUid: Protocol_metadata - - name: User interface - topicUid: CODUserInterface - items: - - name: Element wizard - topicUid: Element_wizard - items: - - name: Default settings - topicUid: Default_settings - - name: Connection names - topicUid: Connection_names - - name: Protocol pages - topicUid: Protocol_pages - items: - - name: Page layout - topicUid: Page_layout - - name: Look and feel - topicUid: Look_and_feel - - name: General page - topicUid: General_page - - name: Core functionality pages - topicUid: Core_functionality_pages - - name: Web interface page - topicUid: Web_interface_page - - name: Displayed text - topicUid: Displayed_text - items: - - name: Title case - topicUid: Title_case - - name: Brand and product names - topicUid: Brand_and_product_names - - name: Acronyms and initialisms - topicUid: Acronyms_and_initialisms - - name: Parameters - topicUid: Parameters2 - items: - - name: Parameter descriptions and values - topicUid: Parameter_descriptions_and_values - - name: Unit of measure - topicUid: Unit_of_measure - - name: Value range - topicUid: Value_range - - name: Date and time values - topicUid: Date_and_time_values - - name: Exceptional states - topicUid: Exceptional_states - - name: Tooltips - topicUid: Tooltips - - name: Octet values - topicUid: Octet_values - - name: Error Counter values - topicUid: Error_Counter_values - - name: Tables - topicUid: Tables_COD - items: - - name: Column names - topicUid: Column_names - - name: Column descriptions - topicUid: Column_descriptions - - name: Column header options - topicUid: Column_header_options - - name: Buttons - topicUid: Buttons - - name: Toggle buttons - topicUid: Toggle_buttons - - name: Page buttons - topicUid: Page_buttons - items: - - name: Page button dimensions - topicUid: Page_button_dimensions - - name: Page button labels - topicUid: Page_button_labels - - name: Page button content - topicUid: Page_button_content - - name: Progress bars - topicUid: Progress_bars - - name: Monitoring - topicUid: CODMonitoring - items: - - name: Trending - topicUid: Trending1 - - name: Alarming - topicUid: Alarming1 - - name: Protocol - topicUid: CODProtocol - items: - - name: API - topicUid: API - items: - - name: Device API - topicUid: Device_API - - name: DataMiner API - topicUid: DataMiner_API - - name: Communication - topicUid: Communication1 - - name: Logic - topicUid: Logic1 - items: - - name: Operation duration - topicUid: Operation_duration - - name: Operation execution delay - topicUid: Operation_execution_delay - - name: Value update verification - topicUid: Value_update_verification - - name: Protocol threads - topicUid: Protocol_threads - - name: Timers - topicUid: Timers1 - items: - - name: Number of timers - topicUid: Number_of_timers - - name: Default timer speeds - topicUid: Default_timer_speeds - - name: Timer speed restrictions - topicUid: Timer_speed_restrictions - - name: Starting/stopping timers - topicUid: Starting_stopping_timers - - name: Timer content - topicUid: Timer_content - - name: DVE - topicUid: DVE - items: - - name: DVE names - topicUid: DVE_names - - name: DVE export rules - topicUid: DVE_export_rules - - name: DVE child element deletion - topicUid: DVE_child_element_deletion - - name: Tables - topicUid: Tables1 - items: - - name: Primary keys - topicUid: Primary_keys1 - - name: Display keys - topicUid: Display_keys1 - - name: Data handling - topicUid: Data_handling - - name: Integrity constraints - topicUid: Integrity_constraints - - name: Preserve state option - topicUid: Preserve_state_option - - name: Clear Table Data on Polling Disable - topicUid: Clear_Table_Data_on_Polling_Disable - - name: Parameters - topicUid: Parameters3 - items: - - name: Saving parameters - topicUid: Saving_parameters - - name: Loading parameters in SLElement - topicUid: Loading_parameters_in_SLElement - - name: QActions - topicUid: QActions - items: - - name: Functionality - topicUid: Functionality - - name: Maintainability - topicUid: Maintainability1 - - name: Robustness - topicUid: Robustness - - name: Conditional execution - topicUid: Conditional_execution - - name: Localization - topicUid: Localization - - name: Inter-process communication - topicUid: Inter-process_communication - - name: Exception handling - topicUid: Exception_handling - - name: Logging - topicUid: Logging - - name: Multi-threading - topicUid: Multi-threading1 - - name: Thread.Sleep - topicUid: Thread_Sleep - - name: StyleCop - topicUid: StyleCop - - name: .NET Recommendations - topicUid: _NET_Recommendations - items: - - name: Microbenchmarking - topicUid: Microbenchmarking - - name: String vs. StringBuilder - topicUid: String_vs_StringBuilder - - name: Conditional statements - topicUid: Conditional_statements - - name: Loops - topicUid: Loops - - name: Collections - topicUid: Collections - - name: Linq - topicUid: Linq - - name: Validation - topicUid: CODValidation - items: - - name: General - topicUid: General1 - - name: Spell checker - topicUid: Spell_checker - - name: DIS validator - topicUid: DIS_validator - - name: Stream Viewer - topicUid: Stream_Viewer - - name: Log files - topicUid: Log_files - - name: Alarm Console - topicUid: Alarm_Console - - name: Points of attention - topicUid: CODAttention - items: - - name: Skyline Driver Passport Platform - topicUid: Skyline_Driver_Passport_Platform - - name: Minimum DMA version - topicUid: Minimum_DMA_version - name: CI/CD topicUid: CICD items: diff --git a/user-guide/Advanced_Functionality/Databases/STaaS/STaaS.md b/user-guide/Advanced_Functionality/Databases/STaaS/STaaS.md index 69daeea3c1..abd1a34a55 100644 --- a/user-guide/Advanced_Functionality/Databases/STaaS/STaaS.md +++ b/user-guide/Advanced_Functionality/Databases/STaaS/STaaS.md @@ -185,6 +185,9 @@ If you have any questions regarding this cost estimation, please contact [!IMPORTANT] > Cost estimations can currently only be performed for the West Europe and UK South regions. +> [!TIP] +> To optimize the cost efficiency of a STaaS solution, adhere to the best practices to prevent storing unnecessary data [with Automation scripts](xref:Automation_best_practices) or [with connectors](xref:Saving_parameters). + ## Migrating existing data to STaaS Before migrating your data over to STaaS, make sure you are aware of the [limitations](#limitations) for migration. Then follow the procedure below: diff --git a/user-guide/Advanced_Modules/Automation_module/Automation_script_actions/Information.md b/user-guide/Advanced_Modules/Automation_module/Automation_script_actions/Information.md index 2edb9692cc..bbfaa00de8 100644 --- a/user-guide/Advanced_Modules/Automation_module/Automation_script_actions/Information.md +++ b/user-guide/Advanced_Modules/Automation_module/Automation_script_actions/Information.md @@ -8,5 +8,8 @@ Use this action to generate an information event in the Alarm Console: - In the *Message* field, enter the message that should appear in the Alarm Console. +> [!TIP] +> See also: [Best practices for Automation script development](xref:Automation_best_practices) + > [!NOTE] > It is also possible to add this action within a C# block in a script. For more information, see [GenerateInformation](xref:Skyline.DataMiner.Automation.Engine.GenerateInformation(System.String)).