From 554fdae9a8d48c2417957d6b9337213ef4bcea68 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabr=C3=ADcio=20Godoy?= Date: Sat, 7 Oct 2023 13:39:08 -0300 Subject: [PATCH] docs: add XML documentation for every member --- src/Directory.Build.props | 1 - .../ExpressionsServiceCollectionExtensions.cs | 3 +++ .../Options/EntityOptions.cs | 2 ++ .../Options/EntityOptionsConfiguration.cs | 3 +++ .../Options/EntityOptionsSelector.cs | 3 +++ .../Queries/EfDbQuery.cs | 17 ++++++++++++ .../Queries/EfQuerySource.cs | 7 +++++ .../Sessions/EfDbSession.cs | 26 +++++++++++++++++++ .../Sessions/EfDbSessionFactory.cs | 11 ++++++++ .../Sessions/EfDbSessionTransaction.cs | 6 +++++ .../Sessions/EfDbSession{TContext}.cs | 9 +++++++ .../ExpressionsServiceCollectionExtensions.cs | 5 +++- .../ExpressionsSessionBuilder.cs | 6 +++++ .../Queries/MartenDbQuery.cs | 17 ++++++++++++ .../Queries/MartenQuerySource.cs | 4 +++ .../BoundedContext/MartenDbQuerySession.cs | 7 +++++ .../BoundedContext/MartenDbSession.cs | 8 ++++++ .../BoundedContext/MartenDbSessionFactory.cs | 10 +++++++ .../Sessions/MartenDbQuerySession.cs | 11 ++++++++ .../Sessions/MartenDbSession.cs | 21 ++++++++++++++- .../Sessions/MartenDbSessionFactory.cs | 9 +++++++ src/Expressions.Reading/Queries/IDbQuery.cs | 3 ++- 22 files changed, 185 insertions(+), 4 deletions(-) diff --git a/src/Directory.Build.props b/src/Directory.Build.props index 61e89cd..8b321be 100644 --- a/src/Directory.Build.props +++ b/src/Directory.Build.props @@ -5,7 +5,6 @@ README.md true - $(NoWarn);CS1591 diff --git a/src/Expressions.EntityFrameworkCore/ExpressionsServiceCollectionExtensions.cs b/src/Expressions.EntityFrameworkCore/ExpressionsServiceCollectionExtensions.cs index 2d7b21f..dbb7d4d 100644 --- a/src/Expressions.EntityFrameworkCore/ExpressionsServiceCollectionExtensions.cs +++ b/src/Expressions.EntityFrameworkCore/ExpressionsServiceCollectionExtensions.cs @@ -3,6 +3,9 @@ namespace Raiqub.Expressions.EntityFrameworkCore; +/// +/// Extension methods for setting up Raiqub Expressions related services in an . +/// public static class ExpressionsServiceCollectionExtensions { /// Gets a builder for registering sessions and session factories using Entity Framework Core. diff --git a/src/Expressions.EntityFrameworkCore/Options/EntityOptions.cs b/src/Expressions.EntityFrameworkCore/Options/EntityOptions.cs index dfe9bf7..e6fe629 100644 --- a/src/Expressions.EntityFrameworkCore/Options/EntityOptions.cs +++ b/src/Expressions.EntityFrameworkCore/Options/EntityOptions.cs @@ -7,6 +7,8 @@ namespace Raiqub.Expressions.EntityFrameworkCore.Options; /// public sealed class EntityOptions { + /// Initializes a new instance of the class. + /// The type of the entity to configure. public EntityOptions(Type entityType) => EntityType = entityType; /// The type of the entity that this options configures. diff --git a/src/Expressions.EntityFrameworkCore/Options/EntityOptionsConfiguration.cs b/src/Expressions.EntityFrameworkCore/Options/EntityOptionsConfiguration.cs index 50ed7b3..198f47e 100644 --- a/src/Expressions.EntityFrameworkCore/Options/EntityOptionsConfiguration.cs +++ b/src/Expressions.EntityFrameworkCore/Options/EntityOptionsConfiguration.cs @@ -5,6 +5,9 @@ public sealed class EntityOptionsConfiguration { private readonly Action _configure; + /// Initializes a new instance of the class. + /// The type of the entity to configure. + /// The action used to configure the options. public EntityOptionsConfiguration(Type entityType, Action configure) { EntityType = entityType; diff --git a/src/Expressions.EntityFrameworkCore/Options/EntityOptionsSelector.cs b/src/Expressions.EntityFrameworkCore/Options/EntityOptionsSelector.cs index 9735ae8..b6af9e2 100644 --- a/src/Expressions.EntityFrameworkCore/Options/EntityOptionsSelector.cs +++ b/src/Expressions.EntityFrameworkCore/Options/EntityOptionsSelector.cs @@ -3,10 +3,13 @@ /// An selector that retrieves an based on a specified entity type. public sealed class EntityOptionsSelector { + /// Provides a value to use with sessions that do not have configuration. public static readonly EntityOptionsSelector Empty = new(Array.Empty()); private readonly Dictionary _dictionary; + /// Initializes a new instance of the class. + /// The collection of configurations. public EntityOptionsSelector(IEnumerable configurations) { _dictionary = configurations diff --git a/src/Expressions.EntityFrameworkCore/Queries/EfDbQuery.cs b/src/Expressions.EntityFrameworkCore/Queries/EfDbQuery.cs index 1eaed6c..6e76fd8 100644 --- a/src/Expressions.EntityFrameworkCore/Queries/EfDbQuery.cs +++ b/src/Expressions.EntityFrameworkCore/Queries/EfDbQuery.cs @@ -6,11 +6,18 @@ namespace Raiqub.Expressions.EntityFrameworkCore.Queries; +/// +/// Entity Framework-based implementation of a query that can be executed to retrieve instances of type . +/// +/// The type of the result returned. public class EfDbQuery : IDbQuery { private readonly ILogger _logger; private readonly IQueryable _dataSource; + /// Initializes a new instance of the class. + /// The to log to. + /// The data source to query from. public EfDbQuery( ILogger logger, IQueryable dataSource) @@ -19,6 +26,7 @@ public EfDbQuery( _dataSource = dataSource; } + /// public async Task AnyAsync(CancellationToken cancellationToken = default) { try @@ -35,6 +43,7 @@ public async Task AnyAsync(CancellationToken cancellationToken = default) } } + /// public async Task CountAsync(CancellationToken cancellationToken = default) { try @@ -51,6 +60,7 @@ public async Task CountAsync(CancellationToken cancellationToken = default) } } + /// public async Task FirstAsync(CancellationToken cancellationToken = default) { try @@ -68,6 +78,7 @@ and not InvalidOperationException } } + /// public async Task FirstOrDefaultAsync(CancellationToken cancellationToken = default) { try @@ -84,6 +95,7 @@ and not InvalidOperationException } } + /// public async Task LongCountAsync(CancellationToken cancellationToken = default) { try @@ -100,6 +112,7 @@ public async Task LongCountAsync(CancellationToken cancellationToken = def } } + /// public async Task ToPagedListAsync( int pageNumber, int pageSize, @@ -138,6 +151,7 @@ public async Task ToPagedListAsync( return pagedResultFactory(new PageInfo(pageNumber, pageSize, totalCount), items); } + /// public async Task> ToListAsync(CancellationToken cancellationToken = default) { List items; @@ -158,6 +172,7 @@ public async Task> ToListAsync(CancellationToken cancella return items; } + /// public async Task SingleAsync(CancellationToken cancellationToken = default) { try @@ -175,6 +190,7 @@ and not InvalidOperationException } } + /// public async Task SingleOrDefaultAsync(CancellationToken cancellationToken = default) { try @@ -192,6 +208,7 @@ and not InvalidOperationException } } + /// public async IAsyncEnumerable ToAsyncEnumerable( [EnumeratorCancellation] CancellationToken cancellationToken = default) { diff --git a/src/Expressions.EntityFrameworkCore/Queries/EfQuerySource.cs b/src/Expressions.EntityFrameworkCore/Queries/EfQuerySource.cs index 063c853..17d87b0 100644 --- a/src/Expressions.EntityFrameworkCore/Queries/EfQuerySource.cs +++ b/src/Expressions.EntityFrameworkCore/Queries/EfQuerySource.cs @@ -5,6 +5,7 @@ namespace Raiqub.Expressions.EntityFrameworkCore.Queries; +/// Entity framework-based implementation of provider of data sources. public class EfQuerySource : IQuerySource { private readonly DbContext _dbContext; @@ -12,6 +13,11 @@ public class EfQuerySource : IQuerySource private readonly EntityOptionsSelector _entityOptionsSelector; private readonly ChangeTracking _tracking; + /// Initializes a new instance of the class. + /// The to read/write. + /// A selector to retrieve custom SQL for querying entities. + /// A selector to retrieve options for handling entities. + /// The change tracking mode of the session. public EfQuerySource( DbContext dbContext, ISqlProviderSelector sqlProviderSelector, @@ -24,6 +30,7 @@ public EfQuerySource( _tracking = tracking; } + /// public IQueryable GetSet() where TEntity : class { EntityOptions? options = _entityOptionsSelector.GetOptions(); diff --git a/src/Expressions.EntityFrameworkCore/Sessions/EfDbSession.cs b/src/Expressions.EntityFrameworkCore/Sessions/EfDbSession.cs index bdc6353..67b74b2 100644 --- a/src/Expressions.EntityFrameworkCore/Sessions/EfDbSession.cs +++ b/src/Expressions.EntityFrameworkCore/Sessions/EfDbSession.cs @@ -7,11 +7,18 @@ namespace Raiqub.Expressions.EntityFrameworkCore.Sessions; +/// Entity Framework-based implementation of a database session for querying and saving instances. public class EfDbSession : IDbSession { private readonly ILogger _logger; private readonly EfQuerySource _querySource; + /// Initializes a new instance of the class. + /// The to log to. + /// The to read/write. + /// A selector to retrieve custom SQL for querying entities. + /// A selector to retrieve options for handling entities. + /// The change tracking mode of the session. public EfDbSession( ILogger logger, DbContext dbContext, @@ -25,21 +32,28 @@ public EfDbSession( _querySource = new EfQuerySource(dbContext, sqlProviderSelector, optionsSelector, tracking); } + /// Gets the Entity Framework session of this database session. public DbContext DbContext { get; } + + /// public ChangeTracking Tracking { get; } + /// public async ValueTask BeginTransactionAsync(CancellationToken cancellationToken = default) { var transaction = await DbContext.Database.BeginTransactionAsync(cancellationToken).ConfigureAwait(false); return new EfDbSessionTransaction(transaction); } + /// public void Add(TEntity entity) where TEntity : class => DbContext.Add(entity); + /// public void AddRange(IEnumerable entities) where TEntity : class => DbContext.AddRange(entities); + /// public async ValueTask AddAsync(TEntity entity, CancellationToken cancellationToken = default) where TEntity : class { @@ -48,6 +62,7 @@ await DbContext .ConfigureAwait(false); } + /// public async ValueTask AddRangeAsync( IEnumerable entities, CancellationToken cancellationToken = default) @@ -58,6 +73,7 @@ await DbContext .ConfigureAwait(false); } + /// public IDbQuery Query(IQueryStrategy queryStrategy) { return new EfDbQuery( @@ -65,20 +81,26 @@ public IDbQuery Query(IQueryStrategy queryStrategy) queryStrategy.Execute(_querySource)); } + /// public void Remove(TEntity entity) where TEntity : class => DbContext.Remove(entity); + /// public void RemoveRange(IEnumerable entities) where TEntity : class => DbContext.RemoveRange(entities); + /// public Task SaveChangesAsync(CancellationToken cancellationToken = default) => DbContext.SaveChangesAsync(true, cancellationToken); + /// public void Update(TEntity entity) where TEntity : class => DbContext.Update(entity); + /// public void UpdateRange(IEnumerable entities) where TEntity : class => DbContext.UpdateRange(entities); + /// public async ValueTask DisposeAsync() { await DisposeAsyncCore().ConfigureAwait(false); @@ -86,17 +108,21 @@ public async ValueTask DisposeAsync() GC.SuppressFinalize(this); } + /// public void Dispose() { Dispose(disposing: true); GC.SuppressFinalize(this); } + /// DisposeAsync method for implementations to write. protected virtual async ValueTask DisposeAsyncCore() { await DbContext.DisposeAsync(); } + /// Dispose method for implementations to write. + /// to release both managed and unmanaged resources; to release only unmanaged resources. protected virtual void Dispose(bool disposing) { if (disposing) diff --git a/src/Expressions.EntityFrameworkCore/Sessions/EfDbSessionFactory.cs b/src/Expressions.EntityFrameworkCore/Sessions/EfDbSessionFactory.cs index 1ae24c3..6438415 100644 --- a/src/Expressions.EntityFrameworkCore/Sessions/EfDbSessionFactory.cs +++ b/src/Expressions.EntityFrameworkCore/Sessions/EfDbSessionFactory.cs @@ -7,6 +7,7 @@ namespace Raiqub.Expressions.EntityFrameworkCore.Sessions; +/// Entity Framework-based implementation of a factory for creating database sessions for data access. public class EfDbSessionFactory : IDbSessionFactory, IDbQuerySessionFactory, IDbSessionFactory, IDbQuerySessionFactory where TContext : DbContext @@ -16,6 +17,11 @@ public class EfDbSessionFactory private readonly ISqlProviderSelector _sqlProviderSelector; private readonly EntityOptionsSelector _optionsSelector; + /// Initializes a new instance of the class. + /// The factory used to create loggers. + /// The factory for creating instances. + /// A selector to retrieve custom SQL for querying entities. + /// A selector to retrieve options for handling entities. public EfDbSessionFactory( ILoggerFactory loggerFactory, IDbContextFactory contextFactory, @@ -28,8 +34,13 @@ public EfDbSessionFactory( _optionsSelector = optionsSelector; } + /// Creates a new database session. + /// The change tracking mode of the new session. + /// A new database session. public EfDbSession Create(ChangeTracking? tracking = null) => CreateWithContext(tracking); + /// Creates a new database query session. + /// A new database query session. public EfDbSession CreateForQuery() => Create(ChangeTracking.Disable); IDbSession IDbSessionFactory.Create(ChangeTracking? tracking) => CreateWithoutContext(tracking); diff --git a/src/Expressions.EntityFrameworkCore/Sessions/EfDbSessionTransaction.cs b/src/Expressions.EntityFrameworkCore/Sessions/EfDbSessionTransaction.cs index 38468f5..4f6acb0 100644 --- a/src/Expressions.EntityFrameworkCore/Sessions/EfDbSessionTransaction.cs +++ b/src/Expressions.EntityFrameworkCore/Sessions/EfDbSessionTransaction.cs @@ -3,19 +3,25 @@ namespace Raiqub.Expressions.EntityFrameworkCore.Sessions; +/// Entity Framework-based implementation of started database transaction. public sealed class EfDbSessionTransaction : IDbSessionTransaction { private readonly IDbContextTransaction _contextTransaction; + /// Initializes a new instance of the class. + /// The Entity Framework transaction to wrap. public EfDbSessionTransaction(IDbContextTransaction contextTransaction) => _contextTransaction = contextTransaction; + /// public Task CommitAsync(CancellationToken cancellationToken = default) => _contextTransaction.CommitAsync(cancellationToken); + /// public ValueTask DisposeAsync() => _contextTransaction.DisposeAsync(); + /// public void Dispose() => _contextTransaction.Dispose(); } diff --git a/src/Expressions.EntityFrameworkCore/Sessions/EfDbSession{TContext}.cs b/src/Expressions.EntityFrameworkCore/Sessions/EfDbSession{TContext}.cs index 50697c4..11554f9 100644 --- a/src/Expressions.EntityFrameworkCore/Sessions/EfDbSession{TContext}.cs +++ b/src/Expressions.EntityFrameworkCore/Sessions/EfDbSession{TContext}.cs @@ -7,9 +7,17 @@ namespace Raiqub.Expressions.EntityFrameworkCore.Sessions; +/// Entity Framework-based implementation of a database session for querying and saving instances. +/// The type of the bounded context. public class EfDbSession : EfDbSession, IDbSession where TContext : DbContext { + /// Initializes a new instance of the class. + /// The to log to. + /// The to read/write. + /// A selector to retrieve custom SQL for querying entities. + /// A selector to retrieve options for handling entities. + /// The change tracking mode of the session. public EfDbSession( ILogger> logger, TContext context, @@ -21,5 +29,6 @@ public EfDbSession( Context = context; } + /// public TContext Context { get; } } diff --git a/src/Expressions.Marten/ExpressionsServiceCollectionExtensions.cs b/src/Expressions.Marten/ExpressionsServiceCollectionExtensions.cs index 24b83e3..26150bc 100644 --- a/src/Expressions.Marten/ExpressionsServiceCollectionExtensions.cs +++ b/src/Expressions.Marten/ExpressionsServiceCollectionExtensions.cs @@ -3,9 +3,12 @@ namespace Raiqub.Expressions.Marten; +/// +/// Extension methods for setting up Raiqub Expressions related services in an . +/// public static class ExpressionsServiceCollectionExtensions { - /// Gets a builder for registering sessions and session factories using Entity Framework Core. + /// Gets a builder for registering sessions and session factories using Marten. /// The to add services to. /// The change tracking mode of injected sessions. /// The so that add context calls can be chained in it. diff --git a/src/Expressions.Marten/ExpressionsSessionBuilder.cs b/src/Expressions.Marten/ExpressionsSessionBuilder.cs index fbb01f5..44317f1 100644 --- a/src/Expressions.Marten/ExpressionsSessionBuilder.cs +++ b/src/Expressions.Marten/ExpressionsSessionBuilder.cs @@ -7,11 +7,17 @@ namespace Raiqub.Expressions.Marten; +/// Used to configure the registration of sessions and sessions factories. public sealed class ExpressionsSessionBuilder { private readonly IServiceCollection _services; private readonly ChangeTracking? _tracking; + /// + /// Initializes a new instance of the class. + /// + /// The to add services to. + /// The change tracking mode of injected sessions. public ExpressionsSessionBuilder(IServiceCollection services, ChangeTracking? tracking) { _services = services; diff --git a/src/Expressions.Marten/Queries/MartenDbQuery.cs b/src/Expressions.Marten/Queries/MartenDbQuery.cs index d819cad..376746e 100644 --- a/src/Expressions.Marten/Queries/MartenDbQuery.cs +++ b/src/Expressions.Marten/Queries/MartenDbQuery.cs @@ -7,11 +7,18 @@ namespace Raiqub.Expressions.Marten.Queries; +/// +/// Marten-based implementation of a query that can be executed to retrieve instances of type . +/// +/// The type of the result returned. public class MartenDbQuery : IDbQuery { private readonly ILogger _logger; private readonly IQueryable _dataSource; + /// Initializes a new instance of the class. + /// The to log to. + /// The data source to query from. public MartenDbQuery( ILogger logger, IQueryable dataSource) @@ -20,6 +27,7 @@ public MartenDbQuery( _dataSource = dataSource; } + /// public async Task AnyAsync(CancellationToken cancellationToken = default) { try @@ -36,6 +44,7 @@ public async Task AnyAsync(CancellationToken cancellationToken = default) } } + /// public async Task CountAsync(CancellationToken cancellationToken = default) { try @@ -52,6 +61,7 @@ public async Task CountAsync(CancellationToken cancellationToken = default) } } + /// public async Task FirstAsync(CancellationToken cancellationToken = default) { try @@ -69,6 +79,7 @@ and not InvalidOperationException } } + /// public async Task FirstOrDefaultAsync(CancellationToken cancellationToken = default) { try @@ -85,6 +96,7 @@ and not InvalidOperationException } } + /// public async Task LongCountAsync(CancellationToken cancellationToken = default) { try @@ -101,6 +113,7 @@ public async Task LongCountAsync(CancellationToken cancellationToken = def } } + /// public async Task ToPagedListAsync( int pageNumber, int pageSize, @@ -129,6 +142,7 @@ public async Task ToPagedListAsync( return pagedResultFactory(new PageInfo(pageNumber, pageSize, stats.TotalResults), items); } + /// public async Task> ToListAsync(CancellationToken cancellationToken = default) { IReadOnlyList items; @@ -149,6 +163,7 @@ public async Task> ToListAsync(CancellationToken cancella return items; } + /// public async Task SingleAsync(CancellationToken cancellationToken = default) { try @@ -166,6 +181,7 @@ and not InvalidOperationException } } + /// public async Task SingleOrDefaultAsync(CancellationToken cancellationToken = default) { try @@ -183,6 +199,7 @@ and not InvalidOperationException } } + /// public IAsyncEnumerable ToAsyncEnumerable(CancellationToken cancellationToken = default) { return _dataSource.ToAsyncEnumerable(cancellationToken); diff --git a/src/Expressions.Marten/Queries/MartenQuerySource.cs b/src/Expressions.Marten/Queries/MartenQuerySource.cs index ae89545..00f694f 100644 --- a/src/Expressions.Marten/Queries/MartenQuerySource.cs +++ b/src/Expressions.Marten/Queries/MartenQuerySource.cs @@ -3,11 +3,15 @@ namespace Raiqub.Expressions.Marten.Queries; +/// Marten-based implementation of provider of data sources. public class MartenQuerySource : IQuerySource { private readonly IQuerySession _session; + /// Initializes a new instance of the class. + /// The Marten session to query from. public MartenQuerySource(IQuerySession session) => _session = session; + /// public IQueryable GetSet() where TEntity : class => _session.Query(); } diff --git a/src/Expressions.Marten/Sessions/BoundedContext/MartenDbQuerySession.cs b/src/Expressions.Marten/Sessions/BoundedContext/MartenDbQuerySession.cs index d50eb09..595f48f 100644 --- a/src/Expressions.Marten/Sessions/BoundedContext/MartenDbQuerySession.cs +++ b/src/Expressions.Marten/Sessions/BoundedContext/MartenDbQuerySession.cs @@ -4,14 +4,21 @@ namespace Raiqub.Expressions.Marten.Sessions.BoundedContext; +/// Marten-based implementation of a database session for querying instances. +/// The type of the bounded context. public class MartenDbQuerySession : MartenDbQuerySession, IDbQuerySession where TContext : IDocumentStore { + /// Initializes a new instance of the class. + /// The to log to. + /// The Marten session to query from. + /// The bounded context associated with this query session. public MartenDbQuerySession(ILogger> logger, IQuerySession session, TContext context) : base(logger, session) { Context = context; } + /// public TContext Context { get; } } diff --git a/src/Expressions.Marten/Sessions/BoundedContext/MartenDbSession.cs b/src/Expressions.Marten/Sessions/BoundedContext/MartenDbSession.cs index 7ba8880..a0b7a90 100644 --- a/src/Expressions.Marten/Sessions/BoundedContext/MartenDbSession.cs +++ b/src/Expressions.Marten/Sessions/BoundedContext/MartenDbSession.cs @@ -5,9 +5,16 @@ namespace Raiqub.Expressions.Marten.Sessions.BoundedContext; +/// Marten-based implementation of a database session for querying and saving instances. +/// The type of the bounded context. public class MartenDbSession : MartenDbSession, IDbSession where TContext : IDocumentStore { + /// Initializes a new instance of the class. + /// The to log to. + /// The to read/write. + /// The change tracking mode of the session. + /// The bounded context associated with this query session. public MartenDbSession( ILogger> logger, IDocumentSession session, @@ -18,5 +25,6 @@ public MartenDbSession( Context = context; } + /// public TContext Context { get; } } diff --git a/src/Expressions.Marten/Sessions/BoundedContext/MartenDbSessionFactory.cs b/src/Expressions.Marten/Sessions/BoundedContext/MartenDbSessionFactory.cs index ca5675e..65abcf7 100644 --- a/src/Expressions.Marten/Sessions/BoundedContext/MartenDbSessionFactory.cs +++ b/src/Expressions.Marten/Sessions/BoundedContext/MartenDbSessionFactory.cs @@ -5,24 +5,34 @@ namespace Raiqub.Expressions.Marten.Sessions.BoundedContext; +/// Marten-based implementation of a factory for creating database sessions for data access. +/// The type of the bounded context. public class MartenDbSessionFactory : IDbSessionFactory, IDbQuerySessionFactory where TContext : class, IDocumentStore { private readonly ILoggerFactory _loggerFactory; private readonly TContext _context; + /// Initializes a new instance of the class. + /// The factory used to create loggers. + /// The to read/write. public MartenDbSessionFactory(ILoggerFactory loggerFactory, TContext context) { _loggerFactory = loggerFactory; _context = context; } + /// Creates a new database session. + /// The change tracking mode of the new session. + /// A new database session. public IDbSession Create(ChangeTracking? tracking = null) => new MartenDbSession( _loggerFactory.CreateLogger>(), MartenDbSessionFactory.CreateSession(_context, tracking ?? ChangeTracking.Default), tracking ?? ChangeTracking.Default, _context); + /// Creates a new database query session. + /// A new database query session. public IDbQuerySession CreateForQuery() => new MartenDbQuerySession( _loggerFactory.CreateLogger>(), _context.QuerySession(), diff --git a/src/Expressions.Marten/Sessions/MartenDbQuerySession.cs b/src/Expressions.Marten/Sessions/MartenDbQuerySession.cs index 871ff4f..a69256a 100644 --- a/src/Expressions.Marten/Sessions/MartenDbQuerySession.cs +++ b/src/Expressions.Marten/Sessions/MartenDbQuerySession.cs @@ -6,12 +6,16 @@ namespace Raiqub.Expressions.Marten.Sessions; +/// Marten-based implementation of a database session for querying instances. public class MartenDbQuerySession : IDbQuerySession { private readonly ILogger _logger; private readonly IQuerySession _session; private readonly MartenQuerySource _querySource; + /// Initializes a new instance of the class. + /// The to log to. + /// The Marten session to query from. public MartenDbQuerySession(ILogger logger, IQuerySession session) { _logger = logger; @@ -19,13 +23,16 @@ public MartenDbQuerySession(ILogger logger, IQuerySession _querySource = new MartenQuerySource(session); } + /// Gets the Marten session used by this database session. public virtual IQuerySession MartenSession => _session; + /// public IDbQuery Query(IQueryStrategy queryStrategy) { return new MartenDbQuery(_logger, queryStrategy.Execute(_querySource)); } + /// public async ValueTask DisposeAsync() { await DisposeAsyncCore().ConfigureAwait(false); @@ -33,17 +40,21 @@ public async ValueTask DisposeAsync() GC.SuppressFinalize(this); } + /// public void Dispose() { Dispose(disposing: true); GC.SuppressFinalize(this); } + /// DisposeAsync method for implementations to write. protected virtual async ValueTask DisposeAsyncCore() { await _session.DisposeAsync(); } + /// Dispose method for implementations to write. + /// to release both managed and unmanaged resources; to release only unmanaged resources. protected virtual void Dispose(bool disposing) { if (disposing) diff --git a/src/Expressions.Marten/Sessions/MartenDbSession.cs b/src/Expressions.Marten/Sessions/MartenDbSession.cs index b6ebee7..d59795b 100644 --- a/src/Expressions.Marten/Sessions/MartenDbSession.cs +++ b/src/Expressions.Marten/Sessions/MartenDbSession.cs @@ -1,13 +1,19 @@ -using Marten; +using System.Diagnostics.CodeAnalysis; +using Marten; using Microsoft.Extensions.Logging; using Raiqub.Expressions.Sessions; namespace Raiqub.Expressions.Marten.Sessions; +/// Marten-based implementation of a database session for querying and saving instances. public class MartenDbSession : MartenDbQuerySession, IDbSession { private readonly IDocumentSession _session; + /// Initializes a new instance of the class. + /// The to log to. + /// The to read/write. + /// The change tracking mode of the session. public MartenDbSession(ILogger logger, IDocumentSession session, ChangeTracking tracking) : base(logger, session) { @@ -15,28 +21,36 @@ public MartenDbSession(ILogger logger, IDocumentSession session Tracking = tracking; } + /// public override IDocumentSession MartenSession => _session; + /// public ChangeTracking Tracking { get; } + /// + [DoesNotReturn] public ValueTask BeginTransactionAsync(CancellationToken cancellationToken = default) { throw new NotSupportedException( "Transactions are not currently supported by Marten implementation of IDbSession"); } + /// public void Add(TEntity entity) where TEntity : class => AddRange(new[] { entity }); + /// public void AddRange(IEnumerable entities) where TEntity : class => _session.Store(entities); + /// public ValueTask AddAsync(TEntity entity, CancellationToken cancellationToken = default) where TEntity : class { return AddRangeAsync(new[] { entity }, cancellationToken); } + /// public ValueTask AddRangeAsync( IEnumerable entities, CancellationToken cancellationToken = default) @@ -46,18 +60,23 @@ public ValueTask AddRangeAsync( return ValueTask.CompletedTask; } + /// public void Remove(TEntity entity) where TEntity : class => _session.Delete(entity); + /// public void RemoveRange(IEnumerable entities) where TEntity : class => _session.DeleteObjects(entities); + /// public Task SaveChangesAsync(CancellationToken cancellationToken = default) => _session.SaveChangesAsync(cancellationToken); + /// public void Update(TEntity entity) where TEntity : class => UpdateRange(new[] { entity }); + /// public void UpdateRange(IEnumerable entities) where TEntity : class => _session.Store(entities); } diff --git a/src/Expressions.Marten/Sessions/MartenDbSessionFactory.cs b/src/Expressions.Marten/Sessions/MartenDbSessionFactory.cs index 9aebaa0..67cb66a 100644 --- a/src/Expressions.Marten/Sessions/MartenDbSessionFactory.cs +++ b/src/Expressions.Marten/Sessions/MartenDbSessionFactory.cs @@ -4,22 +4,31 @@ namespace Raiqub.Expressions.Marten.Sessions; +/// Marten-based implementation of a factory for creating database sessions for data access. public class MartenDbSessionFactory : IDbSessionFactory, IDbQuerySessionFactory { private readonly ILoggerFactory _loggerFactory; private readonly IDocumentStore _documentStore; + /// Initializes a new instance of the class. + /// The factory used to create loggers. + /// The to read/write. public MartenDbSessionFactory(ILoggerFactory loggerFactory, IDocumentStore documentStore) { _loggerFactory = loggerFactory; _documentStore = documentStore; } + /// Creates a new database session. + /// The change tracking mode of the new session. + /// A new database session. public IDbSession Create(ChangeTracking? tracking = null) => new MartenDbSession( _loggerFactory.CreateLogger(), CreateSession(_documentStore, tracking ?? ChangeTracking.Default), tracking ?? ChangeTracking.Default); + /// Creates a new database query session. + /// A new database query session. public IDbQuerySession CreateForQuery() => new MartenDbQuerySession( _loggerFactory.CreateLogger(), _documentStore.QuerySession()); diff --git a/src/Expressions.Reading/Queries/IDbQuery.cs b/src/Expressions.Reading/Queries/IDbQuery.cs index 9b6fa52..d4f220b 100644 --- a/src/Expressions.Reading/Queries/IDbQuery.cs +++ b/src/Expressions.Reading/Queries/IDbQuery.cs @@ -3,8 +3,9 @@ namespace Raiqub.Expressions.Queries; /// -/// Represents a query that can be executed to retrieve entities of type . +/// Represents a query that can be executed to retrieve instances of type . /// +/// The type of the result returned. public interface IDbQuery { /// Determines whether the query returns any elements.