New Documentation System powered by MkDocs and ReadTheDocs

.gitignore

@@ -18,4 +18,5 @@ _[Ss]cripts
 *.pdb
 *.mdf
 *.ldf
-.vs
+.vs
+site

docs/clients/dot-net.md

@@ -0,0 +1 @@
+ [THIS IS A PLACEHOLDER FOR FUTURE CONTENT]

docs/contribution-guidelines.md

@@ -0,0 +1,73 @@
+# How Can I Contribute?
+There are many ways for you to contribute to RESTier. The easiest way is to participate in discussion of 
+features and issues. You can also contribute by sending pull requests of features or bug fixes to us. 
+Contribution to the [documentations](http://odata.github.io/RESTier/) is also highly welcomed.
+
+## Discussion
+You can participate into discussions and ask questions about RESTier at our 
+[Github issues](https://github.com/OData/RESTier/issues).
+
+## Bug Reports
+When reporting a bug at the issue tracker, fill the template of issue. The issue related to other libraries 
+should not be reported in RESTier library issue tracker, but be reported to other libraries' issue tracker.
+
+## Pull Requests
+**Pull request is the only way we accept code and document contribution.** Pull request of document, features 
+and bug fixes are both welcomed. Refer to this [link](https://help.github.com/articles/using-pull-requests/) 
+to learn details about pull request. Before you send a pull request to us, you need to make sure you've 
+followed the steps listed below.
+
+### Pick an issue to work on
+You should either create or pick an issue on the [issue tracker](https://github.com/OData/RESTier/issues) 
+before you work on the pull request. After the RESTier team has reviewed this issue and change its label 
+to "accepting pull request", you can work on the code change.
+
+### Prepare Tools
+[Atom](https://atom.io/) with package [atom-beautify](https://atom.io/packages/atom-beautify) and 
+[markdown-toc](https://atom.io/packages/markdown-toc) is recommended to edit the document. 
+[MarkdownPad](http://www.markdownpad.com/) can also be used to edit the document.<br />
+Visual Studio 2015 is recommended for code contribution.
+
+### Steps to create a pull request
+These are the recommended steps to create a pull request:<br />
+
+1. Create a forked repository of [https://github.com/OData/RESTier.git](https://github.com/OData/RESTier.git)
+2. Clone the forked repository into your local environment
+3. Add a git remote to upstream for local repository with command _git remote add upstream 
+[https://github.com/OData/RESTier.git](https://github.com/OData/RESTier.git)_
+4. Make code changes and add test cases, refer Test specification section for more details about test
+5. Test the changed codes with one-click build and test script
+6. Commit changed code to local repository with clear message
+7. Rebase the code to upstream via command _git pull --rebase upstream master_ and resolve conflicts 
+if there is any then continue rebase via command _git pull --rebase continue_
+8. Push local commit to the forked repository
+9. Create pull request from forked repository Web console via comparing with upstream.
+10. Complete a Contributor License Agreement (CLA), refer below section for more details.
+11. Pull request will be reviewed by Microsoft OData team
+12. Address comments and revise code if necessary
+13. Commit the changes to local repository or amend existing commit via command _git commit --amend_
+14. Rebase the code with upstream again via command _git pull --rebase upstream master_ and resolve 
+conflicts if there is any then continue rebase via command _git pull --rebase continue_
+15. Test the changed codes with one-click build and test script again
+16. Push changes to the forked repository and use _--force_ option if existing commit is amended
+17. Microsoft OData team will merge the pull request into upstream
+
+### Test specification
+All tests need to be written with xUnit. Here are some rules to follow when you are organizing the 
+test code:
+
+- **Project name correspondence** (`X -> X.Tests`). For instance, all the test code of the `Microsoft.Restier.Core` project should be placed in the `Microsoft.Restier.Core.Tests` project. Path and file name correspondence. (`X/Y/Z/A.cs -> X.Tests/Y/Z/ATests.cs`). For example, the test code of the `ConventionBasedApiModelBuilder` class (in the `Microsoft.Restier.Core/Convention/ConventionBasedApiModelBuilder.cs` file) should be placed in the `Microsoft.Restier.Core.Tests/Convention/ConventionBasedApiModelBuilderTests.cs` file.
+- **Namespace correspondence** (`X.Tests/Y/Z -> X.Tests.Y.Z`). The namespace of the file should strictly follow the path. For example, the namespace of the `ConventionBasedApiModelBuilderTests.cs` file should be `Microsoft.Restier.Core.Tests.Convention`.
+- **Utility classes**. The file for a utility class can be placed at the same level of its user or a shared level that is visible to all its users. But the file name must **NOT** be ended with `Tests` to avoid any confusion.
+- **Integration and scenario tests**. Those tests usually involve multiple modules and have some specific scenarios. They should be placed separately in `X.Tests/IntegrationTests` and `X.Tests/ScenarioTests`. There is no hard requirement of the folder structure for those tests. But they should be organized logically and systematically as possible. 
+
+### Complete a Contribution License Agreement (CLA)
+You will need to complete a Contributor License Agreement (CLA). Briefly, this agreement testifies 
+that you are granting us permission to use the submitted change according to the terms of the 
+project's license, and that the work being submitted is under appropriate copyright.
+
+Please submit a Contributor License Agreement (CLA) before submitting a pull request. 
+[Download the agreement](https://github.com/odata/odatacpp/wiki/files/Microsoft Contribution License Agreement.pdf)), 
+sign, scan, and email it back to [[email protected]](mailto:[email protected]). Be sure to include your Github 
+user name along with the agreement. Only after we have received the signed CLA, we'll review the pull request that 
+you send. You only need to do this once for contributing to any Microsoft open source projects.

docs/extending-restier/additional-operations.md

@@ -0,0 +1,69 @@
+## Additional WebAPI Operations
+
+RESTier is built on top of ASP.NET Web API, so like our regular OData support, augmenting your service
+with additional actions is very simple.
+
+First, you must add the action to the EDM Model Builder.
+
+Currently RESTier can not route an operation request to a method defined in API class for operation model 
+building, user need to define its own controller with ODataRoute attribute for operation route.
+
+Operation includes function (bounded), function import (unbounded), action (bounded), and action(unbounded). 
+
+For function and action, the ODataRoute attribute must include namespace information. There is a way to simplify 
+the URL to omit the namespace, user can enable this via call "config.EnableUnqualifiedNameCall(true);" during registering.
+
+For function import and action import, the ODataRoute attribute must NOT include namespace information.
+
+RESTier also supports operation request in batch request, as long as user defines its own controller for operation route.
+
+This is an example on how to define customized controller with ODataRoute attribute for operation.
+
+```cs
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Net;
+using System.Web.Http;
+using System.Web.OData;
+using System.Web.OData.Extensions;
+using System.Web.OData.Routing;
+using Microsoft.OData.Edm.Library;
+using Microsoft.OData.Service.Sample.Trippin.Api;
+using Microsoft.OData.Service.Sample.Trippin.Models;
+
+namespace Microsoft.OData.Service.Sample.Trippin.Controllers
+{
+    public class TrippinController : ODataController
+    {        
+        private TrippinApi Api
+        {
+            get
+            {
+                if (api == null)
+                {
+                    api = new TrippinApi();
+                }
+
+                return api;
+            }
+        }
+        ...
+        // Unbounded action does not need namespace in route attribute
+        [ODataRoute("ResetDataSource")]
+        public IHttpActionResult ResetDataSource()
+        {
+            // reset the data source;
+            return StatusCode(HttpStatusCode.NoContent);
+        }
+
+        [ODataRoute("Trips({key})/Microsoft.OData.Service.Sample.Trippin.Models.EndTrip")]
+        public IHttpActionResult EndTrip(int key)
+        {
+            var trip = DbContext.Trips.SingleOrDefault(t => t.TripId == key);
+            return Ok(Api.EndTrip(trip));
+        }
+        ...
+    }
+}
+```

docs/extending-restier/in-memory-provider.md

@@ -0,0 +1,84 @@
+## In-Memory Data Provider
+
+RESTier supports building an OData service with **all-in-memory** resources. However currently RESTier 
+has not provided a dedicated in-memory provider module so users have to write some service code to bootstrap 
+the initial model with EDM types themselves. There is a sample service with in-memory provider [here](https://github.com/OData/RESTier/tree/apidev/test/ODataEndToEndTests/Microsoft.OData.Service.Sample.TrippinInMemory). 
+This subsection mainly talks about how such a service is created.
+
+First please create an **Empty ASP.NET Web API** project following the instructions in [Section 1.2](http://odata.github.io/RESTier/#01-02-Bootstrap). Stop **BEFORE** the **Generate the model classes** part.
+
+### Create the Api class
+Create a simple data type `Person` with some properties and "fabricate" some fake data. Then add the first entity set `People` to the `Api` class:
+
+    using System.Collections.Generic;
+    using System.Collections.ObjectModel;
+    using System.Linq;
+    using System.Threading;
+    using System.Threading.Tasks;
+    using System.Web.OData.Builder;
+    using Microsoft.OData.Edm;
+    using Microsoft.Restier.Core;
+    using Microsoft.Restier.Core.Model;
+
+    namespace Microsoft.OData.Service.Sample.TrippinInMemory
+    {
+        public class TrippinApi : ApiBase
+        {
+            private static readonly List<Person> people = new List<Person>
+            {
+                ...
+            };
+
+            public IQueryable<Person> People
+            {
+                get { return people.AsQueryable(); }
+            }
+        }
+    }
+
+### Create an initial model
+Since the RESTier convention will not produce any EDM type, an initial model with at least the `Person` type needs to be created by service. Here the `ODataConventionModelBuilder` from OData Web API is used for quick model building.
+Any model building methods supported by Web API OData can be used here, refer to **[Web API OData Model builder ](http://odata.github.io/WebApi/#02-01-model-builder-abstract)**document for more information.
+
+    namespace Microsoft.OData.Service.Sample.TrippinInMemory
+    {
+        public class TrippinApi : ApiBase
+        {
+            protected override IServiceCollection ConfigureApi(IServiceCollection services)
+            {
+                services.AddService<IModelBuilder>(new ModelBuilder());
+                return base.ConfigureApi(services);
+            }
+
+            private class ModelBuilder : IModelBuilder
+            {
+                public Task<IEdmModel> GetModelAsync(InvocationContext context, CancellationToken cancellationToken)
+                {
+                    var builder = new ODataConventionModelBuilder();
+                    builder.EntityType<Person>();
+                    return Task.FromResult(builder.GetEdmModel());
+                }
+            }
+        }
+    }
+
+### Configure the OData endpoint
+Replace the `WebApiConfig` class with the following code. No need to create a custom controller if users don't have attribute routing.
+
+    using System.Web.Http;
+    using Microsoft.Restier.Publisher.OData.Batch;
+
+    namespace Microsoft.OData.Service.Sample.TrippinInMemory
+    {
+        public static class WebApiConfig
+        {
+            public static void Register(HttpConfiguration config)
+            {
+                config.MapRestierRoute<TrippinApi>(
+                    "TrippinApi",
+                    "api/Trippin",
+                    new RestierBatchHandler(GlobalConfiguration.DefaultServer)).Wait();
+            }
+        }
+    }
+

docs/extending-restier/temporal-types.md

@@ -0,0 +1,77 @@
+# Temporal Types
+
+When using the Microsoft.Restier.Providers.EntityFramework provider, temporal types are now supported. The table below 
+shows how Temporal Types map to SQL Types:
+
+|        EF Type        |      SQL Type      |      Edm Type      | Need ColumnAttribute? |
+|:---------------------:|:------------------:|:------------------:|:---------------------:|
+| System.DateTime       | DateTime/DateTime2 | Edm.DateTimeOffset | Y                     |
+| System.DateTimeOffset | DateTimeOffset     | Edm.DateTimeOffset | N                     |
+| System.DateTime       | Date               | Edm.Date           | Y                     |
+| System.TimeSpan       | Time               | Edm.TimeOfDay      | Y                     |
+| System.TimeSpan       | Time               | Edm.Duration       | N                     |
+
+The next sections illustrate how to use use temporal types in various scenarios.
+
+## Edm.DateTimeOffset
+Suppose you have an entity class `Person`, all the following code define `Edm.DateTimeOffset` properties in the 
+EDM model though the underlying SQL types are different (see the value of the `TypeName` property). You can see 
+Column attribute is optional here.
+
+
+    using System;
+    using System.ComponentModel.DataAnnotations.Schema;
+
+    public class Person
+    {
+        public DateTime BirthDateTime1 { get; set; }
+
+        [Column(TypeName = "DateTime")]
+        public DateTime BirthDateTime2 { get; set; }
+
+        [Column(TypeName = "DateTime2")]
+        public DateTime BirthDateTime3 { get; set; }
+
+        public DateTimeOffset BirthDateTime4 { get; set; }
+    }
+
+
+## Edm.Date
+The following code define an `Edm.Date` property in the EDM model.
+
+    using System;
+    using System.ComponentModel.DataAnnotations.Schema;
+
+    public class Person
+    {
+        [Column(TypeName = "Date")]
+        public DateTime BirthDate { get; set; }
+    }
+
+## Edm.Duration
+The following code define an `Edm.Duration` property in the EDM model.
+
+    using System;
+    using System.ComponentModel.DataAnnotations.Schema;
+
+    public class Person
+    {
+        public TimeSpan WorkingHours { get; set; }
+    }
+
+## Edm.TimeOfDay
+The following code define an `Edm.TimeOfDay` property in the EDM model. Please note that you MUST NOT omit the 
+`ColumnTypeAttribute` on a `TimeSpan` property otherwise it will be recognized as an `Edm.Duration` as described above.
+
+    using System;
+    using System.ComponentModel.DataAnnotations.Schema;
+
+    public class Person
+    {
+        [Column(TypeName = "Time")]
+        public TimeSpan BirthTime { get; set; }
+    }
+
+As before, if you have the need to override `ODataPayloadValueConverter`, please now change to override 
+`RestierPayloadValueConverter` instead in order not to break the payload value conversion specialized for these 
+temporal types.

docs/getting-started.md

@@ -0,0 +1,17 @@
+# Welcome to MkDocs
+
+For full documentation visit [mkdocs.org](http://mkdocs.org).
+
+## Commands
+
+* `mkdocs new [dir-name]` - Create a new project.
+* `mkdocs serve` - Start the live-reloading docs server.
+* `mkdocs build` - Build the documentation site.
+* `mkdocs help` - Print this help message.
+
+## Project layout
+
+    mkdocs.yml    # The configuration file.
+    docs/
+        index.md  # The documentation homepage.
+        ...       # Other markdown pages, images and other files.

docs/index.md

@@ -0,0 +1,48 @@
+# Welcome to RESTier!
+
+RESTier is a RESTful API development framework for building standardized, OData V4 based RESTful services on .NET 
+platform. It can be seen as a middle-ware on top of [**Web API OData**](http://odata.github.io/WebApi/). 
+
+RESTier is the spiritual successor to [WCF Data Services](https://en.wikipedia.org/wiki/WCF_Data_Services). Instead of 
+generating endless boilerplate code with the current Web API + OData toolchain, RESTier helps you boostrap a standardized, 
+queryable HTTP-based REST interface in literally minutes. And that's just the beginning.
+
+Like WCF Data Services before it, RESTier provides simple and straightforward ways to shape queries and intercept submissions
+before and after they hit the database. And like Web API + OData, you still have the flexibility to add your own
+custom queries and actions with techniques you're already familiar with.
+
+But RESTier isn't just for OData and the Entity Framework. It also supports adding additional publishers to support other 
+protocols and additional providers to support other data sources.
+
+## What is OData?
+
+OData stands for the Open Data Protocol. OData enables the creation and consumption of RESTful APIs, which allow 
+resources, defined in a data model and identified by using URLs, to be published and edited by Web clients using 
+simple HTTP requests.
+
+OData was originally designed by Microsoft to be a framework for exposing Entity Framework objects over REST services.
+The first concepts shipped as "Project Astoria" in 2007. By 2009, the concept had evolved enough for Microsoft to
+announce OData, along with a [larger effort](https://blogs.msdn.microsoft.com/odatateam/2009/11/17/breaking-down-data-silos-the-open-data-protocol-odata/)
+to push the format as an insustry standard.
+
+Work on the current version of the protocol (V4) began in April 2012, and was ratified by OASIS as an industry standard in Feb 2014.
+
+You can find out more about OData at [OData.org](http://www.odata.org/).
+
+## RESTier Contributors
+
+Special thanks to everyone involved in making RESTier the best API development platform for .NET. The following people
+have made various contributions to the codebase:
+
+| Microsoft     | External       |
+|---------------|----------------|
+| Lewis Cheng   | Cengiz Ilerler |
+| Challenh      | Kemal M        |
+| Eric Erhardt  | Robert McLaws  |
+| Vincent He    |                |
+| Dong Liu      |                |
+| Layla Liu     |                |
+| Fan Ouyang    |                |
+| Congyong S    |                |
+| Mark Stafford |                |
+| Ray Yao       |                |

docs/license.md

@@ -0,0 +1 @@
+[THIS IS A PLACEHOLDER FOR FUTURE CONTENT]