diff --git a/src/EFCore.PG/Design/Internal/NpgsqlDesignTimeServices.cs b/src/EFCore.PG/Design/Internal/NpgsqlDesignTimeServices.cs index 66f2d7d9ce374aa484ce05e2646c077552873149..9c13160aa4d90adaa491b9d242f22671b47c454e 100644 --- a/src/EFCore.PG/Design/Internal/NpgsqlDesignTimeServices.cs +++ b/src/EFCore.PG/Design/Internal/NpgsqlDesignTimeServices.cs @@ -8,6 +8,10 @@ namespace Npgsql.EntityFrameworkCore.PostgreSQL.Design.Internal { + /// + /// Enables configuring Npgsql-specific design-time services. + /// Tools will automatically discover implementations of this interface that are in the startup assembly. + /// [UsedImplicitly] public class NpgsqlDesignTimeServices : IDesignTimeServices { diff --git a/src/EFCore.PG/Diagnostics/NpgsqlEventId.cs b/src/EFCore.PG/Diagnostics/NpgsqlEventId.cs index cd0e8cb7ce4cf9b5dbc8e587d9c0ae010053c294..a2a3e81367a8c9c157ae6d7f5e74b0f896226cc2 100644 --- a/src/EFCore.PG/Diagnostics/NpgsqlEventId.cs +++ b/src/EFCore.PG/Diagnostics/NpgsqlEventId.cs @@ -6,24 +6,23 @@ namespace Npgsql.EntityFrameworkCore.PostgreSQL.Diagnostics { /// - /// - /// Event IDs for PostgreSQL/Npgsql events that correspond to messages logged to an - /// and events sent to a . - /// - /// - /// These IDs are also used with to configure the - /// behavior of warnings. - /// + /// + /// Event IDs for PostgreSQL/Npgsql events that correspond to messages logged to an + /// and events sent to a . + /// + /// + /// These IDs are also used with to configure the + /// behavior of warnings. + /// /// public static class NpgsqlEventId { // Warning: These values must not change between releases. // Only add new values to the end of sections, never in the middle. - // Try to use naming and be consistent with existing names. - private enum Id + // Try to use {Noun}{Verb} naming and be consistent with existing names. + enum Id { // Model validation events - // Scaffolding events ColumnFound = CoreEventId.ProviderDesignBaseId, //ColumnNotNamedWarning, @@ -57,123 +56,156 @@ private enum Id UnsupportedConstraintIndexSkippedWarning } - private static readonly string _validationPrefix = DbLoggerCategory.Model.Validation.Name + "."; - private static EventId MakeValidationId(Id id) => new EventId((int)id, _validationPrefix + id); - -// /// -// /// -// /// No explicit type for a decimal column. -// /// -// /// -// /// This event is in the category. -// /// -// /// -// /// This event uses the payload when used with a . -// /// -// /// -// public static readonly EventId DecimalTypeDefaultWarning = MakeValidationId(Id.DecimalTypeDefaultWarning); - - /// - /// - /// A byte property is set up to use a SQL Server identity column. - /// - /// - /// This event is in the category. - /// - /// - /// This event uses the payload when used with a . - /// - /// - //public static readonly EventId ByteIdentityColumnWarning = MakeValidationId(Id.ByteIdentityColumnWarning); - - private static readonly string _scaffoldingPrefix = DbLoggerCategory.Scaffolding.Name + "."; - private static EventId MakeScaffoldingId(Id id) => new EventId((int)id, _scaffoldingPrefix + id); + static readonly string ScaffoldingPrefix = DbLoggerCategory.Scaffolding.Name + "."; + static EventId MakeScaffoldingId(Id id) => new EventId((int)id, ScaffoldingPrefix + id); /// + /// /// A column was found. + /// + /// /// This event is in the category. + /// /// public static readonly EventId ColumnFound = MakeScaffoldingId(Id.ColumnFound); /// + /// /// The database is missing a schema. + /// + /// /// This event is in the category. + /// /// public static readonly EventId MissingSchemaWarning = MakeScaffoldingId(Id.MissingSchemaWarning); /// + /// /// The database is missing a table. + /// + /// /// This event is in the category. + /// /// public static readonly EventId MissingTableWarning = MakeScaffoldingId(Id.MissingTableWarning); /// + /// /// A foreign key references a missing table at the principal end. + /// + /// /// This event is in the category. + /// /// public static readonly EventId ForeignKeyReferencesMissingPrincipalTableWarning = MakeScaffoldingId(Id.ForeignKeyReferencesMissingPrincipalTableWarning); /// + /// /// A table was found. + /// + /// /// This event is in the category. + /// /// public static readonly EventId TableFound = MakeScaffoldingId(Id.TableFound); /// + /// /// A sequence was found. + /// + /// /// This event is in the category. + /// /// public static readonly EventId SequenceFound = MakeScaffoldingId(Id.SequenceFound); /// - /// Primary key was found. + /// + /// A primary key was found. + /// + /// /// This event is in the category. + /// /// public static readonly EventId PrimaryKeyFound = MakeScaffoldingId(Id.PrimaryKeyFound); /// - /// An unique constraint was found. + /// + /// A unique constraint was found. + /// + /// /// This event is in the category. + /// /// public static readonly EventId UniqueConstraintFound = MakeScaffoldingId(Id.UniqueConstraintFound); /// + /// /// An index was found. + /// + /// /// This event is in the category. + /// /// public static readonly EventId IndexFound = MakeScaffoldingId(Id.IndexFound); /// + /// /// A foreign key was found. + /// + /// /// This event is in the category. + /// /// public static readonly EventId ForeignKeyFound = MakeScaffoldingId(Id.ForeignKeyFound); /// + /// /// A principal column referenced by a foreign key was not found. + /// + /// /// This event is in the category. + /// /// public static readonly EventId ForeignKeyPrincipalColumnMissingWarning = MakeScaffoldingId(Id.ForeignKeyPrincipalColumnMissingWarning); /// + /// /// Enum column cannot be scaffolded, define a CLR enum type and add the property manually. + /// + /// /// This event is in the category. + /// /// public static readonly EventId EnumColumnSkippedWarning = MakeScaffoldingId(Id.EnumColumnSkippedWarning); /// - /// Expression index cannot be scaffolded, expression indices aren't supported and must be added via raw SQL in migrations. - /// This event is in the category. + /// + /// Expression index cannot be scaffolded, expression indices aren't supported and must be added via raw SQL in migrations. + /// + /// + /// This event is in the category. + /// /// public static readonly EventId ExpressionIndexSkippedWarning = MakeScaffoldingId(Id.ExpressionIndexSkippedWarning); /// - /// Index '{name}' on table {tableName} cannot be scaffolded because it includes a column that cannot be scaffolded (e.g. enum). + /// + /// Index '{name}' on table {tableName} cannot be scaffolded because it includes a column that cannot be scaffolded (e.g. enum). + /// + /// + /// This event is in the category. + /// /// public static readonly EventId UnsupportedColumnIndexSkippedWarning = MakeScaffoldingId(Id.UnsupportedColumnIndexSkippedWarning); - + /// - /// Constraint '{name}' on table {tableName} cannot be scaffolded because it includes a column that cannot be scaffolded (e.g. enum). + /// + /// Constraint '{name}' on table {tableName} cannot be scaffolded because it includes a column that cannot be scaffolded (e.g. enum). + /// + /// + /// This event is in the category. + /// /// public static readonly EventId UnsupportedColumnConstraintSkippedWarning = MakeScaffoldingId(Id.UnsupportedConstraintIndexSkippedWarning); } diff --git a/src/EFCore.PG/Storage/Internal/Mapping/NpgsqlArrayTypeMapping.cs b/src/EFCore.PG/Storage/Internal/Mapping/NpgsqlArrayTypeMapping.cs index adffdc361985940458b0dd104785acb43e8390cc..cf3b53289ac8fdbca09adc9f782e2096362c489f 100644 --- a/src/EFCore.PG/Storage/Internal/Mapping/NpgsqlArrayTypeMapping.cs +++ b/src/EFCore.PG/Storage/Internal/Mapping/NpgsqlArrayTypeMapping.cs @@ -11,20 +11,29 @@ namespace Npgsql.EntityFrameworkCore.PostgreSQL.Storage.Internal.Mapping /// /// /// Note that mapping PostgreSQL arrays to .NET List{T} is also supported via . + /// See: https://www.postgresql.org/docs/current/static/arrays.html /// public class NpgsqlArrayTypeMapping : RelationalTypeMapping { + // ReSharper disable once MemberCanBePrivate.Global + /// + /// The relational type mapping used to initialize the array mapping. + /// public RelationalTypeMapping ElementMapping { get; } /// /// Creates the default array mapping (i.e. for the single-dimensional CLR array type) /// + /// The database type to map. + /// The element type mapping. public NpgsqlArrayTypeMapping(string storeType, RelationalTypeMapping elementMapping) : this(storeType, elementMapping, elementMapping.ClrType.MakeArrayType()) {} /// /// Creates the default array mapping (i.e. for the single-dimensional CLR array type) /// + /// The element type mapping. + /// The array type to map. public NpgsqlArrayTypeMapping(RelationalTypeMapping elementMapping, Type arrayType) : this(elementMapping.StoreType + "[]", elementMapping, arrayType) {} diff --git a/src/EFCore.PG/Storage/Internal/Mapping/NpgsqlBitTypeMapping.cs b/src/EFCore.PG/Storage/Internal/Mapping/NpgsqlBitTypeMapping.cs index 1d765f3291c585b6794c5dcf46344c1c11fd003e..f7092ba363dc6858170f7660a06a25a986aadb72 100644 --- a/src/EFCore.PG/Storage/Internal/Mapping/NpgsqlBitTypeMapping.cs +++ b/src/EFCore.PG/Storage/Internal/Mapping/NpgsqlBitTypeMapping.cs @@ -6,8 +6,17 @@ namespace Npgsql.EntityFrameworkCore.PostgreSQL.Storage.Internal.Mapping { + /// + /// The type mapping for the PostgreSQL bit string type. + /// + /// + /// See: https://www.postgresql.org/docs/current/static/datatype-bit.html + /// public class NpgsqlBitTypeMapping : NpgsqlTypeMapping { + /// + /// Constructs an instance of the class. + /// public NpgsqlBitTypeMapping() : base("bit", typeof(BitArray), NpgsqlDbType.Bit) {} protected NpgsqlBitTypeMapping(RelationalTypeMappingParameters parameters) diff --git a/src/EFCore.PG/Storage/Internal/Mapping/NpgsqlHstoreTypeMapping.cs b/src/EFCore.PG/Storage/Internal/Mapping/NpgsqlHstoreTypeMapping.cs index 774377218dfce23c3f161ef90627982edf573414..198546aa4a98ba8901094c812b3a4e9d52c4c3e7 100644 --- a/src/EFCore.PG/Storage/Internal/Mapping/NpgsqlHstoreTypeMapping.cs +++ b/src/EFCore.PG/Storage/Internal/Mapping/NpgsqlHstoreTypeMapping.cs @@ -6,10 +6,19 @@ namespace Npgsql.EntityFrameworkCore.PostgreSQL.Storage.Internal.Mapping { + /// + /// The type mapping for the PostgreSQL hstore type. + /// + /// + /// See: https://www.postgresql.org/docs/current/static/hstore.html + /// public class NpgsqlHstoreTypeMapping : NpgsqlTypeMapping { static readonly HstoreComparer ComparerInstance = new HstoreComparer(); + /// + /// Constructs an instance of the class. + /// public NpgsqlHstoreTypeMapping() : base( new RelationalTypeMappingParameters( diff --git a/src/EFCore.PG/Storage/Internal/Mapping/NpgsqlListTypeMapping.cs b/src/EFCore.PG/Storage/Internal/Mapping/NpgsqlListTypeMapping.cs index ce87ca92f29762ab26cc059cfb21dc32206a533c..abb86f9ee5a31ae075b88ee1fdccb4238b44deb6 100644 --- a/src/EFCore.PG/Storage/Internal/Mapping/NpgsqlListTypeMapping.cs +++ b/src/EFCore.PG/Storage/Internal/Mapping/NpgsqlListTypeMapping.cs @@ -11,16 +11,23 @@ namespace Npgsql.EntityFrameworkCore.PostgreSQL.Storage.Internal.Mapping /// /// Maps PostgreSQL arrays to . /// + /// + /// Note that mapping PostgreSQL arrays to .NET arrays is also supported via . + /// See: https://www.postgresql.org/docs/current/static/arrays.html + /// public class NpgsqlListTypeMapping : RelationalTypeMapping { + // ReSharper disable once MemberCanBePrivate.Global /// - /// The CLR type of the list items. + /// The relational type mapping used to initialize the list mapping. /// public RelationalTypeMapping ElementMapping { get; } /// /// Creates the default list mapping. /// + /// The element type mapping. + /// The database type to map. public NpgsqlListTypeMapping(RelationalTypeMapping elementMapping, Type listType) : this(elementMapping.StoreType + "[]", elementMapping, listType) {} @@ -65,7 +72,7 @@ protected override string GenerateNonNullSqlLiteral(object value) #region Value Comparison - // Note that the value comparison code is largely duplicated from NpgsqlAraryTypeMapping. + // Note that the value comparison code is largely duplicated from NpgsqlArrayTypeMapping. // However, a limitation in EF Core prevents us from merging the code together, see // https://github.com/aspnet/EntityFrameworkCore/issues/11077 diff --git a/src/EFCore.PG/Storage/Internal/Mapping/NpgsqlNetworkTypeMappings.cs b/src/EFCore.PG/Storage/Internal/Mapping/NpgsqlNetworkTypeMappings.cs index 1820c0ee478fda4ad17e52f357aaf15801628969..1d102a4dc0203045b5cbb4a5ace03b7eb11b9c35 100644 --- a/src/EFCore.PG/Storage/Internal/Mapping/NpgsqlNetworkTypeMappings.cs +++ b/src/EFCore.PG/Storage/Internal/Mapping/NpgsqlNetworkTypeMappings.cs @@ -6,8 +6,17 @@ namespace Npgsql.EntityFrameworkCore.PostgreSQL.Storage.Internal.Mapping { + /// + /// The type mapping for the PostgreSQL macaddr type. + /// + /// + /// See: https://www.postgresql.org/docs/current/static/datatype-net-types.html#DATATYPE-MACADDR + /// public class NpgsqlMacaddrTypeMapping : NpgsqlTypeMapping { + /// + /// Constructs an instance of the class. + /// public NpgsqlMacaddrTypeMapping() : base("macaddr", typeof(PhysicalAddress), NpgsqlDbType.MacAddr) {} protected NpgsqlMacaddrTypeMapping(RelationalTypeMappingParameters parameters) @@ -25,8 +34,17 @@ public override Expression GenerateCodeLiteral(object value) Expression.Constant(((PhysicalAddress)value).ToString())); } + /// + /// The type mapping for the PostgreSQL macaddr8 type. + /// + /// + /// See: https://www.postgresql.org/docs/current/static/datatype-net-types.html#DATATYPE-MACADDR8 + /// public class NpgsqlMacaddr8TypeMapping : NpgsqlTypeMapping { + /// + /// Constructs an instance of the class. + /// public NpgsqlMacaddr8TypeMapping() : base("macaddr8", typeof(PhysicalAddress), NpgsqlDbType.MacAddr8) {} protected NpgsqlMacaddr8TypeMapping(RelationalTypeMappingParameters parameters) @@ -44,8 +62,17 @@ public override Expression GenerateCodeLiteral(object value) Expression.Constant(((PhysicalAddress)value).ToString())); } + /// + /// The type mapping for the PostgreSQL inet type. + /// + /// + /// See: https://www.postgresql.org/docs/current/static/datatype-net-types.html#DATATYPE-INET + /// public class NpgsqlInetTypeMapping : NpgsqlTypeMapping { + /// + /// Constructs an instance of the class. + /// public NpgsqlInetTypeMapping() : base("inet", typeof(IPAddress), NpgsqlDbType.Inet) {} protected NpgsqlInetTypeMapping(RelationalTypeMappingParameters parameters) @@ -63,8 +90,17 @@ public override Expression GenerateCodeLiteral(object value) Expression.Constant(((IPAddress)value).ToString())); } + /// + /// The type mapping for the PostgreSQL cidr type. + /// + /// + /// See: https://www.postgresql.org/docs/current/static/datatype-net-types.html#DATATYPE-CIDR + /// public class NpgsqlCidrTypeMapping : NpgsqlTypeMapping { + /// + /// Constructs an instance of the class. + /// public NpgsqlCidrTypeMapping() : base("cidr", typeof((IPAddress, int)), NpgsqlDbType.Cidr) {} protected NpgsqlCidrTypeMapping(RelationalTypeMappingParameters parameters) diff --git a/src/EFCore.PG/Storage/Internal/Mapping/NpgsqlRangeTypeMapping.cs b/src/EFCore.PG/Storage/Internal/Mapping/NpgsqlRangeTypeMapping.cs index 229b537eed06f168cc0e563ffebf41abc90678e3..fc1fdf48abc6cb2104f1efae1666ff8db0577506 100644 --- a/src/EFCore.PG/Storage/Internal/Mapping/NpgsqlRangeTypeMapping.cs +++ b/src/EFCore.PG/Storage/Internal/Mapping/NpgsqlRangeTypeMapping.cs @@ -8,12 +8,29 @@ namespace Npgsql.EntityFrameworkCore.PostgreSQL.Storage.Internal.Mapping { + /// + /// The type mapping for the PostgreSQL range types. + /// + /// + /// See: https://www.postgresql.org/docs/current/static/rangetypes.html + /// public class NpgsqlRangeTypeMapping : NpgsqlTypeMapping { [NotNull] readonly ISqlGenerationHelper _sqlGenerationHelper; + // ReSharper disable once MemberCanBePrivate.Global + /// + /// The relational type mapping used to initialize the bound mapping. + /// public RelationalTypeMapping SubtypeMapping { get; } + /// + /// Constructs an instance of the class. + /// + /// The database type to map + /// The CLR type to map. + /// The type mapping for the range subtype. + /// The SQL generation helper to delimit the store name. public NpgsqlRangeTypeMapping( [NotNull] string storeType, [NotNull] Type clrType, @@ -21,6 +38,14 @@ public class NpgsqlRangeTypeMapping : NpgsqlTypeMapping [NotNull] ISqlGenerationHelper sqlGenerationHelper) : this(storeType, null, clrType, subtypeMapping, sqlGenerationHelper) {} + /// + /// Constructs an instance of the class. + /// + /// The database type to map + /// The schema of the type. + /// The CLR type to map. + /// The type mapping for the range subtype. + /// The SQL generation helper to delimit the store name. public NpgsqlRangeTypeMapping( [NotNull] string storeType, [CanBeNull] string storeTypeSchema, diff --git a/src/EFCore.PG/Storage/Internal/Mapping/NpgsqlTypeMapping.cs b/src/EFCore.PG/Storage/Internal/Mapping/NpgsqlTypeMapping.cs index eec0453f26a8802928eae64bd17303a27d271c0c..fc1c2032e5dcd93b9ec2e719ffb1c9ed156ae242 100644 --- a/src/EFCore.PG/Storage/Internal/Mapping/NpgsqlTypeMapping.cs +++ b/src/EFCore.PG/Storage/Internal/Mapping/NpgsqlTypeMapping.cs @@ -6,11 +6,23 @@ namespace Npgsql.EntityFrameworkCore.PostgreSQL.Storage.Internal.Mapping { + /// + /// The base class for mapping Npgsql-specific types. + /// public abstract class NpgsqlTypeMapping : RelationalTypeMapping { + /// + /// The database type used by Npgsql. + /// public NpgsqlDbType NpgsqlDbType { get; } // ReSharper disable once PublicConstructorInAbstractClass + /// + /// Constructs an instance of the class. + /// + /// The database type to map. + /// The CLR type to map. + /// The database type used by Npgsql. public NpgsqlTypeMapping( [NotNull] string storeType, [NotNull] Type clrType, @@ -18,6 +30,11 @@ public abstract class NpgsqlTypeMapping : RelationalTypeMapping : base(storeType, clrType) => NpgsqlDbType = npgsqlDbType; + /// + /// Constructs an instance of the class. + /// + /// The parameters for this mapping. + /// The database type of the range subtype. protected NpgsqlTypeMapping(RelationalTypeMappingParameters parameters, NpgsqlDbType npgsqlDbType) : base(parameters) => NpgsqlDbType = npgsqlDbType; diff --git a/src/EFCore.PG/Update/Internal/NpgsqlModificationCommandBatch.cs b/src/EFCore.PG/Update/Internal/NpgsqlModificationCommandBatch.cs index a10aafba6f5188c28e5d847ed576bd8fe5872636..4f4d09c5e8d2174eda94f34a3751532025360868 100644 --- a/src/EFCore.PG/Update/Internal/NpgsqlModificationCommandBatch.cs +++ b/src/EFCore.PG/Update/Internal/NpgsqlModificationCommandBatch.cs @@ -10,6 +10,9 @@ namespace Npgsql.EntityFrameworkCore.PostgreSQL.Update.Internal { + /// + /// The Npgsql-specific implementation for . + /// /// /// The usual ModificationCommandBatch implementation is , /// which selects the number of rows modified via a SQL query. @@ -28,6 +31,14 @@ public class NpgsqlModificationCommandBatch : ReaderModificationCommandBatch readonly int _maxBatchSize; long _parameterCount; + /// + /// Constructs an instance of the class. + /// + /// The builder to build commands. + /// A helper for SQL generation. + /// A SQL generator for insert, update, and delete commands. + /// A factory for creating factories. + /// The maximum count of commands to batch. public NpgsqlModificationCommandBatch( [NotNull] IRelationalCommandBuilderFactory commandBuilderFactory, [NotNull] ISqlGenerationHelper sqlGenerationHelper,