Couchbase.Lite.Mapping 1.0.4

A simple component that extends Couchbase.Lite to provide extension methods for converting an object to a Document/MutableDocument and a Document/MutableDocument to an object. This package is not officially supported by Couchbase Inc.

There is a newer version of this package available.
See the version list below for details.
Install-Package Couchbase.Lite.Mapping -Version 1.0.4
dotnet add package Couchbase.Lite.Mapping --version 1.0.4
<PackageReference Include="Couchbase.Lite.Mapping" Version="1.0.4" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Couchbase.Lite.Mapping --version 1.0.4
The NuGet Team does not provide support for this client. Please contact its maintainers for support.

This is an independent, open source couchbaselabs project, and is NOT officially supported by Couchbase, Inc.

Couchbase.Lite.Mapping

Couchbase.Lite.Mapping gives developers the ability to dynamically automatically convert generic objects to/from Couchbase Document objects and lists of Result objects. This drastically reduces the amount of, often repeated, code needed to be written to store and retrieve information to and from Couchbase Lite databases.

Gitter chat

Getting Started

NOTE:
As of version 1.0.2, in order to use Couchbase.Lite.Mapping you must have either the Couchbase.Lite or Couchbase.Lite.Enterprise package installed.

Couchbase.Lite.Mapping does not include dependencies so that it can work with both Couchbase.Lite and Couchbase.Lite.Enterprise. This also provides the flexibility to install any compatible version of Couchbase.lite.

Couchbase.Lite.Mapping is available via:

  • NuGet Official Releases: GitHub release

Build (optional) <a name="build"></a>

If you would like to build the package from source instead, follow the steps below

  • Clone the repo
git clone https://github.com/couchbaselabs/Couchbase.Lite.Mapping
  • Build the release version of project using Visual Studio
  • Build the package
cd /path/to/repo/src/Couchbase.Lite.Mapping/packaging/nuget

nuget pack Couchbase.Lite.Mapping.nuspec

Documentation

To get started using Couchbase.Lite or Couchbase.Lite.Enterprise please refer to the official documentation.

Basic Usage: Object/Document

// An object to be converted to a document
public class Person
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
}

// Create an instance of the object
var person = new Person
{
    FirstName = "Clark",
    LastName = "Kent"
};

// Convert the object into a Couchbase.Lite MutableDocument
var mutableDocument = person.ToMutableDocument();

// Convert a Couchbase.Lite MutableDocument into an object (of a type specified via generic)
var newPerson = mutableDocument.ToObject<Person>();

Basic Usage: IResultSet to IEnumerable of Object

var query = QueryBuilder.Select(SelectResult.All()) 
                                        .From(DataSource.Database(database)) 
                                        .Where(whereQueryExpression); 

var results = query?.Execute()?.AllResults();

// Where 'people' is the containing Dictionary key (see in default approach above)
var personList = results?.ToObjects<Person>("people"); 

Customizing Property Name Serialization

The default serialization for object property names into Couchbase Lite databases uses Lower Camel Case (e.g. lowerCamelCase).

By default the following object

var person = new Person
{
    FirstName = "Bruce",
    LastName = "Wayne"
};

will look like the following in JSON.

{
    "firstName": "Bruce",
    "lastName": "Wayne"
}

Note the casing of firstName and lastName.

Globally

You can override the default implementation of IPropertyNameConverter by setting Couchbase.Lite.Mapping.Setting.PropertyNameConverter.

using Couchbase.Lite.Mapping;
...

// Set this value to override the default IPropertyNameConverter
Settings.PropertyNameConverter = new CustomPropertyNameConverter();

// Here's an example of a custom implementation of IPropertyNameConverter
public class CustomPropertyNameConverter : IPropertyNameConverter
{
    public string Convert(string propertyName)
    {
      return propertyName.ToUpper();
    }
}

Using CustomerPropertyNameConverter will yield the following JSON seralization for Person.

{
    "FIRSTNAME": "Bruce",
    "LASTNAME": "Wayne"
}
By Document

You can override the default implementation of IPropertyNameConverter at the document level by passing in an instance of a class that implements IPropertyNameConverter into the ToMutableDocument extension method.

var mutableDocument = testObject.ToMutableDocument(new CustomPropertyNameConverter());
By Property

You can override the default implementation of IPropertyNameConverter at the property level by adding a MappingPropertyName attribute above a property.

using Couchbase.Lite.Mapping;

public class Person
{
    [MappingPropertyName("fIRStNaME")]
    public string FirstName { get; set; }

    // This property will be converted using the default converter
    public string LastName { get; set; }
}

Using MappingPropertyName (like above) will yield the following JSON seralization for Person.

{
    "fIRStNaME": "Diana",
    "lastName": "Prince"
}

Testing

Sample App

A sample Xamarin.Forms solution (supporting iOS and Android) can be found within Samples. Simply clone this repo, open Couchbase.Lite.Mapping.Sample.sln, and build/run the application!

The sample app allows users to log in with any username and password, and maintains a user profile per username. Profiles consist of basic information and an image that is persisted as a user profile Document in the Couchbase Lite database for a "logged in" user.

<p>
<img src="images/login.png" width="200" title="hover text" style="margin-right:25px;" border="3px">
<img src="images/profile.png" width="200" alt="accessibility text" border="5px">
</p>

Contributors

Couchbase.Lite.Mapping is an open source project and community contributions are welcome whether they be pull-requests, feedback or filing bug tickets or feature requests.

Please include appropriate unit tests with pull-requests.

We appreciate any contribution no matter how big or small!

Licenses

The mapping package is available under
License

Note::
Use of Couchbase.Lite.Mapping has no implications on the Couchbase.Lite.Enterprise or Couchbase.Lite licenses. Those packages are governed by the terms of the Couchbase Enterprise Edition and Community Edition licenses respectively

This is an independent, open source couchbaselabs project, and is NOT officially supported by Couchbase, Inc.

Couchbase.Lite.Mapping

Couchbase.Lite.Mapping gives developers the ability to dynamically automatically convert generic objects to/from Couchbase Document objects and lists of Result objects. This drastically reduces the amount of, often repeated, code needed to be written to store and retrieve information to and from Couchbase Lite databases.

Gitter chat

Getting Started

NOTE:
As of version 1.0.2, in order to use Couchbase.Lite.Mapping you must have either the Couchbase.Lite or Couchbase.Lite.Enterprise package installed.

Couchbase.Lite.Mapping does not include dependencies so that it can work with both Couchbase.Lite and Couchbase.Lite.Enterprise. This also provides the flexibility to install any compatible version of Couchbase.lite.

Couchbase.Lite.Mapping is available via:

  • NuGet Official Releases: GitHub release

Build (optional) <a name="build"></a>

If you would like to build the package from source instead, follow the steps below

  • Clone the repo
git clone https://github.com/couchbaselabs/Couchbase.Lite.Mapping
  • Build the release version of project using Visual Studio
  • Build the package
cd /path/to/repo/src/Couchbase.Lite.Mapping/packaging/nuget

nuget pack Couchbase.Lite.Mapping.nuspec

Documentation

To get started using Couchbase.Lite or Couchbase.Lite.Enterprise please refer to the official documentation.

Basic Usage: Object/Document

// An object to be converted to a document
public class Person
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
}

// Create an instance of the object
var person = new Person
{
    FirstName = "Clark",
    LastName = "Kent"
};

// Convert the object into a Couchbase.Lite MutableDocument
var mutableDocument = person.ToMutableDocument();

// Convert a Couchbase.Lite MutableDocument into an object (of a type specified via generic)
var newPerson = mutableDocument.ToObject<Person>();

Basic Usage: IResultSet to IEnumerable of Object

var query = QueryBuilder.Select(SelectResult.All()) 
                                        .From(DataSource.Database(database)) 
                                        .Where(whereQueryExpression); 

var results = query?.Execute()?.AllResults();

// Where 'people' is the containing Dictionary key (see in default approach above)
var personList = results?.ToObjects<Person>("people"); 

Customizing Property Name Serialization

The default serialization for object property names into Couchbase Lite databases uses Lower Camel Case (e.g. lowerCamelCase).

By default the following object

var person = new Person
{
    FirstName = "Bruce",
    LastName = "Wayne"
};

will look like the following in JSON.

{
    "firstName": "Bruce",
    "lastName": "Wayne"
}

Note the casing of firstName and lastName.

Globally

You can override the default implementation of IPropertyNameConverter by setting Couchbase.Lite.Mapping.Setting.PropertyNameConverter.

using Couchbase.Lite.Mapping;
...

// Set this value to override the default IPropertyNameConverter
Settings.PropertyNameConverter = new CustomPropertyNameConverter();

// Here's an example of a custom implementation of IPropertyNameConverter
public class CustomPropertyNameConverter : IPropertyNameConverter
{
    public string Convert(string propertyName)
    {
      return propertyName.ToUpper();
    }
}

Using CustomerPropertyNameConverter will yield the following JSON seralization for Person.

{
    "FIRSTNAME": "Bruce",
    "LASTNAME": "Wayne"
}
By Document

You can override the default implementation of IPropertyNameConverter at the document level by passing in an instance of a class that implements IPropertyNameConverter into the ToMutableDocument extension method.

var mutableDocument = testObject.ToMutableDocument(new CustomPropertyNameConverter());
By Property

You can override the default implementation of IPropertyNameConverter at the property level by adding a MappingPropertyName attribute above a property.

using Couchbase.Lite.Mapping;

public class Person
{
    [MappingPropertyName("fIRStNaME")]
    public string FirstName { get; set; }

    // This property will be converted using the default converter
    public string LastName { get; set; }
}

Using MappingPropertyName (like above) will yield the following JSON seralization for Person.

{
    "fIRStNaME": "Diana",
    "lastName": "Prince"
}

Testing

Sample App

A sample Xamarin.Forms solution (supporting iOS and Android) can be found within Samples. Simply clone this repo, open Couchbase.Lite.Mapping.Sample.sln, and build/run the application!

The sample app allows users to log in with any username and password, and maintains a user profile per username. Profiles consist of basic information and an image that is persisted as a user profile Document in the Couchbase Lite database for a "logged in" user.

<p>
<img src="images/login.png" width="200" title="hover text" style="margin-right:25px;" border="3px">
<img src="images/profile.png" width="200" alt="accessibility text" border="5px">
</p>

Contributors

Couchbase.Lite.Mapping is an open source project and community contributions are welcome whether they be pull-requests, feedback or filing bug tickets or feature requests.

Please include appropriate unit tests with pull-requests.

We appreciate any contribution no matter how big or small!

Licenses

The mapping package is available under
License

Note::
Use of Couchbase.Lite.Mapping has no implications on the Couchbase.Lite.Enterprise or Couchbase.Lite licenses. Those packages are governed by the terms of the Couchbase Enterprise Edition and Community Edition licenses respectively

Release Notes

Added support for Result collection to Object collection conversion.

Dependencies

This package has no dependencies.

This package is not used by any popular GitHub repositories.

Version History

Version Downloads Last updated
1.1.0 160 12/20/2019
1.0.8 167 9/24/2019
1.0.7 72 9/23/2019
1.0.7-alpha 69 9/17/2019
1.0.6 211 7/1/2019
1.0.5 143 7/1/2019
1.0.4 230 5/13/2019
1.0.3 154 4/11/2019
1.0.2 156 3/15/2019
1.0.1 128 3/9/2019
1.0.0 139 3/9/2019
Show less