Devlooped.TableStorage
5.2.1
Prefix Reserved
dotnet add package Devlooped.TableStorage --version 5.2.1
NuGet\Install-Package Devlooped.TableStorage -Version 5.2.1
<PackageReference Include="Devlooped.TableStorage" Version="5.2.1" />
paket add Devlooped.TableStorage --version 5.2.1
#r "nuget: Devlooped.TableStorage, 5.2.1"
// Install Devlooped.TableStorage as a Cake Addin #addin nuget:?package=Devlooped.TableStorage&version=5.2.1 // Install Devlooped.TableStorage as a Cake Tool #tool nuget:?package=Devlooped.TableStorage&version=5.2.1
This project uses SponsorLink and may issue IDE-only warnings if no active sponsorship is detected.
Repository pattern with POCO object support for storing to Azure/CosmosDB Table Storage
NOTE: This library is a thin wrapper around the latest Azure SDK v12+ for Table Storage, and uses CloudStorageAccount which is a 100% backwards compatible implementation of the Azure SDK v11
CloudStorageAccount
class.
Usage
Given an entity like:
public record Product(string Category, string Id)
{
public required string? Title { get; init; }
public double Price { get; init; }
public DateOnly CreatedAt { get; init; }
}
NOTE: entity can have custom constructor, key properties can be read-only (Category and Id in this case for example), and it doesn't need to inherit from anything, implement any interfaces or use any custom attributes (unless you want to). As shown above, it can even be a simple record type.
The entity can be stored and retrieved with:
var storageAccount = CloudStorageAccount.DevelopmentStorageAccount; // or production one
// We lay out the parameter names for clarity only.
var repo = TableRepository.Create<Product>(storageAccount,
tableName: "Products",
partitionKey: p => p.Category,
rowKey: p => p.Id);
var product = new Product("book", "1234")
{
Title = "Table Storage is Cool",
Price = 25.5,
};
// Insert or Update behavior (aka "upsert")
await repo.PutAsync(product);
// Enumerate all products in category "book"
await foreach (var p in repo.EnumerateAsync("book"))
Console.WriteLine(p.Price);
// Query books priced in the 20-50 range,
// project just title + price
await foreach (var info in from prod in repo.CreateQuery()
where prod.Price >= 20 and prod.Price <= 50
select new { prod.Title, prod.Price })
Console.WriteLine($"{info.Title}: {info.Price}");
// Get previously saved product.
Product saved = await repo.GetAsync("book", "1234");
// Delete product
await repo.DeleteAsync("book", "1234");
// Can also delete passing entity
await repo.DeleteAsync(saved);
Attributes can also be used to eliminate the need for lambdas altogether when the entity storage layout is known at compile time:
[Table("Products")]
public record Product([PartitionKey] string Category, [RowKey] string Id) ...
var storageAccount = CloudStorageAccount.DevelopmentStorageAccount;
// Everything discovered from attributes.
var repo = TableRepository.Create<Product>(storageAccount);
See the Attributes section below for more details on how to use them.
If the product were books for example, it might make sense to partition by author.
In that case, you could use a TableRepository<Book>
when saving:
public record Book([RowKey] string ISBN, string Title, string Author, BookFormat Format, int Pages);
var repo = TableRepository.Create<Product>(storageAccount, "Books",
partitionKey: x => x.Author);
await repo.PutAsync(book);
Note how you can mix and match attributes and explicit lambdas as needed. The latter takes precedence over the former.
And later on when listing/filtering books by a particular author, you can use
a TablePartition<Product>
so all querying is automatically scoped to that author:
var partition = TablePartition.Create<Book>(storageAccount, "Books",
partitionKey: "Rick Riordan");
// Get Rick Riordan books, only from Disney/Hyperion, with over 1000 pages
var query = from book in repo.CreateQuery()
where
book.ISBN.CompareTo("97814231") >= 0 &&
book.ISBN.CompareTo("97814232") < 0 &&
book.Pages >= 1000
select new { book.ISBN, book.Title };
Using table partitions is quite convenient for handling reference data too, for example. Enumerating all entries in the partition wouldn't be something you'd typically do for your "real" data, but for reference data, it could come in handy.
NOTE: if access to the
Timestamp
managed by Azure Table Storage for the entity is needed, just declare a property with that name with eitherDateTimeOffset
,DateTime
orstring
type to read it.
Stored entities using TableRepository
and TablePartition
use individual columns for
properties, which makes it easy to browse the data (and query, as shown above!).
NOTE: partition and row keys can also be typed as
Guid
Document-based storage is also available via DocumentRepository
and DocumentPartition
if
you don't need the individual columns.
Document Storage
The DocumentRepository.Create
and DocumentPartition.Create
factory methods provide access
to document-based storage, exposing the a similar API as column-based storage.
Document repositories cause entities to be persisted as a single document column, alongside type and version information to handle versioning a the app level as needed.
The API is mostly the same as for column-based repositories (document repositories implement
the same underlying ITableStorage
interface):
public record Product(string Category, string Id)
{
public string? Title { get; init; }
public double Price { get; init; }
public DateOnly CreatedAt { get; init; }
}
var book = new Product("book", "9781473217386")
{
Title = "Neuromancer",
Price = 7.32
};
// Column-based storage
var repo = TableRepository.Create<Product>(
CloudStorageAccount.DevelopmentStorageAccount,
tableName: "Products",
partitionKey: p => p.Category,
rowKey: p => p.Id);
await repo.PutAsync(book);
// Document-based storage
var docs = DocumentRepository.Create<Product>(
CloudStorageAccount.DevelopmentStorageAccount,
tableName: "Documents",
partitionKey: p => p.Category,
rowKey: p => p.Id
serializer: [SERIALIZER]);
await docs.PutAsync(book);
If not provided, the serializer defaults to the
System.Text.Json
-basedDocumentSerializer.Default
.
The resulting differences in storage can be seen in the following screenshots of the Azure Storage Explorer:
The Type
column persisted in the documents table is the Type.FullName
of the persisted entity, and the
Version
is the [Major].[Minor]
of its assembly, which could be used for advanced data migration scenarios.
The major and minor version components are also provided as individual columns for easier querying
by various version ranges, using IDocumentRepository.EnumerateAsync(predicate)
.
In addition to the default built-in JSON plain-text based serializer (which uses the System.Text.Json package), there are other alternative serializers for the document-based repository, including various binary serializers which will instead persist the document as a byte array:
You can pass the serializer to use to the factory method as follows:
var repo = TableRepository.Create<Product>(...,
serializer: [JsonDocumentSerializer|BsonDocumentSerializer|MessagePackDocumentSerializer|ProtobufDocumentSerializer].Default);
NOTE: when using alternative serializers, entities might need to be annotated with whatever attributes are required by the underlying libraries.
Attributes
If you want to avoid using strings with the factory methods, you can also annotate the entity type to modify the default values used:
[Table("tableName")]
: class-level attribute to change the default when no value is provided[PartitionKey]
: annotates the property that should be used as the partition key[RowKey]
: annotates the property that should be used as the row key.
Values passed to the factory methods override declarative attributes.
For the products example above, your record entity could be:
[Table("Products")]
public record Product([PartitionKey] string Category, [RowKey] string Id)
{
public string? Title { get; init; }
public double Price { get; init; }
}
And creating the repository wouldn't require any arguments besides the storage account:
var repo = TableRepository.Create<Product>(CloudStorageAccount.DevelopmentStorageAccount);
In addition, if you want to omit a particular property from persistence, you can annotate
it with [Browsable(false)]
and it will be skipped when persisting and reading the entity.
TableEntity Support
Since these repository APIs are quite a bit more intuitive than working directly against a
TableClient
, you might want to retrieve/enumerate entities just by their built-in TableEntity
properties, like PartitionKey
, RowKey
, Timestamp
and ETag
. For this scenario, we
also support creating ITableRepository<TableEntity>
and ITablePartition<TableEntity>
by using the factory methods TableRepository.Create(...)
and TablePartition.Create(...)
without a (generic) entity type argument.
For example, given you know all Region
entities saved in the example above, use the region Code
as the RowKey
, you could simply enumerate all regions without using the Region
type at all:
var account = CloudStorageAccount.DevelopmentStorageAccount; // or production one
var repo = TablePartition.Create(storageAccount,
tableName: "Reference",
partitionKey: "Region");
// Enumerate all regions within the partition as plain TableEntities
await foreach (TableEntity region in repo.EnumerateAsync())
Console.WriteLine(region.RowKey);
You can access and add additional properties by just using the entity indexer, which you can
later persist by calling PutAsync
:
await repo.PutAsync(
new TableEntity("Book", "9781473217386")
{
["Title"] = "Neuromancer",
["Price"] = 7.32
});
var entity = await repo.GetAsync("Book", "9781473217386");
Assert.Equal("Neuromancer", entity["Title"]);
Assert.Equal(7.32, (double)entity["Price"]);
Sponsors
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
.NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.0 is compatible. netstandard2.1 is compatible. |
.NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen40 was computed. tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.0
- Azure.Data.Tables (>= 12.9.1)
- Devlooped.CloudStorageAccount (>= 1.3.0)
- Microsoft.OData.Client (>= 7.21.3)
- System.Text.Json (>= 6.0.10)
-
.NETStandard 2.1
- Azure.Data.Tables (>= 12.9.1)
- Devlooped.CloudStorageAccount (>= 1.3.0)
- Microsoft.OData.Client (>= 7.21.3)
- System.Text.Json (>= 6.0.10)
-
net6.0
- Azure.Data.Tables (>= 12.9.1)
- Devlooped.CloudStorageAccount (>= 1.3.0)
- Microsoft.OData.Client (>= 7.21.3)
- System.Text.Json (>= 6.0.10)
NuGet packages (4)
Showing the top 4 NuGet packages that depend on Devlooped.TableStorage:
Package | Downloads |
---|---|
Devlooped.TableStorage.Protobuf
A Protocol Buffers binary serializer for use with document-based repositories. > This project uses SponsorLink and may issue IDE-only warnings if no active sponsorship is detected. > Learn more at https://github.com/devlooped#sponsorlink. |
|
Devlooped.TableStorage.Bson
A BSON binary serializer for use with document-based repositories. > This project uses SponsorLink and may issue IDE-only warnings if no active sponsorship is detected. > Learn more at https://github.com/devlooped#sponsorlink. |
|
Devlooped.TableStorage.MessagePack
A MessagePack binary serializer for use with document-based repositories. > This project uses SponsorLink and may issue IDE-only warnings if no active sponsorship is detected. > Learn more at https://github.com/devlooped#sponsorlink. |
|
Devlooped.TableStorage.Newtonsoft
A Json.NET serializer for use with document-based repositories. > This project uses SponsorLink and may issue IDE-only warnings if no active sponsorship is detected. > Learn more at https://github.com/devlooped#sponsorlink. |
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
5.2.1 | 830 | 10/22/2024 |
5.2.0 | 985 | 7/24/2024 |
5.2.0-rc.1 | 86 | 7/13/2024 |
5.2.0-rc | 225 | 7/10/2024 |
5.2.0-beta | 246 | 7/6/2024 |
5.1.2 | 1,449 | 1/25/2024 |
5.1.1 | 353 | 10/4/2023 |
5.1.0 | 732 | 8/11/2023 |
4.1.3 | 1,264 | 1/20/2023 |
4.1.2 | 860 | 1/16/2023 |
4.0.0 | 1,551 | 8/26/2022 |
4.0.0-rc.1 | 112 | 8/26/2022 |
4.0.0-rc | 374 | 8/15/2022 |
4.0.0-beta | 529 | 5/17/2022 |
4.0.0-alpha | 394 | 5/4/2022 |
3.2.0 | 1,692 | 12/13/2021 |
3.1.1 | 1,477 | 8/29/2021 |
3.1.0 | 1,372 | 8/13/2021 |
3.0.3 | 1,304 | 7/28/2021 |
3.0.2 | 1,396 | 7/1/2021 |
2.0.2 | 1,427 | 6/23/2021 |
2.0.1 | 1,397 | 6/17/2021 |
2.0.0 | 1,364 | 6/16/2021 |
1.3.0 | 1,130 | 5/31/2021 |
1.2.1 | 471 | 5/29/2021 |
1.2.0 | 514 | 5/26/2021 |
1.0.4 | 646 | 5/16/2021 |