Skip to content
This repository was archived by the owner on Jan 27, 2022. It is now read-only.

Commit 4208b36

Browse files
author
Iain Scott
committed
Add some documentation.
1 parent 8b8dd3d commit 4208b36

5 files changed

Lines changed: 95 additions & 4 deletions

File tree

‎src/Winton.DomainModelling.DocumentDb/EntityExtensions.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ public static TEntity WithId<TEntity, TEntityId>(this TEntity entity)
2323
}
2424
catch (Exception)
2525
{
26-
throw new NotSupportedException($"Automatic generation of {typeof(TEntityId).Name} ID not supported.");
26+
throw new NotSupportedException($"Automatic ID generation for {typeof(TEntityId).Name} not supported.");
2727
}
2828
}
2929
}

‎src/Winton.DomainModelling.DocumentDb/EntityFacade.cs‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,12 +7,24 @@
77

88
namespace Winton.DomainModelling.DocumentDb
99
{
10+
/// <inheritdoc />
11+
/// <summary>
12+
/// An abstraction layer over <see cref="Entity{TEntityId}" /> CRUD operations in DocumentDb. Allows multiple entity
13+
/// types to be transparently stored in one collection using a 'wrapper' document type with a type discriminator and
14+
/// namespaced ID.
15+
/// </summary>
1016
public sealed class EntityFacade : IEntityFacade
1117
{
1218
private readonly Database _database;
1319
private readonly IDocumentClient _documentClient;
1420
private readonly DocumentCollection _documentCollection;
1521

22+
/// <summary>
23+
/// Initializes a new instance of the <see cref="EntityFacade" /> class.
24+
/// </summary>
25+
/// <param name="database">The DocumentDb database.</param>
26+
/// <param name="documentCollection">The DocumentDb collection. Partitioned collections are not supported.</param>
27+
/// <param name="documentClient">A document client implementation.</param>
1628
public EntityFacade(Database database, DocumentCollection documentCollection, IDocumentClient documentClient)
1729
{
1830
if (documentCollection.PartitionKey.Paths.Any())
@@ -25,6 +37,16 @@ public EntityFacade(Database database, DocumentCollection documentCollection, ID
2537
_documentClient = documentClient;
2638
}
2739

40+
/// <inheritdoc />
41+
/// <summary>
42+
/// Create an <see cref="T:Winton.DomainModelling.Entity`1" /> of a specified type. Supports automatic ID generation
43+
/// for
44+
/// <see cref="T:System.String" />-serializable ID types, otherwise IDs must be set before creating.
45+
/// </summary>
46+
/// <typeparam name="TEntity">The type of the entity.</typeparam>
47+
/// <typeparam name="TEntityId">The ID type of the entity.</typeparam>
48+
/// <param name="entity">The <see cref="T:Winton.DomainModelling.Entity`1" /> to persist.</param>
49+
/// <returns>The created <see cref="T:Winton.DomainModelling.Entity`1" />.</returns>
2850
public async Task<TEntity> Create<TEntity, TEntityId>(TEntity entity)
2951
where TEntity : Entity<TEntityId>
3052
where TEntityId : IEquatable<TEntityId>
@@ -38,13 +60,28 @@ public async Task<TEntity> Create<TEntity, TEntityId>(TEntity entity)
3860
return responseDocument.Entity;
3961
}
4062

63+
/// <inheritdoc />
64+
/// <summary>
65+
/// Delete an <see cref="T:Winton.DomainModelling.Entity`1" /> of a specified type by ID.
66+
/// </summary>
67+
/// <typeparam name="TEntity">The type of the entity.</typeparam>
68+
/// <typeparam name="TEntityId">The ID type of the entity.</typeparam>
69+
/// <param name="id">The ID of the <see cref="T:Winton.DomainModelling.Entity`1" /> to delete.</param>
70+
/// <returns>A Task.</returns>
4171
public async Task Delete<TEntity, TEntityId>(TEntityId id)
4272
where TEntity : Entity<TEntityId>
4373
where TEntityId : IEquatable<TEntityId>
4474
{
4575
await _documentClient.DeleteDocumentAsync(GetUri<TEntity, TEntityId>(id));
4676
}
4777

78+
/// <inheritdoc />
79+
/// <summary>
80+
/// Query <see cref="T:Winton.DomainModelling.Entity`1" /> instances of a specified type.
81+
/// </summary>
82+
/// <typeparam name="TEntity">The type of the entity.</typeparam>
83+
/// <typeparam name="TEntityId">The ID type of the entity.</typeparam>
84+
/// <returns>An <see cref="T:System.Linq.IQueryable`1" />.</returns>
4885
public IQueryable<TEntity> Query<TEntity, TEntityId>()
4986
where TEntity : Entity<TEntityId>
5087
where TEntityId : IEquatable<TEntityId>
@@ -56,6 +93,14 @@ public IQueryable<TEntity> Query<TEntity, TEntityId>()
5693
.Select(x => x.Entity);
5794
}
5895

96+
/// <inheritdoc />
97+
/// <summary>
98+
/// Read an <see cref="T:Winton.DomainModelling.Entity`1" /> of a specified type by ID.
99+
/// </summary>
100+
/// <typeparam name="TEntity">The type of the entity.</typeparam>
101+
/// <typeparam name="TEntityId">The ID type of the entity.</typeparam>
102+
/// <param name="id">The ID of the <see cref="T:Winton.DomainModelling.Entity`1" /> to read.</param>
103+
/// <returns>The <see cref="T:Winton.DomainModelling.Entity`1" /> with the given ID, if it exists, otherwise null.</returns>
59104
public async Task<TEntity> Read<TEntity, TEntityId>(TEntityId id)
60105
where TEntity : Entity<TEntityId>
61106
where TEntityId : IEquatable<TEntityId>
@@ -75,6 +120,14 @@ public async Task<TEntity> Read<TEntity, TEntityId>(TEntityId id)
75120
}
76121
}
77122

123+
/// <inheritdoc />
124+
/// <summary>
125+
/// Upsert an <see cref="T:Winton.DomainModelling.Entity`1" /> of a specified type. The ID must be set.
126+
/// </summary>
127+
/// <typeparam name="TEntity">The type of the entity.</typeparam>
128+
/// <typeparam name="TEntityId">The ID type of the entity.</typeparam>
129+
/// <param name="entity">The <see cref="T:Winton.DomainModelling.Entity`1" /> to upsert.</param>
130+
/// <returns>The upserted <see cref="T:Winton.DomainModelling.Entity`1" />.</returns>
78131
public async Task<TEntity> Upsert<TEntity, TEntityId>(TEntity entity)
79132
where TEntity : Entity<TEntityId>
80133
where TEntityId : IEquatable<TEntityId>

‎src/Winton.DomainModelling.DocumentDb/IEntityFacade.cs‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,24 +4,62 @@
44

55
namespace Winton.DomainModelling.DocumentDb
66
{
7+
/// <summary>
8+
/// An abstraction layer over <see cref="Entity{TEntityId}" /> CRUD operations in DocumentDb.
9+
/// </summary>
710
public interface IEntityFacade
811
{
12+
/// <summary>
13+
/// Create an <see cref="Entity{TEntityId}" /> of a specified type. Supports automatic ID generation for
14+
/// <see cref="string" />-serializable ID types, otherwise IDs must be set before creating.
15+
/// </summary>
16+
/// <typeparam name="TEntity">The type of the entity.</typeparam>
17+
/// <typeparam name="TEntityId">The ID type of the entity.</typeparam>
18+
/// <param name="entity">The <see cref="Entity{TEntityId}" /> to persist.</param>
19+
/// <returns>The created <see cref="Entity{TEntityId}" />.</returns>
920
Task<TEntity> Create<TEntity, TEntityId>(TEntity entity)
1021
where TEntity : Entity<TEntityId>
1122
where TEntityId : IEquatable<TEntityId>;
1223

24+
/// <summary>
25+
/// Delete an <see cref="Entity{TEntityId}" /> of a specified type by ID.
26+
/// </summary>
27+
/// <typeparam name="TEntity">The type of the entity.</typeparam>
28+
/// <typeparam name="TEntityId">The ID type of the entity.</typeparam>
29+
/// <param name="id">The ID of the <see cref="Entity{TEntityId}" /> to delete.</param>
30+
/// <returns>A Task.</returns>
1331
Task Delete<TEntity, TEntityId>(TEntityId id)
1432
where TEntity : Entity<TEntityId>
1533
where TEntityId : IEquatable<TEntityId>;
1634

35+
/// <summary>
36+
/// Query <see cref="Entity{TEntityId}" /> instances of a specified type.
37+
/// </summary>
38+
/// <typeparam name="TEntity">The type of the entity.</typeparam>
39+
/// <typeparam name="TEntityId">The ID type of the entity.</typeparam>
40+
/// <returns>An <see cref="IQueryable{TEntity}" />.</returns>
1741
IQueryable<TEntity> Query<TEntity, TEntityId>()
1842
where TEntity : Entity<TEntityId>
1943
where TEntityId : IEquatable<TEntityId>;
2044

45+
/// <summary>
46+
/// Read an <see cref="Entity{TEntityId}" /> of a specified type by ID.
47+
/// </summary>
48+
/// <typeparam name="TEntity">The type of the entity.</typeparam>
49+
/// <typeparam name="TEntityId">The ID type of the entity.</typeparam>
50+
/// <param name="id">The ID of the <see cref="Entity{TEntityId}" /> to read.</param>
51+
/// <returns>The <see cref="Entity{TEntityId}" /> with the given ID, if it exists, otherwise null.</returns>
2152
Task<TEntity> Read<TEntity, TEntityId>(TEntityId id)
2253
where TEntity : Entity<TEntityId>
2354
where TEntityId : IEquatable<TEntityId>;
2455

56+
/// <summary>
57+
/// Upsert an <see cref="Entity{TEntityId}" /> of a specified type. The ID must be set.
58+
/// </summary>
59+
/// <typeparam name="TEntity">The type of the entity.</typeparam>
60+
/// <typeparam name="TEntityId">The ID type of the entity.</typeparam>
61+
/// <param name="entity">The <see cref="Entity{TEntityId}" /> to upsert.</param>
62+
/// <returns>The upserted <see cref="Entity{TEntityId}" />.</returns>
2563
Task<TEntity> Upsert<TEntity, TEntityId>(TEntity entity)
2664
where TEntity : Entity<TEntityId>
2765
where TEntityId : IEquatable<TEntityId>;

‎src/Winton.DomainModelling.DocumentDb/Winton.DomainModelling.DocumentDb.csproj‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
<Company>Winton</Company>
66
<Copyright>Copyright 2018 Winton</Copyright>
77
<Description>Provides common types for persisting domain objects to DocumentDB.</Description>
8-
<GenerateDocumentationFile>False</GenerateDocumentationFile>
8+
<GenerateDocumentationFile>True</GenerateDocumentationFile>
99
<NoWarn>$(NoWarn);SA0001;SA1101;SA1309;SA1413;SA1633;SA1652</NoWarn>
1010
<PackageId>Winton.DomainModelling.DocumentDb</PackageId>
1111
<PackageRequireLicenseAcceptance>False</PackageRequireLicenseAcceptance>

‎test/Winton.DomainModelling.DocumentDb.Tests/EntityExtensionsTests.cs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -78,7 +78,7 @@ private void ShouldThrowForEntityWithoutIntId()
7878
Action action = entityWithoutId.Invoking(e => e.WithId<EntityWithIntId, int>());
7979

8080
action.Should().Throw<NotSupportedException>()
81-
.WithMessage("Automatic generation of Int32 ID not supported.");
81+
.WithMessage("Automatic ID generation for Int32 not supported.");
8282
}
8383

8484
[Fact]
@@ -89,7 +89,7 @@ private void ShouldThrowForEntityWithoutNumericalId()
8989
Action action = entityWithoutId.Invoking(e => e.WithId<EntityWithNumericalId, NumericalId>());
9090

9191
action.Should().Throw<NotSupportedException>()
92-
.WithMessage("Automatic generation of NumericalId ID not supported.");
92+
.WithMessage("Automatic ID generation for NumericalId not supported.");
9393
}
9494

9595
[JsonConverter(typeof(SingleValueConverter))]

0 commit comments

Comments
 (0)