TableStorage.Abstractions.TableEntityConverters
2.0.3
dotnet add package TableStorage.Abstractions.TableEntityConverters --version 2.0.3
NuGet\Install-Package TableStorage.Abstractions.TableEntityConverters -Version 2.0.3
<PackageReference Include="TableStorage.Abstractions.TableEntityConverters" Version="2.0.3" />
paket add TableStorage.Abstractions.TableEntityConverters --version 2.0.3
#r "nuget: TableStorage.Abstractions.TableEntityConverters, 2.0.3"
// Install TableStorage.Abstractions.TableEntityConverters as a Cake Addin #addin nuget:?package=TableStorage.Abstractions.TableEntityConverters&version=2.0.3 // Install TableStorage.Abstractions.TableEntityConverters as a Cake Tool #tool nuget:?package=TableStorage.Abstractions.TableEntityConverters&version=2.0.3
TableStorage.Abstractions.TableEntityConverters
Easily convert POCOs (Plain Old CLR Objects) to Azure Table Storage TableEntities and vice versa
The Azure Storage SDK requires that objects that it works with to implement the ITableEntity interface. This puts us into one of two places that are often not desirable:
- You implement the ITableEntity interace, or inherit from TableEntity. This is easy, but now you've got a leaky abstraction, as well as properties that won't make much sense in your domain (e.g. instead of a UserId, you've now got a RowKey, of the wrong type), or you have fields that are out of place, like ETag and Timestamp.
- You create DTOs to save to ship data back and forth from the domain to Table Storage. This is a common style, but often is overkill, especially if we're just looking for a simple abstraction on top of Azure Table Storage.
This simple library seeks to take care of the mapping for us, so that you can continue to write your domain objects as POCOs, while still being able to leverage the Azure Storage SDK.
The library will convert simple properties to fields in Azure Table Storage. Complex types will serialize as json.
‼️ Important Note About Versioning
TableStorage.Abstractions.TableEntityConverters
uses semantic versioning. Anything changes to a major release should not be breaking, e.g. upgrading to 1.5 from 1.4 should not require a code change.
The upgrade from 1.5 to 2.0 does not introduce changes needed in your use of TableStorage.Abstractions.TableEntityConverters
, however the underlying table storage SDK is now using the newer Azure.Data.Tables instead of the older Microsoft.Azure.Cosmos.Table SDK.
If you directly use Microsoft's Table Storage SDK, you will need to use Azure.Data.Tables
. It should not require much change, but nevertheless it is a change. If you do not want to upgrade at this time, stick with TableStorage.Abstractions.TableEntityConverters
1.5.
Examples
We'll use the following two classes for our examples
public class Department
{
public int Id { get; set; }
public string Name { get; set; }
public Guid? OptionalId { get; set; }
}
public class Employee
{
public string Company { get; set; }
public int Id { get; set; }
public Guid ExternalId { get; set; }
public string Name { get; set; }
public DateTimeOffset HireDate { get; set; }
public DateTimeOffset? TermDate { get; set; }
public Department Department { get; set; }
}
Convert To Table Entity
Converting to a table entity is easy. Use the .ToTableEntity()
extension method and specify which properties represent the partition key and row key. If you need to customize how any of those two keys serialize there are overloads that accept string values.
Example:
var emp = new Employee()
{
Company = "Microsoft",
Name = "John Smith",
Department = new Department
{
Name = "QA",
Id = 1,
OptionalId = null
},
Id = 42,
ExternalId = Guid.Parse("e3bf64f4-0537-495c-b3bf-148259d7ed36"),
HireDate = DateTimeOffset.Parse("Thursday, January 31, 2008")
};
var tableEntity = emp.ToTableEntity(e => e.Company, e => e.Id);
Below is an example that uses string keys instead:
var emp = new Employee()
{
Name = "John Smith",
Department = new Department
{
Name = "QA",
Id = 1,
OptionalId = null
},
ExternalId = Guid.Parse("e3bf64f4-0537-495c-b3bf-148259d7ed36"),
HireDate = DateTimeOffset.Parse("Thursday, January 31, 2008")
};
var tableEntity = emp.ToTableEntity("Google", "42");
Ignoring Properties When Converting To Table Entity
When converting your POCO to a table entity and ultimately serializing and persisting to Azure Table Storage, you may want to ignore some fields. To ignore properties, use the optional ignoredProperties
parameter.
Example:
var tableEntity = emp.ToTableEntity(e=>e.Company, e=>e.Id, e=>e.ExternalId, e=>e.HireDate);
In the above example the partition key is Company
, the row key is Id
and we ignored ExternalId
and HireDate
.
Convert From Table Entity
Converting from a table entity is just as simple. If the both the partition keys can be converted to simple types, you can use the shorter overloaded extension method (FromTableEntity
).
Here is a simple example where we specify the partition key (Company
) and the row key (Id
):
var employee = tableEntity.FromTableEntity<Employee, string, int>(e => e.Company, e => e.Id);
Here is an example where a more complicated key was used, which is common in azure table storage because of the lack of indexes.
var employee = tableEntity.FromTableEntity<Employee, string, int>(e=>e.Company, pk=>pk.Substring("company_".Length), e => e.Id, rk=>int.Parse(rk.Substring("employee_".Length)));
In this example the partitionkey had a prefix of "company_" and the row key had a prefix of "employee_".
Converting From Table Entity While Ignoring Key Properties (Partition Key and Row Key)
When converting from a table entity, you may not want to populate any fields derived from PartitionKey
and RowKey
. One reason for doing this might be that those keys are complex (derived from multiple properties for instance), and you already have those simple properties in your entity.
For your conveninece you can use the simplified FromTableEntity
method. This is the equivilant of doing
var employee = tableEntity.FromTableEntity<Employee,object,object>(null, null, null, null);
Example:
var employee = tableEntity.FromTableEntity<Employee>();
Custom Json Serialization Settings For Complex Types
Beginning with v1.4, you can now control how the json for complex types are serialized/deserialized.
To set the settings globally, use SetDefaultJsonSerializerSettings
. Use this option if you want to apply them to all table entity conversions.
The other option is pass in the settingds in the newly overloaded ToTableEntity
and FromTableEntity
methods.
Custom Property Conversion For Non-Key Fields
Starting in 1.5 you can specify custom property converters for properties that are not used as Partition or Row Key fields.
This is a niche use case, but useful if you need it, for example, if dates are stored as strings in Azure Table Storage.
Here is the object we'll be using in the example:
var car = new Car {
Id = "abc",
Make = "BMW",
Model = "M5",
Year = 2022,
ReleaseDate = new DateTime(2022, 3, 1)
};
First we need to specify property converters. PropertyConverters
is a dictionary. The key is the
property name and the value is a PropertyConverter
, which specifies how to convert to and from EntityProperty
.
var propertyConverters = new PropertyConverters<Car> {
[nameof(Car.ReleaseDate)] =
new PropertyConverter<Car>(x =>
car.ReleaseDate.ToString("yyyy-M-d"),
(c,p) => c.ReleaseDate = p.ToString())
)
};
Finally, pass the PropertyConverters
object when converting to and from your table entities.
Note that in production use cases you don't have to always instantiate your property converters, you should have a single instance and re-use.
var jsonSerializerSettings = new JsonSerializerSettings();
var carEntity =
car.ToTableEntity(c => c.Year, c => car.Id, jsonSerializerSettings, propertyConverters);
var fromEntity = carEntity.FromTableEntity<Car,int,string>(c=>c.Year, c=>c.Id, jsonSerializerSettings, propertyConverters);
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. 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 was computed. |
.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.8.1)
- Newtonsoft.Json (>= 13.0.3)
NuGet packages (2)
Showing the top 2 NuGet packages that depend on TableStorage.Abstractions.TableEntityConverters:
Package | Downloads |
---|---|
TableStorage.Abstractions.POCO
A repository wrapper for Azure Table Storage that uses POCOs (Plain Old CLR Objects) instead of objects that implemeent ITableEntity. The Azure Storage SDK requires that objects that it works with to implement the ITableEntity interface. This puts us into one of two places that are often not desirable: You implement the ITableEntity interace, or inherit from TableEntity. This is easy, but now you've got a leaky abstraction, as well as properties that won't make much sense in your domain (e.g. instead of a UserId, you've now got a RowKey, of the wrong type), or you have fields that are out of place, like ETag and Timestamp. You create DTOs to save to ship data back and forth from the domain to Table Storage. This is a common style, but often is overkill, especially if we're just looking for a simple abstraction on top of Azure Table Storage. This simple library seeks to take care of the mapping for us, so that you can continue to write your domain objects as POCOs, while still being able to leverage the Azure Storage SDK. The library will convert simple properties to fields in Azure Table Storage. Complex types will serialize as json. |
|
TableStorage.Abstractions.Trie
An implementation of a trie-like data structure using Azure Table Storage to enable type-ahead style searching. Targets netcoreapp2.1, netstandard2.0 and net461. |
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
2.0.3 | 8,350 | 8/29/2023 |
2.0.1 | 11,609 | 4/2/2022 |
2.0.0 | 13,582 | 1/23/2022 |
1.6.0-beta | 8,656 | 1/20/2022 |
1.5.0 | 15,243 | 11/17/2021 |
1.5.0-beta | 1,436 | 11/15/2021 |
1.4.1 | 2,184 | 11/3/2021 |
1.4.0 | 7,058 | 9/30/2021 |
1.3.2 | 1,371 | 6/26/2021 |
1.3.1 | 6,718 | 8/19/2020 |
1.3.0 | 3,715 | 5/11/2020 |
1.3.0-beta | 427 | 5/11/2020 |
1.2.0 | 7,693 | 3/2/2020 |
1.1.8 | 2,563 | 2/25/2020 |
1.1.7 | 3,919 | 2/17/2020 |
1.1.6 | 1,381 | 9/16/2019 |
1.1.5 | 20,581 | 6/18/2019 |
1.1.4 | 8,976 | 12/25/2018 |
1.1.3 | 19,312 | 1/27/2018 |
1.1.2 | 10,565 | 8/31/2017 |
1.1.0 | 1,044 | 8/30/2017 |
1.0.1 | 1,181 | 8/15/2017 |
1.0.0 | 1,207 | 8/14/2017 |
Updated packages