Refactor DTOs for improved structure and documentation

Transitioned from records to classes for flexibility, added XML documentation for clarity, and updated property definitions to use standard getters and setters. Introduced the `required` keyword for essential properties, removed unnecessary constructors, and enhanced property descriptions for better readability. Additionally, overridden `GetHashCode` in `ReceiverReadDto` for proper collection behavior.

EnvelopeGenerator.Application/DTOs/ConfigDto.cs

@@ -3,19 +3,45 @@ using Microsoft.AspNetCore.Mvc;
 using System.ComponentModel.DataAnnotations.Schema;
 using System.Text.Json.Serialization;
 
-namespace EnvelopeGenerator.Application.DTOs
+namespace EnvelopeGenerator.Application.DTOs;
+
+/// <summary>
+/// Data Transfer Object representing configuration settings.
+/// </summary>
+[ApiExplorerSettings(IgnoreApi = true)]
+public class ConfigDto : IUnique<int>
 {
-    [ApiExplorerSettings(IgnoreApi = true)]
+    /// <summary>
-    public record ConfigDto(
+    /// Gets or sets the path to the document.
-        string DocumentPath,
+    /// </summary>
-        int SendingProfile,
+    public string DocumentPath { get; set; }
-        string SignatureHost,
+
-        string ExternalProgramName,
+    /// <summary>
-        string ExportPath) : IUnique<int>
+    /// Gets or sets the sending profile identifier.
-    {
+    /// </summary>
-        [NotMapped]
+    public int SendingProfile { get; set; }
-        [JsonIgnore]
+
-        [Obsolete("Configuration does not have an ID; it represents a single table in the database.")]
+    /// <summary>
-        public int Id => throw new InvalidOperationException("This configuration does not support an ID as it represents a single row in the database.");
+    /// Gets or sets the signature host URL or name.
-    };
+    /// </summary>
+    public string SignatureHost { get; set; }
+
+    /// <summary>
+    /// Gets or sets the name of the external program.
+    /// </summary>
+    public string ExternalProgramName { get; set; }
+
+    /// <summary>
+    /// Gets or sets the path where exports will be saved.
+    /// </summary>
+    public string ExportPath { get; set; }
+
+    /// <summary>
+    /// Gets the ID of the configuration.
+    /// This DTO represents a single row in the database and does not support an ID.
+    /// </summary>
+    [NotMapped]
+    [JsonIgnore]
+    [Obsolete("Configuration does not have an ID; it represents a single table in the database.")]
+    public int Id => throw new InvalidOperationException("This configuration does not support an ID as it represents a single row in the database.");
 }

EnvelopeGenerator.Application/DTOs/DocumentReceiverElementDto.cs

@@ -1,26 +1,96 @@
 using DigitalData.Core.Abstractions;
 using Microsoft.AspNetCore.Mvc;
 
-namespace EnvelopeGenerator.Application.DTOs
+namespace EnvelopeGenerator.Application.DTOs;
+
+/// <summary>
+/// Data Transfer Object representing a positioned element assigned to a document receiver.
+/// </summary>
+[ApiExplorerSettings(IgnoreApi = true)]
+public class DocumentReceiverElementDto : IUnique<int>
 {
-    [ApiExplorerSettings(IgnoreApi = true)]
+    /// <summary>
-    public record DocumentReceiverElementDto(
+    /// Gets or sets the unique identifier of the element.
-        int Id,
+    /// </summary>
-        int DocumentId,
+    public int Id { get; set; }
-        int ReceiverId,
+
-        int ElementType,
+    /// <summary>
-        double X,
+    /// Gets or sets the identifier of the associated document.
-        double Y,
+    /// </summary>
-        double Width,
+    public int DocumentId { get; set; }
-        double Height,
+
-        int Page,
+    /// <summary>
-        bool Required,
+    /// Gets or sets the identifier of the receiver.
-        string? Tooltip,
+    /// </summary>
-        bool ReadOnly,
+    public int ReceiverId { get; set; }
-        int AnnotationIndex,
+
-        DateTime AddedWhen,
+    /// <summary>
-        DateTime? ChangedWhen,
+    /// Gets or sets the type of the element.
-        double Top,
+    /// </summary>
-        double Left
+    public int ElementType { get; set; }
-        ): IUnique<int>;
+
+    /// <summary>
+    /// Gets or sets the X coordinate of the element.
+    /// </summary>
+    public double X { get; set; }
+
+    /// <summary>
+    /// Gets or sets the Y coordinate of the element.
+    /// </summary>
+    public double Y { get; set; }
+
+    /// <summary>
+    /// Gets or sets the width of the element.
+    /// </summary>
+    public double Width { get; set; }
+
+    /// <summary>
+    /// Gets or sets the height of the element.
+    /// </summary>
+    public double Height { get; set; }
+
+    /// <summary>
+    /// Gets or sets the page number where the element appears.
+    /// </summary>
+    public int Page { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the element is required.
+    /// </summary>
+    public bool Required { get; set; }
+
+    /// <summary>
+    /// Gets or sets the tooltip text for the element.
+    /// </summary>
+    public string? Tooltip { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the element is read-only.
+    /// </summary>
+    public bool ReadOnly { get; set; }
+
+    /// <summary>
+    /// Gets or sets the annotation index for ordering or reference.
+    /// </summary>
+    public int AnnotationIndex { get; set; }
+
+    /// <summary>
+    /// Gets or sets the timestamp when the element was added.
+    /// </summary>
+    public DateTime AddedWhen { get; set; }
+
+    /// <summary>
+    /// Gets or sets the timestamp when the element was last changed, if applicable.
+    /// </summary>
+    public DateTime? ChangedWhen { get; set; }
+
+    /// <summary>
+    /// Gets or sets the top position of the element (in layout terms).
+    /// </summary>
+    public double Top { get; set; }
+
+    /// <summary>
+    /// Gets or sets the left position of the element (in layout terms).
+    /// </summary>
+    public double Left { get; set; }
 }

EnvelopeGenerator.Application/DTOs/DocumentStatusDto.cs

@@ -1,18 +1,51 @@
 using DigitalData.Core.Abstractions;
 using Microsoft.AspNetCore.Mvc;
 
-namespace EnvelopeGenerator.Application.DTOs
+namespace EnvelopeGenerator.Application.DTOs;
+
+/// <summary>
+/// Data Transfer Object representing the status of a document for a specific receiver.
+/// </summary>
+[ApiExplorerSettings(IgnoreApi = true)]
+public class DocumentStatusDto : IUnique<int>
 {
-    [ApiExplorerSettings(IgnoreApi = true)]
+    /// <summary>
-    public record DocumentStatusDto(
+    /// Gets or sets the unique identifier of the document status entry.
-        int Id,
+    /// </summary>
-        int EnvelopeId,
+    public int Id { get; set; }
-        int ReceiverId,
+
-        int Status,
+    /// <summary>
-        DateTime? StatusChangedWhen,
+    /// Gets or sets the ID of the associated envelope.
-        DateTime AddedWhen,
+    /// </summary>
-        DateTime? ChangedWhen) : IUnique<int>
+    public int EnvelopeId { get; set; }
-    {
+
-        public string? Value { get; set; }
+    /// <summary>
-    };
+    /// Gets or sets the ID of the receiver associated with this status.
+    /// </summary>
+    public int ReceiverId { get; set; }
+
+    /// <summary>
+    /// Gets or sets the current status code.
+    /// </summary>
+    public int Status { get; set; }
+
+    /// <summary>
+    /// Gets or sets the timestamp when the status was changed.
+    /// </summary>
+    public DateTime? StatusChangedWhen { get; set; }
+
+    /// <summary>
+    /// Gets or sets the timestamp when this record was added.
+    /// </summary>
+    public DateTime AddedWhen { get; set; }
+
+    /// <summary>
+    /// Gets or sets the timestamp when this record was last changed.
+    /// </summary>
+    public DateTime? ChangedWhen { get; set; }
+
+    /// <summary>
+    /// Gets or sets the display value associated with the status.
+    /// </summary>
+    public string? Value { get; set; }
 }

EnvelopeGenerator.Application/DTOs/EnvelopeCertificateDto.cs

@@ -1,16 +1,51 @@
 using DigitalData.Core.Abstractions;
 using Microsoft.AspNetCore.Mvc;
 
-namespace EnvelopeGenerator.Application.DTOs
+namespace EnvelopeGenerator.Application.DTOs;
+
+/// <summary>
+/// Data Transfer Object representing certificate information for an envelope.
+/// </summary>
+[ApiExplorerSettings(IgnoreApi = true)]
+public class EnvelopeCertificateDto : IUnique<int>
 {
-    [ApiExplorerSettings(IgnoreApi = true)]
+    /// <summary>
-    public record EnvelopeCertificateDto(
+    /// Gets the unique identifier of the certificate.
-        int Id,
+    /// </summary>
-        int EnvelopeId,
+    public int Id { get; init; }
-        string EnvelopeUuid,
+
-        string EnvelopeSubject,
+    /// <summary>
-        int CreatorId,
+    /// Gets the envelope ID associated with the certificate.
-        string CreatorName,
+    /// </summary>
-        string CreatorEmail,
+    public int EnvelopeId { get; init; }
-        int EnvelopeStatus) : IUnique<int>;
+
+    /// <summary>
+    /// Gets the UUID of the envelope.
+    /// </summary>
+    public string EnvelopeUuid { get; init; }
+
+    /// <summary>
+    /// Gets the subject of the envelope.
+    /// </summary>
+    public string EnvelopeSubject { get; init; }
+
+    /// <summary>
+    /// Gets the ID of the creator of the envelope.
+    /// </summary>
+    public int CreatorId { get; init; }
+
+    /// <summary>
+    /// Gets the name of the creator.
+    /// </summary>
+    public string CreatorName { get; init; }
+
+    /// <summary>
+    /// Gets the email address of the creator.
+    /// </summary>
+    public string CreatorEmail { get; init; }
+
+    /// <summary>
+    /// Gets the current status of the envelope.
+    /// </summary>
+    public int EnvelopeStatus { get; init; }
 }

EnvelopeGenerator.Application/DTOs/EnvelopeDocumentDto.cs

@@ -1,15 +1,36 @@
 using DigitalData.Core.Abstractions;
 using Microsoft.AspNetCore.Mvc;
 
-namespace EnvelopeGenerator.Application.DTOs
+namespace EnvelopeGenerator.Application.DTOs;
+
+/// <summary>
+/// Data Transfer Object representing a document within an envelope, including optional binary data and form elements.
+/// </summary>
+[ApiExplorerSettings(IgnoreApi = true)]
+public class EnvelopeDocumentDto : IUnique<int>
 {
-    [ApiExplorerSettings(IgnoreApi = true)]
+    /// <summary>
-    public record EnvelopeDocumentDto
+    /// Gets or sets the unique identifier of the document.
-    (
+    /// </summary>
-        int Id,
+    public int Id { get; set; }
-        int EnvelopeId,
+
-        DateTime AddedWhen,
+    /// <summary>
-        byte[]? ByteData = null,
+    /// Gets or sets the envelope ID to which the document belongs.
-        IEnumerable<DocumentReceiverElementDto>? Elements = null
+    /// </summary>
-    ) : IUnique<int>;
+    public int EnvelopeId { get; set; }
-}
+
+    /// <summary>
+    /// Gets or sets the date and time when the document was added.
+    /// </summary>
+    public DateTime AddedWhen { get; set; }
+
+    /// <summary>
+    /// Gets or sets the binary data of the document, if available.
+    /// </summary>
+    public byte[]? ByteData { get; set; }
+
+    /// <summary>
+    /// Gets or sets the collection of elements associated with the document for receiver interactions, if any.
+    /// </summary>
+    public IEnumerable<DocumentReceiverElementDto>? Elements { get; set; }
+}

EnvelopeGenerator.Application/DTOs/EnvelopeDto.cs

@@ -4,53 +4,52 @@ using DigitalData.UserManager.Application.DTOs.User;
 using EnvelopeGenerator.Domain.Entities;
 using Microsoft.AspNetCore.Mvc;
 
-namespace EnvelopeGenerator.Application.DTOs
+namespace EnvelopeGenerator.Application.DTOs;
+
+[ApiExplorerSettings(IgnoreApi = true)]
+public record EnvelopeDto : IUnique<int>
 {
-    [ApiExplorerSettings(IgnoreApi = true)]
+	public int Id { get; set; }
-    public record EnvelopeDto() : IUnique<int>
-    {
-		public int Id { get; set; }
 
-		public int UserId { get; set; }
+	public int UserId { get; set; }
 
-		public int Status { get; set; }
+	public int Status { get; set; }
 
-		public string StatusName { get; set; }
+	public string StatusName { get; set; }
 
-        public string Uuid { get; set; }
+    public string Uuid { get; set; }
 
-		[TemplatePlaceholder("[MESSAGE]")]
+	[TemplatePlaceholder("[MESSAGE]")]
-		public string Message { get; set; }
+	public string Message { get; set; }
 
-		public DateTime AddedWhen { get; set; }
+	public DateTime AddedWhen { get; set; }
 
-		public DateTime? ChangedWhen { get; set; }
+	public DateTime? ChangedWhen { get; set; }
 
-		[TemplatePlaceholder("[DOCUMENT_TITLE]")]
+	[TemplatePlaceholder("[DOCUMENT_TITLE]")]
-		public string Title { get; set; }
+	public string Title { get; set; }
 
-		public int? ContractType { get; set; }
+	public int? ContractType { get; set; }
 
-		public string Language { get; set; }
+	public string Language { get; set; }
 
-		public int? EnvelopeTypeId { get; set; }
+	public int? EnvelopeTypeId { get; set; }
 
-		public int? CertificationType { get; set; }
+	public int? CertificationType { get; set; }
 
-		public bool? UseAccessCode { get; set; }
+	public bool? UseAccessCode { get; set; }
 
-        public bool TFAEnabled { get; init; }
+    public bool TFAEnabled { get; init; }
 
-		public UserReadDto? User { get; set; }
+	public UserReadDto? User { get; set; }
 
-		public EnvelopeType? EnvelopeType { get; set; }
+	public EnvelopeType? EnvelopeType { get; set; }
 
-		public string? EnvelopeTypeTitle { get; set; }
+	public string? EnvelopeTypeTitle { get; set; }
 
-		public bool IsAlreadySent { get; set; }
+	public bool IsAlreadySent { get; set; }
 
-        public byte[]? DocResult { get; init; }
+    public byte[]? DocResult { get; init; }
 
-        public IEnumerable<EnvelopeDocumentDto>? Documents { get; set; }
+    public IEnumerable<EnvelopeDocumentDto>? Documents { get; set; }
-	}
 }

EnvelopeGenerator.Application/DTOs/EnvelopeHistory/EnvelopeHistoryCreateDto.cs

@@ -1,12 +1,34 @@
 using Microsoft.AspNetCore.Mvc;
 
-namespace EnvelopeGenerator.Application.DTOs.EnvelopeHistory
+namespace EnvelopeGenerator.Application.DTOs.EnvelopeHistory;
+
+/// <summary>
+/// Data Transfer Object for creating a new envelope history record.
+/// </summary>
+public class EnvelopeHistoryCreateDto
 {
-    [ApiExplorerSettings(IgnoreApi = true)]
+    /// <summary>
-    public record EnvelopeHistoryCreateDto(
+    /// Gets or sets the identifier of the envelope.
-        int EnvelopeId,
+    /// </summary>
-        string UserReference,
+    public int EnvelopeId { get; set; }
-        int Status,
+
-        DateTime? ActionDate,
+    /// <summary>
-        string? Comment = null);
+    /// Gets or sets the user reference associated with the action.
+    /// </summary>
+    public required string UserReference { get; set; }
+
+    /// <summary>
+    /// Gets or sets the status of the envelope at the time of the action.
+    /// </summary>
+    public int Status { get; set; }
+
+    /// <summary>
+    /// Gets or sets the date and time when the action occurred.
+    /// </summary>
+    public DateTime? ActionDate { get; set; }
+
+    /// <summary>
+    /// Gets or sets an optional comment related to the action.
+    /// </summary>
+    public string? Comment { get; set; }
 }

EnvelopeGenerator.Application/DTOs/EnvelopeTypeDto.cs

@@ -1,23 +1,86 @@
 using DigitalData.Core.Abstractions;
 using Microsoft.AspNetCore.Mvc;
 
-namespace EnvelopeGenerator.Application.DTOs
+namespace EnvelopeGenerator.Application.DTOs;
+
+/// <summary>
+/// Data Transfer Object representing a type of envelope with its configuration settings.
+/// </summary>
+[ApiExplorerSettings(IgnoreApi = true)]
+public class EnvelopeTypeDto : IUnique<int>
 {
-    [ApiExplorerSettings(IgnoreApi = true)]
+    /// <summary>
-    public record EnvelopeTypeDto(
+    /// Gets or sets the unique identifier of the envelope type.
-        int Id,
+    /// </summary>
-        string Title,
+    public int Id { get; set; }
-        string Language,
+
-        int? ExpiresDays,
+    /// <summary>
-        int? CertificationType,
+    /// Gets or sets the title of the envelope type.
-        bool? UseAccessCode,
+    /// </summary>
-        int? FinalEmailToCreator,
+    public string Title { get; set; }
-        int? FinalEmailToReceivers,
+
-        DateTime AddedWhen,
+    /// <summary>
-        DateTime? ChangedWhen,
+    /// Gets or sets the language code used in this envelope type.
-        int? ExpiresWarningDays,
+    /// </summary>
-        bool? SendReminderEmails,
+    public string Language { get; set; }
-        int? FirstReminderDays,
+
-        int? ReminderIntervalDays,
+    /// <summary>
-        int? ContractType) : IUnique<int>;
+    /// Gets or sets the number of days after which the envelope expires.
+    /// </summary>
+    public int? ExpiresDays { get; set; }
+
+    /// <summary>
+    /// Gets or sets the certification type identifier.
+    /// </summary>
+    public int? CertificationType { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether an access code is required.
+    /// </summary>
+    public bool? UseAccessCode { get; set; }
+
+    /// <summary>
+    /// Gets or sets the final email template ID to be sent to the creator.
+    /// </summary>
+    public int? FinalEmailToCreator { get; set; }
+
+    /// <summary>
+    /// Gets or sets the final email template ID to be sent to the receivers.
+    /// </summary>
+    public int? FinalEmailToReceivers { get; set; }
+
+    /// <summary>
+    /// Gets or sets the timestamp when this envelope type was added.
+    /// </summary>
+    public DateTime AddedWhen { get; set; }
+
+    /// <summary>
+    /// Gets or sets the timestamp when this envelope type was last changed.
+    /// </summary>
+    public DateTime? ChangedWhen { get; set; }
+
+    /// <summary>
+    /// Gets or sets the number of days before expiry when a warning should be sent.
+    /// </summary>
+    public int? ExpiresWarningDays { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether reminder emails should be sent.
+    /// </summary>
+    public bool? SendReminderEmails { get; set; }
+
+    /// <summary>
+    /// Gets or sets the number of days before the first reminder is sent.
+    /// </summary>
+    public int? FirstReminderDays { get; set; }
+
+    /// <summary>
+    /// Gets or sets the interval in days between reminder emails.
+    /// </summary>
+    public int? ReminderIntervalDays { get; set; }
+
+    /// <summary>
+    /// Gets or sets the contract type associated with the envelope type.
+    /// </summary>
+    public int? ContractType { get; set; }
 }

EnvelopeGenerator.Application/DTOs/Receiver/ReceiverCreateDto.cs

@@ -20,7 +20,7 @@ public record ReceiverCreateDto
     }
 
     [EmailAddress]
-    public string EmailAddress { get; init; }
+    public required string EmailAddress { get; init; }
 
     public string? TotpSecretkey { get; init; }
 

EnvelopeGenerator.Application/DTOs/Receiver/ReceiverReadDto.cs

@@ -1,5 +1,4 @@
 using DigitalData.Core.Abstractions;
-using DigitalData.Core.DTO;
 using EnvelopeGenerator.Application.DTOs.EnvelopeReceiver;
 using Microsoft.AspNetCore.Mvc;
 using System.Text.Json.Serialization;
@@ -7,19 +6,27 @@ using System.Text.Json.Serialization;
 namespace EnvelopeGenerator.Application.DTOs.Receiver;
 
 [ApiExplorerSettings(IgnoreApi = true)]
-public record ReceiverReadDto(
+public class ReceiverReadDto : IUnique<int>
-    int Id,
-    string EmailAddress,
-    string Signature,
-    DateTime AddedWhen
-    ) : BaseDTO<int>(Id), IUnique<int>
 {
+    public int Id { get; set; }
+
+    public string EmailAddress { get; set; }
+
+    public string Signature { get; set; }
+
+    public DateTime AddedWhen { get; set; }
+
     [JsonIgnore]
-    public IEnumerable<EnvelopeReceiverBasicDto>? EnvelopeReceivers { get; init; }
+    public IEnumerable<EnvelopeReceiverBasicDto>? EnvelopeReceivers { get; set; }
 
     public string? LastUsedName => EnvelopeReceivers?.LastOrDefault()?.Name;
 
     public string? TotpSecretkey { get; set; } = null;
 
     public DateTime? TfaRegDeadline { get; set; }
-};
+
+    public override int GetHashCode()
+    {
+        return Id.GetHashCode();
+    }
+}

EnvelopeGenerator.Application/DTOs/Receiver/ReceiverUpdateDto.cs

@@ -3,5 +3,26 @@ using Microsoft.AspNetCore.Mvc;
 
 namespace EnvelopeGenerator.Application.DTOs.Receiver;
 
+/// <summary>
+/// Data Transfer Object for updating a receiver's information.
+/// </summary>
 [ApiExplorerSettings(IgnoreApi = true)]
-public record ReceiverUpdateDto(int Id, string? TotpSecretkey = null, DateTime? TfaRegDeadline = null) : IUnique<int>;
+public class ReceiverUpdateDto : IUnique<int>
+{
+    /// <summary>
+    /// Gets or sets the unique identifier of the receiver.
+    /// </summary>
+    public int Id { get; set; }
+
+    /// <summary>
+    /// Gets or sets the TOTP (Time-based One-Time Password) secret key.
+    /// Optional.
+    /// </summary>
+    public string? TotpSecretkey { get; set; }
+
+    /// <summary>
+    /// Gets or sets the deadline for two-factor authentication registration.
+    /// Optional.
+    /// </summary>
+    public DateTime? TfaRegDeadline { get; set; }
+}

EnvelopeGenerator.Application/DTOs/UserReceiverDto.cs

@@ -1,15 +1,46 @@
 using DigitalData.Core.Abstractions;
 using Microsoft.AspNetCore.Mvc;
 
-namespace EnvelopeGenerator.Application.DTOs
+namespace EnvelopeGenerator.Application.DTOs;
+
+/// <summary>
+/// Data Transfer Object representing a user receiver with associated details.
+/// </summary>
+[ApiExplorerSettings(IgnoreApi = true)]
+public class UserReceiverDto : IUnique<int>
 {
-    [ApiExplorerSettings(IgnoreApi = true)]
+    /// <summary>
-    public record UserReceiverDto(
+    /// Gets or sets the unique identifier of the user receiver.
-        int Id,
+    /// </summary>
-        int UserId,
+    public int Id { get; set; }
-        int ReceiverId,
+
-        string Name,
+    /// <summary>
-        string CompanyName,
+    /// Gets or sets the identifier of the user associated with the receiver.
-        string JobTitle,
+    /// </summary>
-        DateTime AddedWhen) : IUnique<int>;
+    public int UserId { get; set; }
+
+    /// <summary>
+    /// Gets or sets the identifier of the receiver.
+    /// </summary>
+    public int ReceiverId { get; set; }
+
+    /// <summary>
+    /// Gets or sets the name of the receiver.
+    /// </summary>
+    public string Name { get; set; }
+
+    /// <summary>
+    /// Gets or sets the company name of the receiver.
+    /// </summary>
+    public string CompanyName { get; set; }
+
+    /// <summary>
+    /// Gets or sets the job title of the receiver.
+    /// </summary>
+    public string JobTitle { get; set; }
+
+    /// <summary>
+    /// Gets or sets the timestamp when the user receiver was added.
+    /// </summary>
+    public DateTime AddedWhen { get; set; }
 }