diff --git a/src/EFCore.PG/Infrastructure/Internal/INpgsqlOptions.cs b/src/EFCore.PG/Infrastructure/Internal/INpgsqlOptions.cs index 1d2299ead..a213f0c9c 100644 --- a/src/EFCore.PG/Infrastructure/Internal/INpgsqlOptions.cs +++ b/src/EFCore.PG/Infrastructure/Internal/INpgsqlOptions.cs @@ -1,15 +1,50 @@ -using System.Collections.Generic; +#region License + +// The PostgreSQL License +// +// Copyright (C) 2016 The Npgsql Development Team +// +// Permission to use, copy, modify, and distribute this software and its +// documentation for any purpose, without fee, and without a written +// agreement is hereby granted, provided that the above copyright notice +// and this paragraph and the following two paragraphs appear in all copies. +// +// IN NO EVENT SHALL THE NPGSQL DEVELOPMENT TEAM BE LIABLE TO ANY PARTY +// FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, +// INCLUDING LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS +// DOCUMENTATION, EVEN IF THE NPGSQL DEVELOPMENT TEAM HAS BEEN ADVISED OF +// THE POSSIBILITY OF SUCH DAMAGE. +// +// THE NPGSQL DEVELOPMENT TEAM SPECIFICALLY DISCLAIMS ANY WARRANTIES, +// INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY +// AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS +// ON AN "AS IS" BASIS, AND THE NPGSQL DEVELOPMENT TEAM HAS NO OBLIGATIONS +// TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS. + +#endregion + +using System; +using System.Collections.Generic; +using JetBrains.Annotations; using Microsoft.EntityFrameworkCore.Infrastructure; namespace Npgsql.EntityFrameworkCore.PostgreSQL.Infrastructure.Internal { + /// + /// Represents options for Npgsql that can only be set at the singleton level. + /// public interface INpgsqlOptions : ISingletonOptions { /// - /// Reflects the option set by . + /// True if reverse null ordering is enabled; otherwise, false. /// bool ReverseNullOrderingEnabled { get; } + /// + /// The collection of database plugins. + /// + [NotNull] + [ItemNotNull] IReadOnlyList Plugins { get; } } } diff --git a/src/EFCore.PG/Infrastructure/Internal/NpgsqlOptionsExtension.cs b/src/EFCore.PG/Infrastructure/Internal/NpgsqlOptionsExtension.cs index 52ce59361..bf8150f2a 100644 --- a/src/EFCore.PG/Infrastructure/Internal/NpgsqlOptionsExtension.cs +++ b/src/EFCore.PG/Infrastructure/Internal/NpgsqlOptionsExtension.cs @@ -1,4 +1,5 @@ #region License + // The PostgreSQL License // // Copyright (C) 2016 The Npgsql Development Team @@ -19,6 +20,7 @@ // AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS // ON AN "AS IS" BASIS, AND THE NPGSQL DEVELOPMENT TEAM HAS NO OBLIGATIONS // TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS. + #endregion using System.Collections.Generic; @@ -28,36 +30,76 @@ using Microsoft.Extensions.DependencyInjection; using Npgsql.EntityFrameworkCore.PostgreSQL.Utilities; -// ReSharper disable once CheckNamespace namespace Npgsql.EntityFrameworkCore.PostgreSQL.Infrastructure.Internal { + /// + /// Represents options managed by the Npgsql. + /// public class NpgsqlOptionsExtension : RelationalOptionsExtension { + /// + /// The collection of database plugins. + /// + [NotNull] readonly List _plugins; + + /// + /// The name of the database for administrative operations. + /// + [CanBeNull] public string AdminDatabase { get; private set; } - public bool? ReverseNullOrdering { get; private set; } - public ProvideClientCertificatesCallback ProvideClientCertificatesCallback { get; private set; } - public RemoteCertificateValidationCallback RemoteCertificateValidationCallback { get; private set; } + /// + /// The collection of database plugins. + /// + [NotNull] + [ItemNotNull] public IReadOnlyList Plugins => _plugins; - readonly List _plugins = new List(); + /// + /// The specified . + /// + [CanBeNull] + public ProvideClientCertificatesCallback ProvideClientCertificatesCallback { get; private set; } - public NpgsqlOptionsExtension() {} + /// + /// The specified . + /// + [CanBeNull] + public RemoteCertificateValidationCallback RemoteCertificateValidationCallback { get; private set; } - // NB: When adding new options, make sure to update the copy ctor below. + /// + /// True if reverse null ordering is enabled; otherwise, false. + /// + public bool ReverseNullOrdering { get; private set; } - public NpgsqlOptionsExtension([NotNull] NpgsqlOptionsExtension copyFrom) - : base(copyFrom) + /// + /// Initializes an instance of with the default settings. + /// + public NpgsqlOptionsExtension() + { + _plugins = new List(); + ReverseNullOrdering = false; + } + + // NB: When adding new options, make sure to update the copy ctor below. + /// + /// Initializes an instance of by copying the specified instance. + /// + /// The instance to copy. + public NpgsqlOptionsExtension([NotNull] NpgsqlOptionsExtension copyFrom) : base(copyFrom) { AdminDatabase = copyFrom.AdminDatabase; - ReverseNullOrdering = copyFrom.ReverseNullOrdering; + _plugins = new List(copyFrom._plugins); ProvideClientCertificatesCallback = copyFrom.ProvideClientCertificatesCallback; RemoteCertificateValidationCallback = copyFrom.RemoteCertificateValidationCallback; - _plugins.AddRange(copyFrom._plugins); + ReverseNullOrdering = copyFrom.ReverseNullOrdering; } + /// + [NotNull] protected override RelationalOptionsExtension Clone() => new NpgsqlOptionsExtension(this); + /// public override bool ApplyServices(IServiceCollection services) { Check.NotNull(services, nameof(services)); @@ -67,8 +109,15 @@ public override bool ApplyServices(IServiceCollection services) return true; } - public virtual NpgsqlOptionsExtension WithPlugin(NpgsqlEntityFrameworkPlugin plugin) + /// + /// Returns a copy of the current instance configured to use the specified . + /// + /// The plugin to configure. + [NotNull] + public virtual NpgsqlOptionsExtension WithPlugin([NotNull] NpgsqlEntityFrameworkPlugin plugin) { + Check.NotNull(plugin, nameof(plugin)); + var clone = (NpgsqlOptionsExtension)Clone(); clone._plugins.Add(plugin); @@ -76,7 +125,12 @@ public virtual NpgsqlOptionsExtension WithPlugin(NpgsqlEntityFrameworkPlugin plu return clone; } - public virtual NpgsqlOptionsExtension WithAdminDatabase(string adminDatabase) + /// + /// Returns a copy of the current instance configured to use the specified administrative database. + /// + /// The name of the database for administrative operations. + [NotNull] + public virtual NpgsqlOptionsExtension WithAdminDatabase([CanBeNull] string adminDatabase) { var clone = (NpgsqlOptionsExtension)Clone(); @@ -85,6 +139,11 @@ public virtual NpgsqlOptionsExtension WithAdminDatabase(string adminDatabase) return clone; } + /// + /// Returns a copy of the current instance configured with the specified value.. + /// + /// True to enable reverse null ordering; otherwise, false. + [NotNull] internal virtual NpgsqlOptionsExtension WithReverseNullOrdering(bool reverseNullOrdering) { var clone = (NpgsqlOptionsExtension)Clone(); @@ -96,7 +155,12 @@ internal virtual NpgsqlOptionsExtension WithReverseNullOrdering(bool reverseNull #region Authentication - public virtual NpgsqlOptionsExtension WithProvideClientCertificatesCallback(ProvideClientCertificatesCallback callback) + /// + /// Returns a copy of the current instance with the specified . + /// + /// The specified callback. + [NotNull] + public virtual NpgsqlOptionsExtension WithProvideClientCertificatesCallback([CanBeNull] ProvideClientCertificatesCallback callback) { var clone = (NpgsqlOptionsExtension)Clone(); @@ -105,7 +169,12 @@ public virtual NpgsqlOptionsExtension WithProvideClientCertificatesCallback(Prov return clone; } - public virtual NpgsqlOptionsExtension WithRemoteCertificateValidationCallback(RemoteCertificateValidationCallback callback) + /// + /// Returns a copy of the current instance with the specified . + /// + /// The specified callback. + [NotNull] + public virtual NpgsqlOptionsExtension WithRemoteCertificateValidationCallback([CanBeNull] RemoteCertificateValidationCallback callback) { var clone = (NpgsqlOptionsExtension)Clone(); diff --git a/src/EFCore.PG/Infrastructure/NpgsqlDbContextOptionsBuilder.cs b/src/EFCore.PG/Infrastructure/NpgsqlDbContextOptionsBuilder.cs index 66e8497da..85999fcc4 100644 --- a/src/EFCore.PG/Infrastructure/NpgsqlDbContextOptionsBuilder.cs +++ b/src/EFCore.PG/Infrastructure/NpgsqlDbContextOptionsBuilder.cs @@ -1,4 +1,5 @@ #region License + // The PostgreSQL License // // Copyright (C) 2016 The Npgsql Development Team @@ -19,6 +20,7 @@ // AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS // ON AN "AS IS" BASIS, AND THE NPGSQL DEVELOPMENT TEAM HAS NO OBLIGATIONS // TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS. + #endregion using System; @@ -30,41 +32,58 @@ using Microsoft.EntityFrameworkCore.Storage; using Npgsql.EntityFrameworkCore.PostgreSQL.Infrastructure.Internal; -// ReSharper disable once CheckNamespace namespace Npgsql.EntityFrameworkCore.PostgreSQL.Infrastructure { + /// + /// Allows for options specific to PostgreSQL to be configured for a . + /// public class NpgsqlDbContextOptionsBuilder : RelationalDbContextOptionsBuilder { + /// + /// Initializes a new instance of the class. + /// + /// The core options builder. public NpgsqlDbContextOptionsBuilder([NotNull] DbContextOptionsBuilder optionsBuilder) - : base(optionsBuilder) - { - } + : base(optionsBuilder) {} - public virtual void UsePlugin(NpgsqlEntityFrameworkPlugin plugin) + /// + /// Configures the to use the specified . + /// + /// The plugin to configure. + public virtual void UsePlugin([NotNull] NpgsqlEntityFrameworkPlugin plugin) => WithOption(e => e.WithPlugin(plugin)); /// /// Connect to this database for administrative operations (creating/dropping databases). - /// Defaults to 'postgres'. /// - public virtual void UseAdminDatabase(string dbName) => WithOption(e => e.WithAdminDatabase(dbName)); + /// The name of the database for administrative operations. + public virtual void UseAdminDatabase([CanBeNull] string dbName) + => WithOption(e => e.WithAdminDatabase(dbName)); /// /// Appends NULLS FIRST to all ORDER BY clauses. This is important for the tests which were written /// for SQL Server. Note that to fully implement null-first ordering indexes also need to be generated /// accordingly, and since this isn't done this feature isn't publicly exposed. /// - /// + /// True to enable reverse null ordering; otherwise, false. internal virtual void ReverseNullOrdering(bool reverseNullOrdering = true) => WithOption(e => e.WithReverseNullOrdering(reverseNullOrdering)); #region Authentication - public virtual void ProvideClientCertificatesCallback(ProvideClientCertificatesCallback callback) + /// + /// Configures the to use the specified . + /// + /// The callback to use. + public virtual void ProvideClientCertificatesCallback([CanBeNull] ProvideClientCertificatesCallback callback) => WithOption(e => e.WithProvideClientCertificatesCallback(callback)); - public virtual void RemoteCertificateValidationCallback(RemoteCertificateValidationCallback callback) + /// + /// Configures the to use the specified . + /// + /// The callback to use. + public virtual void RemoteCertificateValidationCallback([CanBeNull] RemoteCertificateValidationCallback callback) => WithOption(e => e.WithRemoteCertificateValidationCallback(callback)); #endregion Authentication @@ -72,23 +91,36 @@ public virtual void RemoteCertificateValidationCallback(RemoteCertificateValidat #region Retrying execution strategy /// - /// Configures the context to use the default retrying . + /// Configures the context to use the default retrying . /// + /// + /// An instance of configured to use + /// the default retrying . + /// + [NotNull] public virtual NpgsqlDbContextOptionsBuilder EnableRetryOnFailure() => ExecutionStrategy(c => new NpgsqlRetryingExecutionStrategy(c)); /// - /// Configures the context to use the default retrying . + /// Configures the context to use the default retrying . /// + /// + /// An instance of with the specified parameters. + /// + [NotNull] public virtual NpgsqlDbContextOptionsBuilder EnableRetryOnFailure(int maxRetryCount) => ExecutionStrategy(c => new NpgsqlRetryingExecutionStrategy(c, maxRetryCount)); /// - /// Configures the context to use the default retrying . + /// Configures the context to use the default retrying . /// - /// The maximum number of retry attempts. - /// The maximum delay between retries. - /// Additional error codes that should be considered transient. + /// The maximum number of retry attempts. + /// The maximum delay between retries. + /// Additional error codes that should be considered transient. + /// + /// An instance of with the specified parameters. + /// + [NotNull] public virtual NpgsqlDbContextOptionsBuilder EnableRetryOnFailure( int maxRetryCount, TimeSpan maxRetryDelay, diff --git a/src/EFCore.PG/Internal/NpgsqlOptions.cs b/src/EFCore.PG/Internal/NpgsqlOptions.cs index b036dc572..d433abebe 100644 --- a/src/EFCore.PG/Internal/NpgsqlOptions.cs +++ b/src/EFCore.PG/Internal/NpgsqlOptions.cs @@ -1,4 +1,29 @@ -using System; +#region License + +// The PostgreSQL License +// +// Copyright (C) 2016 The Npgsql Development Team +// +// Permission to use, copy, modify, and distribute this software and its +// documentation for any purpose, without fee, and without a written +// agreement is hereby granted, provided that the above copyright notice +// and this paragraph and the following two paragraphs appear in all copies. +// +// IN NO EVENT SHALL THE NPGSQL DEVELOPMENT TEAM BE LIABLE TO ANY PARTY +// FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, +// INCLUDING LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS +// DOCUMENTATION, EVEN IF THE NPGSQL DEVELOPMENT TEAM HAS BEEN ADVISED OF +// THE POSSIBILITY OF SUCH DAMAGE. +// +// THE NPGSQL DEVELOPMENT TEAM SPECIFICALLY DISCLAIMS ANY WARRANTIES, +// INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY +// AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS +// ON AN "AS IS" BASIS, AND THE NPGSQL DEVELOPMENT TEAM HAS NO OBLIGATIONS +// TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS. + +#endregion + +using System; using System.Collections.Generic; using Microsoft.EntityFrameworkCore; using Microsoft.EntityFrameworkCore.Infrastructure; @@ -8,21 +33,30 @@ namespace Npgsql.EntityFrameworkCore.PostgreSQL.Internal { + /// public class NpgsqlOptions : INpgsqlOptions { + /// + public virtual bool ReverseNullOrderingEnabled { get; private set; } + + /// + public virtual IReadOnlyList Plugins { get; private set; } + + /// public void Initialize(IDbContextOptions options) { var npgsqlOptions = options.FindExtension() ?? new NpgsqlOptionsExtension(); - ReverseNullOrderingEnabled = npgsqlOptions.ReverseNullOrdering ?? false; + ReverseNullOrderingEnabled = npgsqlOptions.ReverseNullOrdering; Plugins = npgsqlOptions.Plugins; } + /// public void Validate(IDbContextOptions options) { var npgsqlOptions = options.FindExtension() ?? new NpgsqlOptionsExtension(); - if (ReverseNullOrderingEnabled != (npgsqlOptions.ReverseNullOrdering ?? false)) + if (ReverseNullOrderingEnabled != npgsqlOptions.ReverseNullOrdering) { throw new InvalidOperationException( CoreStrings.SingletonOptionChanged( @@ -30,9 +64,5 @@ public void Validate(IDbContextOptions options) nameof(DbContextOptionsBuilder.UseInternalServiceProvider))); } } - - public virtual bool ReverseNullOrderingEnabled { get; private set; } - - public virtual IReadOnlyList Plugins { get; private set; } } }