Merge pull request #679 from markashleybell/master

Update README with documentation for [ExplicitKey] attribute

Dapper.Contrib/Readme.md

@@ -21,15 +21,21 @@ bool DeleteAll<T>();
 ```
 
 For these extensions to work, the entity in question _MUST_ have a
-key-property, a property named "`id`" or decorated with a `[Key]` attribute.
+key property. Dapper will automatically use a property named "`id`" 
+(case-insensitive) as the key property, if one is present.
 
 ```csharp
 public class Car
 {
-    public int Id { get; set; }
+    public int Id { get; set; } // Works by convention
     public string Name { get; set; }
 }
+```
+
+If the entity doesn't follow this convention, decorate 
+a specific property with a `[Key]` or `[ExplicitKey]` attribute.
 
+```csharp
 public class User
 {
     [Key]
@@ -39,6 +45,9 @@ public class User
 }
 ```
 
+`[Key]` should be used for database-generated keys (e.g. autoincrement columns), 
+while `[ExplicitKey]` should be used for explicit keys generated in code.
+
 `Get` methods
 -------
 
@@ -111,15 +120,35 @@ Dapper.Contrib makes use of some optional attributes:
 
 * `[Table("Tablename")]` - use another table name instead of the name of the class
 
-	```csharp
+    ```csharp
     [Table ("emps")]
     public class Employee
     {
-    	public int Id { get; set; }
+        public int Id { get; set; }
+        public string Name { get; set; }
+    }
+    ```
+* `[Key]` - this property represents a database-generated identity/key
+    
+    ```csharp
+    public class Employee
+    {
+        [Key]
+        public int EmployeeId { get; set; }
+        public string Name { get; set; }
+    }
+    ```
+* `[ExplicitKey]` - this property represents an explicit identity/key which is 
+  *not* automatically generated by the database 
+
+    ```csharp
+    public class Employee
+    {
+        [ExplicitKey]
+        public Guid EmployeeId { get; set; }
         public string Name { get; set; }
     }
     ```
-* `[Key]` - this property is the identity/key (unless it is named "Id")
 * `[Write(true/false)]` -  this property is (not) writeable
 * `[Computed]` - this property is computed and should not be part of updates
 
@@ -133,11 +162,11 @@ extension provided by Dapper.Contrib. There are 2 ways to deal with this.
 
 1. Call the `Update` method explicitly from `SqlMapperExtensions`
 
-	```Csharp
+    ```Csharp
     SqlMapperExtensions.Update(_conn, new Employee { Id = 1, Name = "Mercedes" });
     ```
 2. Make the method signature unique by passing a type parameter to `Update`
 
-	```Csharp
+    ```Csharp
     connection.Update<Car>(new Car() { Id = 1, Name = "Maruti" });
     ```