Couchbase.Lite.Mapping 1.0.4

The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org. Prefix Reserved
There is a newer version of this package available.
See the version list below for details.
dotnet add package Couchbase.Lite.Mapping --version 1.0.4
NuGet\Install-Package Couchbase.Lite.Mapping -Version 1.0.4
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<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
#r "nuget: Couchbase.Lite.Mapping, 1.0.4"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Couchbase.Lite.Mapping as a Cake Addin
#addin nuget:?package=Couchbase.Lite.Mapping&version=1.0.4

// Install Couchbase.Lite.Mapping as a Cake Tool
#tool nuget:?package=Couchbase.Lite.Mapping&version=1.0.4

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

Product 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. 
Compatible target framework(s)
Additional computed target framework(s)
Learn more about Target Frameworks and .NET Standard.

This package has no dependencies.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.1.0 337,904 12/20/2019
1.0.8 691 9/24/2019
1.0.7 491 9/23/2019
1.0.7-alpha 375 9/17/2019
1.0.6 684 7/1/2019
1.0.5 2,840 7/1/2019
1.0.4 650 5/13/2019
1.0.3 598 4/11/2019
1.0.2 594 3/15/2019
1.0.1 550 3/9/2019
1.0.0 594 3/9/2019

Added support for Result collection to Object collection conversion.