PillowSharp 4.0.2
dotnet add package PillowSharp --version 4.0.2
NuGet\Install-Package PillowSharp -Version 4.0.2
<PackageReference Include="PillowSharp" Version="4.0.2" />
paket add PillowSharp --version 4.0.2
#r "nuget: PillowSharp, 4.0.2"
// Install PillowSharp as a Cake Addin
#addin nuget:?package=PillowSharp&version=4.0.2
// Install PillowSharp as a Cake Tool
#tool nuget:?package=PillowSharp&version=4.0.2
Pillowsharp
Content
- Description
- Setup
- Install
- Planned features
- Basic usage
- How to...
- By example:
- Create database
- Create document
- Get documents
- Delete documents
- Attachments
- Design Documents
- UUID
Description
Pillowsharp is a library designed to be used as a client for Apache CouchDB written in .NET Core. The goal is to offer something that can be used out of the box without the need of configuration or a lot of code. Pillowsharp makes use of the async
and await
feature from .NET that allows none blocking requests to the DB.
Setup
To build the library and to run the unit tests, please follow the instructions below:
- Install .Net Core as described here .NET Core
- Install Apache CouchDB
- Add an admin for couch using
curl -X PUT localhost:5984/_config/admins/admin -d '"admin"'
- Clone or download this repository
- Switch into the cloned folder and execute build.bat (Windows) or build.sh
- After the script is completed, you are ready to use the
library/nuget
Please note: If you are using CouchDB 2.X there are some changes to the configure a development enviorment you can use the dev_couch2_setup.sh/bat file. It will configure a single node instance with the default admin used also in the unit tests.
In case you encounter issues in step 5, please check the CouchSettings.cs file if all configurations are correct for your instance of CouchDB. If you still have issues or questions, please open an issue or contact me.
Install
Either you can clone the repository and run the related build script (please see the Setup section) or download a build from nuget.org
Planned features
The following things will be added, or at least I would like to add them:
- Replication end point support
- Replication status check
- Replication conflict support
- Backup and restore of a db (will be in a different tool)
Basic usage
All communication with CouchDB uses the PillowClient class, you can generate a new instance like this:
var client = = new PillowClient(new BasicCouchDBServer("http://127.0.0.1:5984"));
The above example will use anonymous communication with CouchDB (no user required,default CouchDB setup). To use PillowSharp with a login the following client setup would be correct:
var client = new PillowClient(new BasicCouchDBServer("http://127.0.0.1:5984",new CouchLoginData("admin","admin"),ELoginTypes.TokenLogin));
Please note: You need to set the Login type as described here
Example usage for some Pillow functions are located in the example project in the repository.
Model data
Pillow allows you to use any C# class as a model to send and receive from CouchDB. If you would like to make your life a little bit easier inerheit from CouchDocument
. This allows all the communication functions of Pillow to set the ID, Revision and Delete flag automatically.
public class TestDocument : CouchDocument
{
public int Fu { get; set; }
public string Bar { get; set; }
}
If the above module is used for example in an update call, Pillow will update the revsion number inside the object.
All calls accept a parameter to define the database you want to talk to. If you would like to avoid setting this on every call you can also set this as a parameter for your client:
client.ForcedDatabaseName = "pillow";
Another way is to set the database for each model:
[DBName("pillow")]
public class TestDocument : CouchDocument
{
public int Fu { get; set; }
public string Bar { get; set; }
}
It is fine to use all three ways to set the database, Pillow will use them in the following order:
- Caller Parameter
- Class DB, see ForcedDatabaseName
- DBNameAttribute of the current document
Examples
Please also see the example project.
Create a database
if(!await client.DbExists("pillow"))
{
if( await client.CreateNewDatabase("pillow"))
Console.WriteLine("Database pillow created");
}
Create a document
The example below assumes that the Person
class inerheits CouchDocument
and uses the [DBName("pillow")]
attribute. It would also be possible to check the new revision and id in the result object from the call.
person = new Person(){Name="Dev",LastName="Owl",Role="Developer" };
var result = await client.CreateANewDocument(person);
if(result.Ok)
{
Console.WriteLine($"Document created with id:{person.ID} and Rev:{person.Rev}");
}
Get documents
Get a single document by id and optional by revision:
var result = await client.GetDocument<Person>(ID="developer");
Use the all documents endpoint in CouchDB:
await client.GetAllDocuments(Person.GetType());
There are some more ways you can use PillowClient to get a list of documents:
- GetDocuments<T>(string RequestURL)
Delete documents
The example below assumes that the Person
class inerheits CouchDocument
and uses the [DBName("pillow")]
attribute. Important for this call is to send an existing ID to CouchDB.
var result = await client.DeleteDocument(person);
Attachments
The examples below assumes that the Person
class inerheits CouchDocument
and uses the [DBName("pillow")]
attribute.
Upload
Just provide the path to the file you would like to attach to the document.
var result = await client.AddAttachment(person,"fav.image","sleepy_owl.JPG");
Download
The result will be a byte[]
var result = await client.GetAttachement(person,"fav.image");
Delete
var result = await client.DeleteAttachment(person,"fav.image");
Design Documents
Create a document
PillowSharp supports:
- Filters
- Lists
- Views
- Shows
- Updates
var designDoc = new CouchDesignDocument();
designDoc.ID="testDesignDoc";
designDoc.AddView("test","function (doc) {emit(doc._id, 1);}");
designDoc.AddView("testReduce","function (doc) {emit(doc._id, 1);}","_count");
var result = await client.UpsertDesignDocument(designDoc);
Get a design document
var dbDocument = await client.GetDesignDocument(ID);
Run a view
var result = await client.GetView<dynamic>(ID,"viewname",new[] {new KeyValuePair<string, object>("reduce","false")});
UUID
You can ask CouchDB to generate IDs for you, the PillowSharp Client can auto generate IDs for new documents. All can be configured inside PillowClientSettings
default settings are:
public class PillowClientSettings
{
public bool AutoGenerateID { get; set; } = true;
public bool UseCouchUUID { get; set; } = false;
public bool IgnoreJSONNull { get; set; } = true;
}
To generate CouchDB UUID's you can use the follwing call:
var uuidResponse = await client.GetManyUUIDs(AmountOfUUIDs:10);
foreach(var id in uuidResponse.UUIDS){
Console.WriteLine(id);
}
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
- Newtonsoft.Json (>= 13.0.3)
- RestSharp (>= 110.2.0)
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 |
---|---|---|
4.0.2 | 116 | 3/24/2024 |
4.0.1 | 120 | 2/25/2024 |
4.0.0 | 80 | 2/17/2024 |
3.0.6 | 769 | 11/24/2020 |
3.0.5 | 364 | 10/28/2020 |
3.0.4 | 418 | 7/17/2020 |
3.0.3 | 629 | 3/31/2019 |
3.0.1 | 529 | 3/3/2019 |
3.0.0 | 497 | 3/2/2019 |
2.0.2 | 625 | 1/10/2019 |
2.0.1 | 628 | 11/6/2018 |
2.0.0 | 639 | 11/5/2018 |
1.0.6 | 766 | 7/19/2018 |
1.0.5 | 904 | 5/30/2018 |
1.0.0 | 931 | 4/29/2018 |
V4.X Major featuers:
- Upgraded all used nugets to latest stable
- Support for RestSharp 107+
- Moved test and example to NET8.0
Path 0.1:
- Fix Mango query generation due to NewtonsoftJson chnage
Patch 0.2:
- Allow null in SimpleSelector for Mango query