Merge branch 'master' of github.com:dimi3tron/data.dump

README.md

@@ -26,9 +26,117 @@ Special care has been taken to reduce the memory footprint while creating and st
 
 ## How can I use it?
 ### Examples
-Some examples and documentaion will be described here soon. 
+#### Basic usage
+Dumping a list of objects to the database is as easy as:
+```c#
+var repo = new SqlRepository(new SqlStore(ConnectionString));
+var pocos = someService.GetEnumerable<Poco>();
+repo.Save(pocos);
+```
+This code will generate a table called Pocos, with all primitive fields included. Nested objects will be ignored. 
+
+
+To get a reference to the repo object you can also use your favourite flavor of Dependency Injection. Just implement ISqlStore, and it hook up.
+
+#### Mapping nested objects
+To create tables for objects contained within your root collection use:
+```c#
+repo.Save(
+    nested, 
+    Schema.Mapping.Models.Map<NestedPoco>()
+        .SelectModel(x => x) //make sure to pass in the base model as well, or it won't get saved
+        .SelectModel(x => x.Pocos) //select the objects to include
+);
+```
+Notice this method will work on collections of objects as well as on single objects. In the last case a table with only one row will be created.
+
+The above method will just save the data, with no relation between the tables. You can include a foreign key as such:
+```c#
+repo.Save(
+    nested, 
+    Schema.Mapping.Models.Map<NestedPoco>()
+        .SelectModel(x => x)
+        .SelectModel(
+            x => x.Pocos,
+            x => x.Id, // select the field containing the foreign key value 
+            "NestedPocoId" //pass in a name for the key column; this can be a string or 
+                           //a function returning a string.
+                           //if no name is provided one will be generated;  
+        )
+);
+```
+
+#### Mapping complex or deeply nested objects
+To save the data contained deeper in the object tree, you'll need to provide some extra info on where to find the root object to use for foreign key resolution.
+```c#
+repo.Save(
+  deeplyNestedExtended.AsEnumerable(), //make sure to pass in your collections as enumerable 
+  Schema.Mapping.Models.Map<RootPoco>()
+    .SelectModel(x => x)  //root object of type RootPoco
+    .SelectModel(
+        x => x.NestedPocos, //child collection in RootPoco
+        x => x.Id, //foreign key value from RootPoco
+        "RootPocoId"
+    )
+    .SelectNestedModel(
+       x => x.NestedPocos
+            .Select(n => n.DeeplyNestedPocos.WithRoot(n)), //include DeeplyNestedPocos with a NestedPoco root
+       x => x.Id //foreign key value from NestedPoco
+    )
+);
+```
+
+#### Named collections
+Tables names will be autogenerated based on the Clr Type. As tables are overwritten on each save, this may lead to some undesireable effects. To avoid this issue, simply pass in a table name.
+```c#
+repo.Save(first, "FirstCollection"); //as string
+repo.Save(second, () => "SecondCollection"); //or as a function
+```
+
+#### Mapping collections of primitive types
+Currently there is no out of the box support for collections of primitive types. As these contain no valid information to use to create the columns, mapping will fail. Luckily there is an easy workaround:
+```c#
+repo.Save(
+  pocos,
+  Schema.Mapping.Models.Map<Poco>()
+    .SelectModel(
+        x => x.CollectionOfStrings.Select(p => new SingleValue<string>(p)),
+        "PocoStrings" //optional table name always goes as second argument
+        x => x.Id, 
+        "PocoId"
+    )
+);
+```
+```SingleValue``` can be found in the ```Data.Dump.Schema.Mapping``` namespace. In the future this will be taken care of automatically.
+
+#### Mapping dictionaries
+Mapping dictionaries of primitive types will pose no problem, as the contained KeyValuePairs will translate nicely to a table with a Key and Value column. However, to map dictionaries of complex objects, you'll need to do some extra work. Here's an example using AutoMapper:
+```c#
+class DictPoco : Poco
+{
+    public string DictKey { get; set; }
+}
+
+var config = new MapperConfiguration(cfg =>
+{
+    cfg.CreateMap<Poco, DictPoco>();
+});
+var mapper = config.CreateMapper();
+
+repo.Save(
+  pocos,
+  Schema.Mapping.Models.Map<ComplexPoco>()
+    .SelectModel(
+        x => x.DictionaryOfStringPoco.Select(
+            p => mapper.Map(p.Value, new DictPoco { DictKey = p.Key })
+        ),
+        x => x.Id,
+        "ComplexPocoId"
+    )
+);  
+```
 
-For now, please refer to the included sample project.
+Please refer to the included sample project for more examples.
 
 ### Instalation
 ```