From cdb347449584bd36525de7f79224f57b854aec8c Mon Sep 17 00:00:00 2001 From: Robert Wagner Date: Wed, 5 Nov 2025 15:43:15 +1000 Subject: [PATCH] Add XML documentation for all public members --- src/dbup-oracle/OracleCommandReader.cs | 7 +++- src/dbup-oracle/OracleCommandSplitter.cs | 12 ++++++- src/dbup-oracle/OracleConnectionManager.cs | 6 +++- .../OracleCustomDelimiterCommandReader.cs | 7 +++- src/dbup-oracle/OracleExtensions.cs | 7 +++- src/dbup-oracle/OracleObjectParser.cs | 8 ++++- src/dbup-oracle/OraclePreprocessor.cs | 6 +++- src/dbup-oracle/OracleScriptExecutor.cs | 7 +++- src/dbup-oracle/OracleTableJournal.cs | 33 ++++++++++++++++++- src/dbup-oracle/dbup-oracle.csproj | 3 +- 10 files changed, 86 insertions(+), 10 deletions(-) diff --git a/src/dbup-oracle/OracleCommandReader.cs b/src/dbup-oracle/OracleCommandReader.cs index 41e2750..2c7e93e 100644 --- a/src/dbup-oracle/OracleCommandReader.cs +++ b/src/dbup-oracle/OracleCommandReader.cs @@ -1,9 +1,12 @@ -using System; +using System; using System.Text; using DbUp.Support; namespace DbUp.Oracle { + /// + /// Reads Oracle commands from an underlying text stream. Supports DELIMITER statements. + /// [Obsolete] public class OracleCommandReader : SqlCommandReader { @@ -19,6 +22,7 @@ public class OracleCommandReader : SqlCommandReader /// /// Hook to support custom statements /// + /// protected override bool IsCustomStatement => TryPeek(DelimiterKeyword.Length, out var statement) && string.Equals(DelimiterKeyword, statement, StringComparison.OrdinalIgnoreCase) && string.IsNullOrEmpty(GetCurrentCommandTextFromBuffer()); @@ -26,6 +30,7 @@ public class OracleCommandReader : SqlCommandReader /// /// Read a custom statement /// + /// protected override void ReadCustomStatement() { // Move past Delimiter keyword diff --git a/src/dbup-oracle/OracleCommandSplitter.cs b/src/dbup-oracle/OracleCommandSplitter.cs index 0541939..96bd1d4 100644 --- a/src/dbup-oracle/OracleCommandSplitter.cs +++ b/src/dbup-oracle/OracleCommandSplitter.cs @@ -1,19 +1,29 @@ -using System; +using System; using System.Collections.Generic; using DbUp.Support; namespace DbUp.Oracle { + /// + /// Splits Oracle SQL scripts into individual commands using configurable delimiters. + /// public class OracleCommandSplitter { private readonly Func commandReaderFactory; + /// + /// Initializes a new instance of the class using the default semicolon delimiter. + /// [Obsolete] public OracleCommandSplitter() { this.commandReaderFactory = scriptContents => new OracleCommandReader(scriptContents); } + /// + /// Initializes a new instance of the class using a custom delimiter. + /// + /// The delimiter character to use for splitting commands. public OracleCommandSplitter(char delimiter) { this.commandReaderFactory = scriptContents => new OracleCustomDelimiterCommandReader(scriptContents, delimiter); diff --git a/src/dbup-oracle/OracleConnectionManager.cs b/src/dbup-oracle/OracleConnectionManager.cs index 5d482d4..fbb8e33 100644 --- a/src/dbup-oracle/OracleConnectionManager.cs +++ b/src/dbup-oracle/OracleConnectionManager.cs @@ -1,10 +1,13 @@ -using System; +using System; using System.Collections.Generic; using DbUp.Engine.Transactions; using Oracle.ManagedDataAccess.Client; namespace DbUp.Oracle { + /// + /// Manages Oracle database connections. + /// public class OracleConnectionManager : DatabaseConnectionManager { private readonly OracleCommandSplitter commandSplitter; @@ -31,6 +34,7 @@ public OracleConnectionManager(string connectionString, OracleCommandSplitter co this.commandSplitter = commandSplitter; } + /// public override IEnumerable SplitScriptIntoCommands(string scriptContents) { var scriptStatements = commandSplitter.SplitScriptIntoCommands(scriptContents); diff --git a/src/dbup-oracle/OracleCustomDelimiterCommandReader.cs b/src/dbup-oracle/OracleCustomDelimiterCommandReader.cs index cfc1d33..48061bb 100644 --- a/src/dbup-oracle/OracleCustomDelimiterCommandReader.cs +++ b/src/dbup-oracle/OracleCustomDelimiterCommandReader.cs @@ -1,9 +1,12 @@ -using System; +using System; using System.Text; using DbUp.Support; namespace DbUp.Oracle { + /// + /// Reads Oracle commands from an underlying text stream using a custom delimiter. Supports DELIMITER statements. + /// public class OracleCustomDelimiterCommandReader : SqlCommandReader { const string DelimiterKeyword = "DELIMITER"; @@ -18,6 +21,7 @@ public OracleCustomDelimiterCommandReader(string sqlText, char delimiter) : base /// /// Hook to support custom statements /// + /// protected override bool IsCustomStatement => TryPeek(DelimiterKeyword.Length - 1, out var statement) && string.Equals(DelimiterKeyword, CurrentChar + statement, StringComparison.OrdinalIgnoreCase) && @@ -26,6 +30,7 @@ protected override bool IsCustomStatement /// /// Read a custom statement /// + /// protected override void ReadCustomStatement() { // Move past Delimiter keyword diff --git a/src/dbup-oracle/OracleExtensions.cs b/src/dbup-oracle/OracleExtensions.cs index 75a752f..f181690 100644 --- a/src/dbup-oracle/OracleExtensions.cs +++ b/src/dbup-oracle/OracleExtensions.cs @@ -1,4 +1,4 @@ -using System; +using System; using System.Linq; using DbUp.Builder; using DbUp.Engine.Transactions; @@ -6,6 +6,9 @@ namespace DbUp.Oracle { #pragma warning disable IDE0060 // Remove unused parameter - The "SupportedDatabases" parameter is never used. + /// + /// Configuration extension methods for Oracle. + /// public static class OracleExtensions { /// @@ -81,6 +84,7 @@ public static UpgradeEngineBuilder OracleDatabase(this SupportedDatabases suppor /// /// Fluent helper type. /// The connection string. + /// Which Oracle schema to check for changes. /// Character to use as the delimiter between statements. /// /// A builder for a database upgrader designed for Oracle databases. @@ -111,6 +115,7 @@ public static UpgradeEngineBuilder OracleDatabase(this SupportedDatabases suppor /// Fluent helper type. /// Oracle database connection string. /// Which Oracle schema to check for changes + /// Character to use as the delimiter between statements. /// /// A builder for a database upgrader designed for Oracle databases. /// diff --git a/src/dbup-oracle/OracleObjectParser.cs b/src/dbup-oracle/OracleObjectParser.cs index b122844..3f25f91 100644 --- a/src/dbup-oracle/OracleObjectParser.cs +++ b/src/dbup-oracle/OracleObjectParser.cs @@ -1,9 +1,15 @@ -using DbUp.Support; +using DbUp.Support; namespace DbUp.Oracle { + /// + /// Parses Sql Objects and performs quoting functions. + /// public class OracleObjectParser : SqlObjectParser { + /// + /// Initializes a new instance of the class. + /// public OracleObjectParser() : base("\"", "\"") { } diff --git a/src/dbup-oracle/OraclePreprocessor.cs b/src/dbup-oracle/OraclePreprocessor.cs index f224e35..8d46458 100644 --- a/src/dbup-oracle/OraclePreprocessor.cs +++ b/src/dbup-oracle/OraclePreprocessor.cs @@ -1,9 +1,13 @@ -using DbUp.Engine; +using DbUp.Engine; namespace DbUp.Oracle { + /// + /// This preprocessor makes adjustments to your sql to make it compatible with Oracle. + /// public class OraclePreprocessor : IScriptPreprocessor { + /// public string Process(string contents) => contents; } } diff --git a/src/dbup-oracle/OracleScriptExecutor.cs b/src/dbup-oracle/OracleScriptExecutor.cs index f8442c2..cce95d3 100644 --- a/src/dbup-oracle/OracleScriptExecutor.cs +++ b/src/dbup-oracle/OracleScriptExecutor.cs @@ -1,4 +1,4 @@ -using System; +using System; using System.Collections.Generic; using DbUp.Engine; using DbUp.Engine.Output; @@ -8,6 +8,9 @@ namespace DbUp.Oracle { + /// + /// An implementation of that executes against an Oracle database. + /// public class OracleScriptExecutor : ScriptExecutor { /// @@ -25,6 +28,7 @@ public OracleScriptExecutor(Func connectionManagerFactory, F { } + /// protected override string GetVerifySchemaSql(string schema) { throw new NotSupportedException(); @@ -39,6 +43,7 @@ public override void Execute(SqlScript script) Execute(script, null); } + /// protected override void ExecuteCommandsWithinExceptionHandler(int index, SqlScript script, Action executeCommand) { try diff --git a/src/dbup-oracle/OracleTableJournal.cs b/src/dbup-oracle/OracleTableJournal.cs index e2d6625..3e22569 100644 --- a/src/dbup-oracle/OracleTableJournal.cs +++ b/src/dbup-oracle/OracleTableJournal.cs @@ -1,12 +1,17 @@ -using System; +using System; using System.Data; using System.Globalization; +using DbUp.Engine; using DbUp.Engine.Output; using DbUp.Engine.Transactions; using DbUp.Support; namespace DbUp.Oracle { + /// + /// An implementation of the interface which tracks version numbers for an + /// Oracle database using a table called SchemaVersions. + /// public class OracleTableJournal : TableJournal { bool journalExists; @@ -22,8 +27,12 @@ public OracleTableJournal(Func connectionManager, Func + /// English culture info used for formatting. + /// public static CultureInfo English = new CultureInfo("en-US", false); + /// protected override string CreateSchemaTableSql(string quotedPrimaryKeyName) { var fqSchemaTableName = UnquotedSchemaTableName; @@ -37,12 +46,20 @@ scriptname VARCHAR2(255) NOT NULL, )"; } + /// + /// Creates the SQL for the sequence used by the schema table. + /// + /// The SQL statement to create the sequence. protected string CreateSchemaTableSequenceSql() { var fqSchemaTableName = UnquotedSchemaTableName; return $@" CREATE SEQUENCE {fqSchemaTableName}_sequence"; } + /// + /// Creates the SQL for the trigger used by the schema table. + /// + /// The SQL statement to create the trigger. protected string CreateSchemaTableTriggerSql() { var fqSchemaTableName = UnquotedSchemaTableName; @@ -57,24 +74,32 @@ FOR EACH ROW "; } + /// protected override string GetInsertJournalEntrySql(string scriptName, string applied) { var unquotedSchemaTableName = UnquotedSchemaTableName.ToUpper(English); return $"insert into {unquotedSchemaTableName} (ScriptName, Applied) values (:" + scriptName.Replace("@", "") + ",:" + applied.Replace("@", "") + ")"; } + /// protected override string GetJournalEntriesSql() { var unquotedSchemaTableName = UnquotedSchemaTableName.ToUpper(English); return $"select scriptname from {unquotedSchemaTableName} order by scriptname"; } + /// protected override string DoesTableExistSql() { var unquotedSchemaTableName = UnquotedSchemaTableName.ToUpper(English); return $"select 1 from user_tables where table_name = '{unquotedSchemaTableName}'"; } + /// + /// Gets the command to create the sequence for the schema table. + /// + /// Factory to create database commands. + /// A command to create the sequence. protected IDbCommand GetCreateTableSequence(Func dbCommandFactory) { var command = dbCommandFactory(); @@ -83,6 +108,11 @@ protected IDbCommand GetCreateTableSequence(Func dbCommandFactory) return command; } + /// + /// Gets the command to create the trigger for the schema table. + /// + /// Factory to create database commands. + /// A command to create the trigger. protected IDbCommand GetCreateTableTrigger(Func dbCommandFactory) { var command = dbCommandFactory(); @@ -91,6 +121,7 @@ protected IDbCommand GetCreateTableTrigger(Func dbCommandFactory) return command; } + /// public override void EnsureTableExistsAndIsLatestVersion(Func dbCommandFactory) { if (!journalExists && !DoesTableExist(dbCommandFactory)) diff --git a/src/dbup-oracle/dbup-oracle.csproj b/src/dbup-oracle/dbup-oracle.csproj index b2afd84..2bd08ad 100644 --- a/src/dbup-oracle/dbup-oracle.csproj +++ b/src/dbup-oracle/dbup-oracle.csproj @@ -1,4 +1,4 @@ - + DbUp makes it easy to deploy and upgrade SQL Server databases. This package adds Oracle support. @@ -14,6 +14,7 @@ true https://github.com/DbUp/dbup-oracle.git dbup-icon.png + true