GettingStarted.cshtml

@{
    ViewBag.Title = "Getting Started";
}

@section scripts {
    <script type="text/javascript">
        $('body').scrollspy({ target: '#local_navbar' });
    </script>
}

<style>
    .affix {
        top: 80px;
    }

    #local_navbar ul.nav li ul {
        display: none;
    }

    #local_navbar ul.nav li.active ul {
        display: block;
        padding-left: 10px
    }

    #local_navbar ul.nav li.active ul.nav li a {
        padding-top: 0px;   
        padding-bottom: 0px;
        margin-top: 4px;
        margin-bottom: 4px;
    }

    #local_navbar ul.nav li.active ul.nav li.active {
        border-left: 2px solid blue;
        margin-left: -2px;
    }
</style>

<div class="row">
    <div class="col-md-3 hidden-sm hidden-xs">
        <div id="local_navbar" data-spy="affix">
            <ul class="nav nav-pills nav-stacked">
                <li class="active"><a href="#top">Top</a></li>

                <li>
                    <a href="#dynamicLinqApi">Dynamic LINQ API</a>
                    <ul class="nav">
                        <li><a href="#subValues">Substitution Values</a></li>
                        <li><a href="#iqueryableExtensionMethods">IQueryable Extension Methods</a></li>
                        <li><a href="#parseExceptionClass">ParseException Class</a></li>
                    </ul>
                </li>

                <li>
                    <a href="#expressionLanguage">Expression Language</a>
                    <ul class="nav">
                        <li><a href="#identifiers">Identifiers</a></li>
                        <li><a href="#literals">Literals</a></li>
                        <li><a href="#constants">Constants</a></li>
                        <li><a href="#types">Types</a></li>
                        <li><a href="#conversions">Conversions</a></li>
                        <li><a href="#operators">Operators</a></li>
                        <li><a href="#invocations">Invocations</a></li>
                        <li><a href="#initializers">Data Object Initializers</a></li>
                        <li><a href="#currentInstance">Current Instance</a></li>
                        <li><a href="#queryOperators">Query Operators</a></li>
                        <li><a href="#enumTypeSupport">Enum Type Support</a></li>
                    </ul>
                </li>

            </ul>
        </div>
    </div>
    <div class="col-md-9">
        <section id="top">
            <h2>@ViewBag.Title</h2>
        </section>

        <section>
            <h3>Dynamic Expressions and Queries in LINQ</h3>
            <div class="row">
                <div class="col-md-9">
                    @Html.FormatMarkdown("Database applications frequently rely on “Dynamic SQL” queries that are constructed at run-time through program logic. The LINQ infrastructure supports similar capabilities through dynamic construction of expression trees using the classes in the `System.Linq.Expressions` namespace. Expression trees are an appropriate abstraction for a variety of scenarios, but for others a string-based representation may be more convenient. The [Dynamic LINQ API][0] extends the core LINQ API with that capability.\n[0]:#dynamicLinqApi")
                    <p>The Dynamic LINQ API relies on a simple <a href="#expressionLanguage">expression language</a> for formulating expressions and queries in strings.</p>
                </div>
            </div>
        </section>

        <section id="dynamicLinqApi">
            <h3>Dynamic LINQ API</h3>
            <div class="row">
                <div class="col-md-9">
                    @Html.FormatMarkdown("Dynamic Linq is brought into scope by using (importing) the `System.Linq.Dynamic` namespace. Below is an example of applying the Dynamic LINQ API to a LINQ to SQL data source.")
                    @Html.FormatCodeBlock("var query = db.Customers\n     .Where(\"City = @0 and Orders.Count >= @1\", \"London\", 10)\n     .OrderBy(\"CompanyName\")\n     .Select(\"new(CompanyName as Name, Phone)\");")
                </div>
                <div class="col-md-3">
                    @using (Html.BeginNote())
                    {
                        <p>Expressions in the query are strings that could have been dynamically constructed at run-time.</p>
                    }
                </div>
            </div>
        </section>

        <section id="subValues">
            <h4>Substitution Values</h4>
            <div class="row">
                <div class="col-md-9">
                    @Html.FormatMarkdown("Several methods in the Dynamic LINQ API permit *substitution* values to be specified through a parameter array. Substitution values are referenced in an expression using [identifiers][0] of the form `@x`, where `x` is an index into the parameter array. The last element of the parameter array may be an object that implements `IDictionary<string, object>`. If so, this dictionary is used to map identifiers to substitution values during parsing.\n[0]:#identifiers")
                </div>
            </div>
        </section>

        <section id="iqueryableExtensionMethods">
            <h4>IQueryable Extension Methods</h4>
            <div class="row">
                <div class="col-md-9">
                    @Html.FormatMarkdown("The [System.Linq.Dynamic.DynamicQueryable][0] class implements the following extension methods for dynamically querying objects that implement the `IQueryable<T>` interface.\n[0]:/Library/DynamicQueryable")
                    @Html.FormatMarkdown("The methods found in `DynamicQueryable` correspond to their System.Linq.Queryable counterparts, except that they operate on `IQueryable` instead of `IQueryable<T>` and use string expressions instead of lambda expressions to express predicates, selectors, and orderings. `IQueryable` is the non-generic base interface for `IQueryable<T>`, so the methods can be used even when `T` isn’t known on beforehand, i.e. when the source of a query is dynamically determined.")
                    @Html.FormatMarkdown("The *predicate*, *selector*, *ordering*, *keySelector*, and *elementSelector* parameters are strings containing expressions written in the [expression language][0]. In the expression strings, the members of the [current instance][1] are automatically in scope and the instance itself can be referenced using the keyword `it` or symbol `$`.\n[0]:#expressionLanguage\n[1]:#currentInstance")
                    @Html.FormatMarkdown("The [`OrderBy`][0] method permits a sequence of orderings to be specified, separated by commas. Each ordering may optionally be followed by `asc` or `ascending` to indicate ascending order, or `desc` or `descending` to indicate descending order. The default order is ascending. The example\n[0]:/Library/DynamicQueryable/OrderBy(TSource)")
                    @Html.FormatCodeBlock("products.OrderBy(\"Category.CategoryName, UnitPrice descending\");")
                    <p>orders a sequence of products by ascending category name and, within each category, descending unit price.</p>
                </div>
                <div class="col-md-3">
                    @using (Html.BeginNote())
                    {
                        @Html.FormatMarkdown("Because a dynamic predicate or ordering does not affect the result type, generic overloads are provided for `Where` and `OrderBy` in order to preserve strong typing when possible.")
                    }
                </div>
            </div>
        </section>

        <section id="parseExceptionClass">
            <h4>ParseException Class</h4>
            <div class="row">
                <div class="col-md-9">
                    @Html.FormatMarkdown("The Dynamic Expression API reports parsing errors using the [`System.Linq.Dynamic.ParseException`][0] class. The [`Position`][1] property of the [`ParseException`][0] class gives the character index in the expression string at which the parsing error occurred.\n[0]:/Library/ParseException\n[1]:/Library/ParseException/Property-Position")
                </div>
            </div>
        </section>

        <section id="expressionLanguage">
            <h3>Expression Language</h3>
            <div class="row">
                <div class="col-md-9">
                    <p>The expression language implemented by the Dynamic LINQ API provides a simple and convenient way of writing expressions that can be parsed into LINQ expression trees. The language supports most of the constructs of expression trees, but it is by no means a complete query or programming language. In particular, the expression language does not support statements or declarations.</p>
                    @Html.FormatMarkdown("The expression language is designed to be familiar to **C#**, **VB**, and **SQL** users. For this reason, some operators are present in multiple forms, such as `&&` and `and`.")
                </div>
            </div>
        </section>

        <section id="identifiers">
            <h4>Identifiers</h4>
            <div class="row">
                <div class="col-md-9">
                    @Html.FormatMarkdown("An *Identifier* consists of a letter or underscore followed by any number of letters, digits, or underscores. In order to reference an identifier with the same spelling as a keyword, the identifier must be prefixed with a single `@` character. Some examples of identifiers:")
                    @Html.InlineCodeList("x", "Hello", "m_1", "@true", "@String")
                    @Html.FormatMarkdown("Identifiers of the from `@x`, where `x` is an integral number greater than or equal to zero, are used to denote the [substitution values][0], if any, that were passed to the expression parser. For example:\n[0]:#subValues")
                    @Html.FormatCodeBlock("customers.Where(\"Country = @0\", country);")
                </div>
                <div class="col-md-3">
                    @using (Html.BeginNote())
                    {
                        <p>Casing is not significant in identifiers or keywords.</p>
                    }
                </div>
            </div>

        </section>

        <section id="literals">
            <h4>Literals</h4>
            <div class="row">
                <div class="col-md-9">
                    <p>The expression language supports integer, real, string, and character literals.</p>
                    @Html.FormatMarkdown("An *integer literal* consists of a sequence of digits. The type of an integer literal is the first of the types `Int32`, `UInt32`, `Int64`, or `UInt64` that can represent the given value. An integer literal implicitly converts to any other numeric type provided the number is in the range of that type. Some examples of integer literals:")
                    @Html.InlineCodeList("0", "123", "10000")

                    @Html.FormatMarkdown("A *real literal* consists of an integral part followed by a fractional part and/or an exponent. The integral part is a sequence of one or more digits. The fractional part is a decimal point followed by one or more digits. The exponent is the letter e or E followed by an optional + or – sign followed by one or more digits. The type of a real literal is `Double`. A real literal implicitly converts to any other real type provided the number is in the range of that type. Some examples of real literals:")
                    @Html.InlineCodeList("1.0", "2.25", "10000.0", "1e0", "1e10", "1.2345E-4")

                    @Html.FormatMarkdown("A *string literal* consists of zero or more characters enclosed in double quotes. Inside a string literal, a double quote is written as two consecutive double quotes. The type of a string literal is `String`. Some examples of string literals:")
                    @Html.InlineCodeList("\"hello\"", "\"\"", "\"\"\"quoted\"\"\"", "\"'\"")

                    @Html.FormatMarkdown("A *character literal* consists of a single character enclosed in single quotes. Inside a character literal, a single quote is written as two consecutive single quotes. The type of a character literal is `Char`. Some examples of character literals:")
                    @Html.InlineCodeList("'A'", "'1'", "''''", "'\"'")
                </div>
            </div>
        </section>

        <section id="constants">
            <h4 id="constants">Constants</h4>
            <div class="row">
                <div class="col-md-9">
                    @Html.FormatMarkdown("The predefined constants `true` and `false` denote the two values of the type `Boolean`.")
                    @Html.FormatMarkdown("The predefined constant `null` denotes a *null* reference. The `null` constant is of type `Object`, but is also implicitly convertible to any reference type.")
                </div>
            </div>
        </section>

        <section id="types">
            <h4>Types</h4>
            <div class="row">
                <div class="col-md-9">
                    @Html.FormatMarkdown("The expression language defines the following *primitive types*:")
                    @Html.InlineCodeList("Object", "Boolean", "Char", "String", "SByte", "Byte", "Int16", "UInt16", "Int32", "UInt32", "Int64", "UInt64", "Decimal", "Single", "Double", "DateTime", "TimeSpan", "Guid")

                    @Html.FormatMarkdown("The primitive types correspond to the similarly named types in the `System` namespace of the .NET Framework Base Class Library. The expression language also defines a set of accessible types consisting of the primitive types and the following types from the `System` namespace:")
                    @Html.InlineCodeList("Math", "Convert")

                    <p>The accessible types are the only types that can be explicitly referenced in expressions, and method invocations in the expression language are restricted to methods declared in the accessible types.</p>
                    @Html.FormatMarkdown("The *nullable form* of a value type is referenced by writing a `?` after the type name. For example, `Int32?` denotes the nullable form of `Int32`.")
                    @Html.FormatMarkdown("The non-nullable and nullable forms of the types `SByte`, `Byte`, `Int16`, `UInt16`, `Int32`, `UInt32`, `Int64`, and `UInt64` are collectively called the *integral types*.")
                    @Html.FormatMarkdown("The non-nullable and nullable forms of the types `Single`, `Double`, and `Decimal` are collectively called the *real types*.")
                    @Html.FormatMarkdown("The integral types and real types are collectively called the *numeric types*.")
                </div>
            </div>
        </section>

        <section id="conversions">
            <h4>Conversions</h4>
            <div class="row">
                <div class="col-md-9">
                    <p>The following conversions are implicitly performed by the expression language:</p>
                    <ul>
                        <li>@Html.FormatMarkdown("From the the `null` literal to any reference type or nullable type.")</li>
                        <li>@Html.FormatMarkdown("From an integer literal to an integral type or real type provided the number is within the range of that type.")</li>
                        <li>@Html.FormatMarkdown("From a real literal to a real type provided the number is within the range of that type.")</li>
                        <li>@Html.FormatMarkdown("From a string literal to an enum type provided the string literal contains the name of a member of that enum type.")</li>
                        <li>@Html.FormatMarkdown("From a source type that is assignment compatible with the target type according to the `Type.IsAssignableFrom` method in .NET.")</li>
                        <li>@Html.FormatMarkdown("From a non-nullable value type to the nullable form of that value type.")</li>
                        <li>@Html.FormatMarkdown("From a numeric type to another numeric type with greater range.")</li>
                    </ul>
                    @Html.FormatMarkdown("The expression language permits explicit conversions using the syntax `type(expr)` or `type\"string\"`, where *type* is a type name optionally followed by `?` and *expr* is an expression or *string* is a string literal. This syntax may be used to perform the following conversions:")
                    <ul>
                        <li>@Html.FormatMarkdown("Between two types provided `Type.IsAssignableFrom` is true in one or both directions.")</li>
                        <li>@Html.FormatMarkdown("Between two types provided one or both are interface types.")</li>
                        <li>@Html.FormatMarkdown("Between the nullable and non-nullable forms of any value type.")</li>
                        <li>@Html.FormatMarkdown("Between string and any type that have static TryParse method.")</li>
                        <li>@Html.FormatMarkdown("Between any two types belonging to the set consisting of `SByte`, `Byte`, `Int16`, `UInt16`, `Int32`, `UInt32`, `Int64`, `UInt64`, `Decimal`, `Single`, `Double`, `Char`, any *enum* type, as well as the *nullable* forms of those types.")</li>
                    </ul>
                </div>
            </div>
        </section>

        <section id="operators">
            <h4>Operators</h4>
            <div class="row">
                <div class="col-md-9">
                    <p>The table below shows the operators supported by the expression language in order of precedence from highest to lowest. Operators in the same category have equal precedence. In the table, x, y, and z denote expressions, s denotes a <a href="#types">String</a>, T denotes a <a href="#types">type</a>, and m denotes a member.</p>

                    <table class="table table-responsive">
                        <thead>
                            <tr>
                                <th>Category</th>
                                <th>Expression</th>
                                <th>Description</th>
                            </tr>
                        </thead>
                        <tbody>
                            <tr>
                                <td rowspan="11">Primary</td>
                                <td><code>x.m</code></td>
                                <td>Instance field or instance property access. Any public field or property can be accessed.</td>
                            </tr>
                            <tr>
                                <td><code>x.m(...)</code></td>
                                <td>Instance <a href="#invocations">method invocation</a>. The method must be public and must be declared in an accessible type.</td>
                            </tr>
                            <tr>
                                <td><code>x[…]</code></td>
                                <td>Array or indexer access. Multi-dimensional arrays are not supported.</td>
                            </tr>
                            <tr>
                                <td><code>T.m</code></td>
                                <td>Static field or static property access. Any public field or property can be accessed.</td>
                            </tr>
                            <tr>
                                <td><code>T.m(…)</code></td>
                                <td>Static <a href="#invocations">method invocation</a>. The method must be public and must be declared in an accessible type.</td>
                            </tr>
                            <tr>
                                <td><code>T(…)</code></td>
                                <td><a href="#conversions">Explicit conversion</a> or <a href="#invocations">constructor invocation</a>. Note that new is not required in front of a constructor invocation.</td>
                            </tr>
                            <tr>
                                <td><code>T"s"</code></td>
                                <td><a href="#conversions">Explicit conversion</a> from string (using Parse, Convert or <a href="#invocations">constructor invocation</a> with string parameter). Note that new is not required in front of a constructor invocation.</td>
                            </tr>
                            <tr>
                                <td><code>new(…)</code></td>
                                <td><a href="#initializers">Data object initializer</a>. This construct can be used to perform dynamic projections.</td>
                            </tr>
                            <tr>
                                <td><code>it</code><br /><code>$</code></td>
                                <td><a href="#currentInstance">Current instance</a>. In contexts where members of a current object are implicitly in scope, <code>it</code> or <code>$</code> is used to refer to the entire object itself.</td>
                            </tr>
                            <tr>
                                <td><code>parent</code><br /><code>^</code></td>
                                <td>Parent instance. In contexts where an object is implicitly in scope, and a parent scope exists, <code>parent</code> or <code>^</code>  is used to refer to the entire parent object.</td>
                            </tr>
                            <tr>
                                <td><code>root</code><br /><code>~</code></td>
                                <td>Root instance. In contexts where one or more multiple object scopes exist, <code>root</code> or <code>~</code> is used to refer to the entire root (first level) object.</td>
                            </tr>
                            <tr>
                                <td><code>iif(x, y, z)</code></td>
                                <td>Conditional expression. Alternate syntax for x ? y : z.</td>
                            </tr>

                            <tr>
                                <td rowspan="2">Unary</td>
                                <td><code>-x</code></td>
                                <td>Negation</td>
                            </tr>
                            <tr>
                                <td><code>!x</code><br /><code>not x</code></td>
                                <td>@Html.FormatMarkdown("Logical negation. Operand must be of type `Boolean`.")</td>
                            </tr>

                            <tr>
                                <td rowspan="3">Multiplicative</td>
                                <td><code>x * y</code></td>
                                <td>Multiplication.</td>
                            </tr>
                            <tr>
                                <td><code>x / y</code></td>
                                <td>Division.</td>
                            </tr>
                            <tr>
                                <td><code>x % y</code><br /><code>x mod y</code></td>
                                <td>Remainder.</td>
                            </tr>

                            <tr>
                                <td rowspan="3">Additive</td>
                                <td><code>x + y</code></td>
                                <td>@Html.FormatMarkdown("Addition or string concatenation. Performs string concatenation if either operand is of type `String`. Otherwise, performs addition for the supported types.")</td>
                            </tr>
                            <tr>
                                <td><code>x - y</code></td>
                                <td>Subtraction.</td>
                            </tr>
                            <tr>
                                <td><code>x & y</code></td>
                                <td>String concatenation. Operands may be of any type.</td>
                            </tr>

                            <tr>
                                <td rowspan="6">Relational</td>
                                <td><code>x = y</code><br /><code>x == y</code><br /><code>x eq y</code></td>
                                <td>Equal. Supported for reference types and the primitive types. Assignment is not supported.</td>
                            </tr>
                            <tr>
                                <td><code>x != y</code><br /><code>x <> y</code><br /><code>x ne y</code></td>
                                <td>Not equal. Supported for reference types and the primitive types.</td>
                            </tr>
                            <tr>
                                <td><code>x &lt; y</code><br /><code>x lt y</code></td>
                                <td>Less than.</td>
                            </tr>
                            <tr>
                                <td><code>x &gt; y</code><br /><code>x gt y</code></td>
                                <td>Greater than.</td>
                            </tr>
                            <tr>
                                <td><code>x &lt;= y</code><br /><code>x le y</code></td>
                                <td>Less than or equal.</td>
                            </tr>
                            <tr>
                                <td><code>x &gt;= y</code><br /><code>x ge y</code></td>
                                <td>Greater than or equal</td>
                            </tr>

                            <tr>
                                <td>Logical AND</td>
                                <td><code>x && y</code><br /><code>x and y</code></td>
                                <td>Logical AND. Operands must be of type <code>Boolean</code>.</td>
                            </tr>

                            <tr>
                                <td>Logical OR</td>
                                <td><code>x || y</code><br /><code>x or y</code></td>
                                <td>Logical OR. Operands must be of type <code>Boolean</code>.</td>
                            </tr>

                            <tr>
                                <td>Conditional</td>
                                <td><code>x ? y : z</code></td>
                                <td>Evaluates y if x is true, evaluates z if x is false.</td>
                            </tr>
                        </tbody>
                    </table>
                </div>
            </div>
        </section>

        <section id="invocations">
            <h4>Method and Constructor Invocations</h4>
            <div class="row">
                <div class="col-md-9">
                    <p>The expression language limits invocation of methods and constructors to those declared public in the accessible types. This restriction exists to protect against unintended side effects from invocation of arbitrary methods.</p>
                    <p>The expression language permits getting (but not setting) the value of any reachable public field, property, or indexer.</p>
                    <p>Overload resolution for methods, constructors, and indexers uses rules similar to C#. In informal terms, overload resolution will pick the best matching method, constructor, or indexer, or report an ambiguity error if no single best match can be identified.</p>
                    @Html.FormatMarkdown("Note that constructor invocations are not prefixed by new. The following example creates a `DateTime` instance for a specfic year, month, and day using a constructor invocation:")
                    @Html.FormatCodeBlock("orders.Where(\"OrderDate >= DateTime(2007, 1, 1)\");")
                </div>
            </div>
        </section>

        <section id="initializers">
            <h4>Data Object Initializers</h4>
            <div class="row">
                <div class="col-md-9">
                    <p>A data object initializer creates a dynamically generated class and returns an instance of that class. The properties of the class are inferred from the data object initializer. Specifically, a data object initializer of the form <code>new(e1 as p1, e2 as p2, e3 as p3)</code> creates a class with three properties, p1, p2, and p3, the types of which are inferred from the expressions e1, e2, and e3, and returns an instance of that data class with the properties initialized to the values computed by e1, e2, and e3. A property initializer may omit the <code>as</code> keyword and the property name provided the associated expression is a field or property access.</p>
                    <p>The example:</p>
                    @Html.FormatCodeBlock("customers.Select(\"new(CompanyName as Name, Phone)\");")
                    <p>creates a data class with two properties, Name and Phone, and returns a sequence of instances of that class initialized from the CompanyName and Phone properties of each customer.</p>
                </div>
            </div>
        </section>

        <section id="currentInstance">
            <h4>Current Instance</h4>
            <div class="row">
                <div class="col-md-9">
                    <p>When parsing a string expression, the members of the current instance are automatically in scope, and the current instance can be referenced in whole using the keyword <code>it</code> or the symbol <code>$</code>. For example,</p>
                    @Html.FormatCodeBlock("customers.Where(\"Country = @0\", country);")
                    <p>is equivalent to</p>
                    @Html.FormatCodeBlock("customers.Where(\"it.Country = @0\", country);")
                    <p>or</p>
                    @Html.FormatCodeBlock("customers.Where(\"$.Country = @0\", country);")
                </div>
            </div>
        </section>

        <section id="queryOperators">
            <h4>Query Operators</h4>
            <div class="row">
                <div class="col-md-9">
                    @Html.FormatMarkdown("A subset of the Standard Query Operators is supported for objects that implement `IEnumerable<T>`. Specifically, the following constructs are permitted, where *seq* is an `IEnumerable<T>` instance, *predicate* is a boolean expression, and *selector* is an expression of any type:")
                    <ul class="list-unstyled">
                        <li><code>seq.Where(predicate)</code></li>
                        <li><code>seq.Any()</code></li>
                        <li><code>seq.Any(predicate)</code></li>
                        <li><code>seq.All(predicate)</code></li>
                        <li><code>seq.Count()</code></li>
                        <li><code>seq.Count(predicate)</code></li>
                        <li><code>seq.Min(selector)</code></li>
                        <li><code>seq.Max(selector)</code></li>
                        <li><code>seq.Sum(selector)</code></li>
                        <li><code>seq.Average(selector)</code></li>
                    </ul>
                    @Html.FormatMarkdown("In the *predicate* and *selector* expressions, the members of the [current instance][0] for that sequence operator are automatically in scope, and the instance itself can be referenced using the keyword `it` or symbol `$`. An example:\n[0]:#currentInstance")
                    @Html.FormatCodeBlock("customers.Where(\"Orders.Any(Total >= 1000)\");")
                    <p>or</p>
                    @Html.FormatCodeBlock("customers.Where(\"it.Orders.Any(it.Total >= 1000)\");")
                </div>
            </div>
        </section>

        <section id="enumTypeSupport">
            <h4>Enum Type Support</h4>
            <div class="row">
                <div class="col-md-9">
                    <p>The expression language supports an <a href="#conversions">implicit conversion</a> from a string literal to an enum type provided the string literal contains the name of a member of that enum type. For example,</p>
                    @Html.FormatCodeBlock("orders.Where(\"OrderDate.DayOfWeek = \\\"Monday\\\"\");")
                    <p>is equivalent to</p>
                    @Html.FormatCodeBlock("orders.Where(\"OrderDate.DayOfWeek = @0\", DayOfWeek.Monday);")
                </div>
            </div>
        </section>
    </div>
</div>