Publish to live 2022-01-12

entity-framework/core/extensions/index.md

@@ -197,12 +197,12 @@ Add support for calling extension methods in LINQ lambdas. For EF Core: 3, 5.
 
 [GitHub repository](https://github.com/ClaveConsulting/Expressionify) | [NuGet](https://www.nuget.org/packages/Clave.Expressionify)
 
-### ELinq
+### EntityLinq
 
-Language Integrated Query (LINQ) technology for relational databases. It allows you to use C# to write strongly typed queries. For EF Core: 3, 5.
+Alternative (not MS based) Language Integrated Query (LINQ) technology for relational databases. It allows you to use C# to write strongly typed SQL queries. For EF Core: 3, 5, 6.
 
 - Full C# support for query creation: multiple statements inside lambda, variables, functions, etc.
-- No semantic gap with SQL. ELinq declares SQL statements (like `SELECT`, `FROM`, `WHERE`) as first class C# methods, combining familiar syntax with intellisense, type safety and refactoring.
+- No semantic gap with SQL. EntityLinq declares SQL statements (like `SELECT`, `FROM`, `WHERE`) as first class C# methods, combining familiar syntax with intellisense, type safety and refactoring.
 
 As a result SQL becomes just "another" class library exposing its API locally, literally *"Language Integrated SQL"*.
 
@@ -254,7 +254,7 @@ Includes support for advanced SQL features such as CTEs, bulk copy, table hints,
 
 ### EFCore.SoftDelete
 
-An implementation for soft deleting entities. For EF Core: 3.
+An implementation for soft deleting entities. For EF Core: 3, 5, 6.
 
 [GitHub repository](https://github.com/AshkanAbd/efCoreSoftDeletes) | [NuGet](https://www.nuget.org/packages/EFCore.SoftDelete)
 

entity-framework/core/modeling/value-conversions.md

@@ -319,7 +319,7 @@ However, if by default all `EquineBeast` columns should be `varchar(20)`, then t
 -->
 [!code-csharp[ConversionByConverterInstanceWithMappingHints](../../../samples/core/Modeling/ValueConversions/EnumToStringConversions.cs?name=ConversionByConverterInstanceWithMappingHints)]
 
-Now any time this converter is used, the database column will be non-unicode with a max length of 20. However, these are only hints since they are be overridden by any facets explicitly set on the mapped property.
+Now any time this converter is used, the database column will be non-unicode with a max length of 20. However, these are only hints since they are overridden by any facets explicitly set on the mapped property.
 
 ## Examples
 

entity-framework/core/performance/efficient-querying.md

@@ -64,7 +64,13 @@ As a result, it's usually worth giving thought to limiting the number of results
 
 [!code-csharp[Main](../../../samples/core/Performance/Program.cs#Limit25)]
 
-At a minimum, your UI could show a message indicating that more rows may exist in the database (and allow retrieving them in some other manner). A full-blown solution would implement *paging*, where your UI only shows a certain number of rows at a time, and allow users to advance to the next page as needed; this typically combines the <xref:System.Linq.Enumerable.Take%2A> and <xref:System.Linq.Enumerable.Skip%2A> operators to select a specific range in the resultset each time.
+At a minimum, your UI could show a message indicating that more rows may exist in the database (and allow retrieving them in some other manner). A full-blown solution would implement *pagination*, where your UI only shows a certain number of rows at a time, and allow users to advance to the next page as needed; see the next section for more details on how to implement this efficiently.
+
+## Efficient pagination
+
+Pagination refers to retrieving results in pages, rather than all at once; this is typically done for large resultsets, where a user interface is shown that allows the user to navigate to the next or previous page of the results. A common way to implement pagination with databases is to use the `Skip` and `Take` operators (`OFFSET` and `LIMIT` in SQL); while this is an intuitive implementation, it's also quite inefficient. For pagination that allows moving on page at a time (as opposed to jumping to arbitrary pages), consider using *keyset pagination* instead.
+
+For more information, [eee the documentation page on pagination](xref:core/querying/pagination).
 
 ## Avoid cartesian explosion when loading related entities
 

entity-framework/core/providers/cosmos/index.md

@@ -2,7 +2,7 @@
 title: Azure Cosmos DB Provider - EF Core
 description: Documentation for the database provider that allows Entity Framework Core to be used with the Azure Cosmos DB SQL API
 author: AndriySvyryd
-ms.date: 11/15/2021
+ms.date: 01/11/2022
 uid: core/providers/cosmos/index
 ---
 # EF Core Azure Cosmos DB Provider
@@ -103,8 +103,33 @@ Once configured the partition key property should always have a non-null value.
 
 It is generally recommended to add the partition key to the primary key as that best reflects the server semantics and allows some optimizations, for example in `FindAsync`.
 
+### Provisioned throughput
+
+If you use EF Core to create the Azure Cosmos database or containers you can configure [provisioned throughput](/azure/cosmos-db/set-throughput) for the database by calling <xref:Microsoft.EntityFrameworkCore.CosmosModelBuilderExtensions.HasAutoscaleThroughput%2A?displayProperty=nameWithType> or <xref:Microsoft.EntityFrameworkCore.CosmosModelBuilderExtensions.HasManualThroughput%2A?displayProperty=nameWithType>. For example:
+
+<!--
+modelBuilder.HasManualThroughput(2000);
+modelBuilder.HasAutoscaleThroughput(4000);
+-->
+[!code-csharp[ModelThroughput](../../../../samples/core/Miscellaneous/NewInEFCore6.Cosmos/CosmosModelConfigurationSample.cs?name=ModelThroughput)]
+
+To configure provisioned throughput for a container call <xref:Microsoft.EntityFrameworkCore.CosmosEntityTypeBuilderExtensions.HasAutoscaleThroughput%2A?displayProperty=nameWithType> or <xref:Microsoft.EntityFrameworkCore.CosmosEntityTypeBuilderExtensions.HasManualThroughput%2A?displayProperty=nameWithType>. For example:
+
+<!--
+modelBuilder.Entity<Family>(
+    entityTypeBuilder =>
+    {
+        entityTypeBuilder.HasManualThroughput(5000);
+        entityTypeBuilder.HasAutoscaleThroughput(3000);
+    });
+-->
+[!code-csharp[EntityTypeThroughput](../../../../samples/core/Miscellaneous/NewInEFCore6.Cosmos/CosmosModelConfigurationSample.cs?name=EntityTypeThroughput)]
+
 ## Embedded entities
 
+> [!NOTE]
+> Beginning with EF Core 6.0 related entity types are configured as owned by default. To prevent this for a specific entity type call <xref:Microsoft.EntityFrameworkCore.ModelBuilder.Entity%2A?displayProperty=nameWithType>.
+
 For Cosmos, owned entities are embedded in the same item as the owner. To change a property name use [ToJsonProperty](/dotnet/api/Microsoft.EntityFrameworkCore.CosmosEntityTypeBuilderExtensions.ToJsonProperty):
 
 [!code-csharp[PropertyNames](../../../../samples/core/Cosmos/ModelBuilding/OrderContext.cs?name=PropertyNames)]
@@ -169,6 +194,91 @@ Internally EF Core always needs to have unique key values for all tracked entiti
 > [!TIP]
 > When necessary the default primary key for the owned entity types can be changed, but then key values should be provided explicitly.
 
+### Collections of primitive types
+
+Collections of supported primitive types, such as `string` and `int`, are discovered and mapped automatically. Supported collections are all types that implement <xref:System.Collections.Generic.IReadOnlyList%601> or <xref:System.Collections.Generic.IReadOnlyDictionary%602>. For example, consider this entity type:
+
+<!--
+public class Book
+{
+    public Guid Id { get; set; }
+    public string Title { get; set; }
+    public IList<string> Quotes { get; set; }
+    public IDictionary<string, string> Notes { get; set; }
+}
+-->
+[!code-csharp[BookEntity](../../../../samples/core/Miscellaneous/NewInEFCore6.Cosmos/CosmosPrimitiveTypesSample.cs?name=BookEntity)]
+
+Both the list and the dictionary can be populated and inserted into the database in the normal way:
+
+<!--
+using var context = new BooksContext();
+
+var book = new Book
+{
+    Title = "How It Works: Incredible History",
+    Quotes = new List<string>
+    {
+        "Thomas (Tommy) Flowers was the British engineer behind the design of the Colossus computer.",
+        "Invented originally for Guinness, plastic widgets are nitrogen-filled spheres.",
+        "For 20 years after its introduction in 1979, the Walkman dominated the personal stereo market."
+    },
+    Notes = new Dictionary<string, string>
+    {
+        { "121", "Fridges" },
+        { "144", "Peter Higgs" },
+        { "48", "Saint Mark's Basilica" },
+        { "36", "The Terracotta Army" }
+    }
+};
+
+context.Add(book);
+context.SaveChanges();
+-->
+[!code-csharp[Insert](../../../../samples/core/Miscellaneous/NewInEFCore6.Cosmos/CosmosPrimitiveTypesSample.cs?name=Insert)]
+
+This results in the following JSON document:
+
+```json
+{
+    "Id": "0b32283e-22a8-4103-bb4f-6052604868bd",
+    "Discriminator": "Book",
+    "Notes": {
+        "36": "The Terracotta Army",
+        "48": "Saint Mark's Basilica",
+        "121": "Fridges",
+        "144": "Peter Higgs"
+    },
+    "Quotes": [
+        "Thomas (Tommy) Flowers was the British engineer behind the design of the Colossus computer.",
+        "Invented originally for Guinness, plastic widgets are nitrogen-filled spheres.",
+        "For 20 years after its introduction in 1979, the Walkman dominated the personal stereo market."
+    ],
+    "Title": "How It Works: Incredible History",
+    "id": "Book|0b32283e-22a8-4103-bb4f-6052604868bd",
+    "_rid": "t-E3AIxaencBAAAAAAAAAA==",
+    "_self": "dbs/t-E3AA==/colls/t-E3AIxaenc=/docs/t-E3AIxaencBAAAAAAAAAA==/",
+    "_etag": "\"00000000-0000-0000-9b50-fc769dc901d7\"",
+    "_attachments": "attachments/",
+    "_ts": 1630075016
+}
+```
+
+These collections can then be updated, again in the normal way:
+
+<!--
+book.Quotes.Add("Pressing the emergency button lowered the rods again.");
+book.Notes["48"] = "Chiesa d'Oro";
+
+context.SaveChanges();
+-->
+[!code-csharp[Updates](../../../../samples/core/Miscellaneous/NewInEFCore6.Cosmos/CosmosPrimitiveTypesSample.cs?name=Updates)]
+
+Limitations:
+
+* Only dictionaries with string keys are supported
+* Querying into the contents of primitive collections is not currently supported. Vote for [#16926](https://github.com/dotnet/efcore/issues/16926), [#25700](https://github.com/dotnet/efcore/issues/25700), and [#25701](https://github.com/dotnet/efcore/issues/25701) if these features are important to you.
+
 ## Working with disconnected entities
 
 Every item needs to have an `id` value that is unique for the given partition key. By default EF Core generates the value by concatenating the discriminator and the primary key values, using '|' as a delimiter. The key values are only generated when an entity enters the `Added` state. This might pose a problem when [attaching entities](xref:core/saving/disconnected-entities) if they don't have an `id` property on the .NET type to store the value.

entity-framework/core/providers/writing-a-provider.md

@@ -33,3 +33,16 @@ For example:
 * `Microsoft.EntityFrameworkCore.SqlServer`
 * `Npgsql.EntityFrameworkCore.PostgreSQL`
 * `EntityFrameworkCore.SqlServerCompact40`
+
+## The EF Core specification tests
+
+EF Core provides a specification test suite project, which all providers are encouraged to implement. The project contains tests which ensure that the provider function correctly, e.g. by executing various LINQ queries and ensuring that the correct results are returned. This test suite is used by EF Core's own providers (SQL Server, SQLite, Cosmos...) as the primary regression testing mechanism, and are continuously updated and improved as new features are added to EF Core. By implementing these tests for other, 3rd-party providers, you can ensure that your database provider works correctly and implements all the latest EF Core features. Note that the test suite is quite large, as it covers the entire EF Core feature set; you don't have to implement everything - it's perfectly fine to cherry-pick certain test classes, and incrementally improve your coverage with time.
+
+To start using the specification tests, follow these steps:
+
+* Create an xunit test project in your provider solution. We suggest the name `<Provider>.FunctionalTests` for consistency, so if your provider is called `AcmeSoftware.EntityFramework.AcmeDb`, call the test project `AcmeSoftware.EntityFramework.AcmeDb.FunctionalTests`.
+* From your new test project, reference the EF specification tests, which are published as regular Nuget packages. For relational providers, the specification test suite is [Microsoft.EntityFrameworkCore.Relational.Specification.Tests](https://www.nuget.org/packages/Microsoft.EntityFrameworkCore.Relational.Specification.Tests), for non-relational provider, use [Microsoft.EntityFrameworkCore.Specification.Tests](https://www.nuget.org/packages/Microsoft.EntityFrameworkCore.Specification.Tests)).
+* Pick a test class from the EF specification tests, and extend it from a corresponding test class in your own project. The available test classes can be seen in the [EF source code](https://github.com/dotnet/efcore/tree/main/test/EFCore.Relational.Specification.Tests). Your class should be named based on the EF test class, with your provider name inserted where appropriate. For example, `NorthwindWhereQueryRelationalTestBase` (which is a good place to start), would be extended by `NorthwindWhereQueryAcmeDbTest`.
+* At the very beginning, you'll have a bit of test infrastructure to implement - once that's done once, things will become easier. For example, for `NorthwindWhereQueryAcmeDbTest` you'll have to implement `NorthwindWhereQueryAcmeDbFixture`, which will require a `AcmeDbNorthwindTestStoreFactory`, which would need a Northwind.sql script to seed the AcmeDb version of the Northwind database. We strongly suggest keeping another EF Core provider's test suite open nearby, and following what it does. For example, the SQL Server implementation of the specification tests is visible [here](https://github.com/dotnet/efcore/tree/main/test/EFCore.SqlServer.FunctionalTests).
+* Once the infrastructure for the test class is done, you'll start seeing some green tests on it. You can investigate the failing tests, or temporarily skip them for later investigation. In this way you can add more and more test classes.
+* At some point, when you've extended most of the upstream test classes, you can also create `AcmeDbComplianceTest`, which extends `RelationalComplianceTestBase`. This test class will fail if your own test project doesn't extend an EF Core test class - it's a great way to know whether your test suite is complete, and also whether EF added a new test class in a new version. You can also opt out of extending specific test classes if they're not ready (or not relevant).

entity-framework/core/querying/pagination.md

@@ -0,0 +1,56 @@
+---
+title: Pagination - EF Core
+description: Writing paginating queries in Entity Framework Core
+author: roji
+ms.date: 12/19/2021
+uid: core/querying/pagination
+---
+# Pagination
+
+Pagination refers to retrieving results in pages, rather than all at once; this is typically done for large resultsets, where a user interface is shown that allows the user to navigate to the next or previous page of the results.
+
+## Offset pagination
+
+A common way to implement pagination with databases is to use the `Skip` and `Take` (`OFFSET` and `LIMIT` in SQL). Given a a page size of 10 results, the third page can be fetched with EF Core as follows:
+
+[!code-csharp[Main](../../../samples/core/Querying/Pagination/Program.cs?name=OffsetPagination&highlight=4)]
+
+Unfortunately, while this technique is very intuitive, it also has some severe shortcomings:
+
+1. The database must still process the first 20 entries, even if they aren't returned to the application; this creates possibly significant computation load that increases with the number of rows being skipped.
+2. If any updates occur concurrently, your pagination may end up skipping certain entries or showing them twice. For example, if an entry is removed as the user is moving from page 2 to 3, the whole resultset "shifts up", and one entry would be skipped.
+
+## Keyset pagination
+
+The recommended alternative to offset-based pagination - sometimes called *keyset pagination* or *seek-based pagination* - is simply use a `WHERE` clause to skip rows, instead of an offset. This means remember the relevant values from the last entry fetched (instead of its offset), and to ask for the next rows after that row. For example, assuming the last entry in the last page we fetched had an ID value of 55, we'd simply do the following:
+
+[!code-csharp[Main](../../../samples/core/Querying/Pagination/Program.cs?name=KeySetPagination&highlight=4)]
+
+Assuming an index is defined on `PostId`, this query is very efficient, and also isn't sensitive to any concurrent changes happening in lower Id values.
+
+Keyset pagination is appropriate for pagination interfaces where the user navigates forwards and backwards, but does not support random access, where the user can jump to any specific page. Random access pagination requires using offset pagination as explained above; because of the shortcomings of offset pagination, carefully consider if random access pagination really is required for your use case, or if next/previous page navigation is enough. If random access pagination is necessary, a robust implementation could use keyset pagination when navigation to the next/previous page, and offset navigation when jumping to any other page.
+
+> [!WARNING]
+> Always make sure that your ordering is fully deterministic. For example, if results are ordered only by date, but there can be multiple results with the same date, then results could be skipped when paginating as they're ordered differently across two queries. Ordering by both date and ID (or any other unique property) makes the resultset deterministic and avoids this problem. Note that relational databases do not apply any ordering by default, even on the primary key; queries without explicit ordering have non-deterministic resultsets.
+
+### Multiple pagination keys
+
+When using keyset pagination, it's frequently necessary to order by more than one property. For example, the following query paginates by date and ID:
+
+[!code-csharp[Main](../../../samples/core/Querying/Pagination/Program.cs?name=KeySetPaginationWithMultipleKeys&highlight=6)]
+
+This ensures that the next page picks off exactly where the previous one ended. As more ordering keys are added, additional clauses can be added.
+
+> [!NOTE]
+> Most SQL databases support a simpler and more efficient version of the above, using *row values*: `WHERE (Date, Id) > (@lastDate, @lastId)`. EF Core does not currently support expressing this in LINQ queries, this is tracked by [#26822](https://github.com/dotnet/efcore/issues/26822).
+
+## Indexes
+
+As with any other query, proper indexing is vital for good performance: make sure to have indexes in place which correspond to your pagination ordering. If ordering by more than one column, an index over those multiple columns can be defined; this is called a *composite index*.
+
+For more information, [see the documentation page on indexes](xref:core/modeling/indexes).
+
+## Additional resources
+
+* To learn more about the shortcomings of offset-based pagination and about keyset pagination, [see this post](https://use-the-index-luke.com/no-offset).
+* [A technical deep dive presentation](https://www.slideshare.net/MarkusWinand/p2d2-pagination-done-the-postgresql-way) comparing offset and keyset pagination. While the content deals with the PostgreSQL database, the general information is valid for other relational databases as well.

entity-framework/core/querying/single-split-queries.md

@@ -23,7 +23,7 @@ If a typical blog has multiple related posts, rows for these posts will duplicat
 ## Split queries
 
 > [!NOTE]
-> This feature was introduced in EF Core 5.0. It only works when using `Include`. [This issue](https://github.com/dotnet/efcore/issues/21234) is tracking support for split query when loading related data in projection without `Include`.
+> This feature was introduced in EF Core 5.0, where it only worked when using `Include`. EF Core 6.0 added support for split queries when loading related data in projections, without `Include`.
 
 EF allows you to specify that a given LINQ query should be *split* into multiple SQL queries. Instead of JOINs, split queries generate an additional SQL query for each included collection navigation: