diff --git a/entity-framework/core/change-tracking/explicit-tracking.md b/entity-framework/core/change-tracking/explicit-tracking.md index b8d5b2a2f7..d2c8336211 100644 --- a/entity-framework/core/change-tracking/explicit-tracking.md +++ b/entity-framework/core/change-tracking/explicit-tracking.md @@ -37,7 +37,7 @@ The web application must now re-attach these entities so that they are again tra > [!TIP] > Attaching entities to the _same DbContext instance_ that they were queried from should not normally be needed. Do not routinely perform a no-tracking query and then attach the returned entities to the same context. This will be slower than using a tracking query, and may also result in issues such as missing shadow property values, making it harder to get right. -### Generated verses explicit key values +### Generated versus explicit key values By default, integer and GUID [key properties](xref:core/modeling/keys) are configured to use [automatically generated key values](xref:core/modeling/generated-properties). This has a **major advantage for change tracking: an unset key value indicates that the entity is "new"**. By "new", we mean that it has not yet been inserted into the database. diff --git a/entity-framework/core/change-tracking/miscellaneous.md b/entity-framework/core/change-tracking/miscellaneous.md index 11da3d3f41..c3e2406372 100644 --- a/entity-framework/core/change-tracking/miscellaneous.md +++ b/entity-framework/core/change-tracking/miscellaneous.md @@ -16,7 +16,7 @@ This document covers miscellaneous features and scenarios involving change track > [!TIP] > You can run and debug into all the code in this document by [downloading the sample code from GitHub](https://github.com/dotnet/EntityFramework.Docs/tree/master/samples/core/ChangeTracking/AdditionalChangeTrackingFeatures). -## Add verses AddAsync +## `Add` versus `AddAsync` Entity Framework Core (EF Core) provides async methods whenever using that method may result in a database interaction. Synchronous methods are also provided to avoid overhead when using databases that do not support high performance asynchronous access. @@ -24,16 +24,16 @@ Entity Framework Core (EF Core) provides async methods whenever using that metho Other similar methods like `Update`, `Attach`, and `Remove` do not have async overloads because they never generate new key values, and hence never need to access the database. -## AddRange, UpdateRange, AttachRange, and RemoveRange +## `AddRange`, `UpdateRange`, `AttachRange`, and `RemoveRange` - and provide alternate versions of `Add`, `Update`, `Attach`, and `Remove` that accept multiple instances in a single call. These methods are called `AddRange`, `UpdateRange`, `AttachRange`, and `RemoveRange` respectively. + and provide alternate versions of `Add`, `Update`, `Attach`, and `Remove` that accept multiple instances in a single call. These methods are , , , and respectively. These methods are provided as a convenience. Using a "range" method has the same functionality as multiple calls to the equivalent non-range method. There is no significant performance difference between the two approaches. > [!NOTE] -> This is different from EF6, where AddRange and Add both automatically called DetectChanges, but calling Add multiple times caused DetectChanges to be called multiple times instead of once. This made AddRange more efficient in EF6. In EF Core, neither of these methods automatically call DetectChanges. +> This is different from EF6, where `AddRange` and `Add` both automatically called `DetectChanges`, but calling `Add` multiple times caused DetectChanges to be called multiple times instead of once. This made `AddRange` more efficient in EF6. In EF Core, neither of these methods automatically call `DetectChanges`. -## DbContext verses DbSet methods +## DbContext versus DbSet methods Many methods, including `Add`, `Update`, `Attach`, and `Remove`, have implementations on both and . These methods have _exactly the same behavior_ for normal entity types. This is because the CLR type of the entity is mapped onto one and only one entity type in the EF Core model. Therefore, the CLR type fully defines where the entity fits in the model, and so the DbSet to use can be determined implicitly. @@ -84,14 +84,14 @@ Shared-type entity types are used by default for the join entities in many-to-ma context.SaveChanges(); --> -[!code-csharp[DbContext_verses_DbSet_methods_1](../../../samples/core/ChangeTracking/AdditionalChangeTrackingFeatures/Samples.cs?name=DbContext_verses_DbSet_methods_1)] +[!code-csharp[DbContext_versus_DbSet_methods_1](../../../samples/core/ChangeTracking/AdditionalChangeTrackingFeatures/Samples.cs?name=DbContext_versus_DbSet_methods_1)] Notice that is used to create a DbSet for the `PostTag` entity type. This DbSet can then be used to call `Add` with the new join entity instance. > [!IMPORTANT] > The CLR type used for join entity types by convention may change in future releases to improve performance. Do not depend on any specific join entity type unless it has been explicitly configured as is done for `Dictionary` in the code above. -## Property verses field access +## Property versus field access Starting with EF Core 3.0, access to entity properties uses the backing field of the property by default. This is efficient and avoids triggering side effects from calling property getters and setters. For example, this is how lazy-loading is able to avoid triggering infinite loops. See [Backing Fields](xref:core/modeling/backing-field) for more information on configuring backing fields in the model. diff --git a/entity-framework/core/cli/dotnet.md b/entity-framework/core/cli/dotnet.md index 2bbc5518d0..8ebf812c06 100644 --- a/entity-framework/core/cli/dotnet.md +++ b/entity-framework/core/cli/dotnet.md @@ -123,7 +123,7 @@ dotnet ef database update -- --environment Production Starting in EF Core 5.0, any additional arguments are passed to the application. -## dotnet ef database drop +## `dotnet ef database drop` Deletes the database. @@ -136,7 +136,7 @@ Options: The [common options](#common-options) are listed above. -## dotnet ef database update +## `dotnet ef database update` Updates the database to the last migration or to a specified migration. @@ -161,19 +161,19 @@ dotnet ef database update InitialCreate dotnet ef database update 20180904195021_InitialCreate --connection your_connection_string ``` -## dotnet ef dbcontext info +## `dotnet ef dbcontext info` Gets information about a `DbContext` type. The [common options](#common-options) are listed above. -## dotnet ef dbcontext list +## `dotnet ef dbcontext list` Lists available `DbContext` types. The [common options](#common-options) are listed above. -## dotnet ef dbcontext scaffold +## `dotnet ef dbcontext scaffold` Generates code for a `DbContext` and entity types for a database. In order for this command to generate an entity type, the database table must have a primary key. @@ -222,7 +222,7 @@ dotnet user-secrets set ConnectionStrings:Blogging "Data Source=(localdb)\MSSQLL dotnet ef dbcontext scaffold Name=ConnectionStrings:Blogging Microsoft.EntityFrameworkCore.SqlServer ``` -## dotnet ef dbcontext script +## `dotnet ef dbcontext script` Generates a SQL script from the DbContext. Bypasses any migrations. Added in EF Core 3.0. @@ -234,7 +234,7 @@ Options: The [common options](#common-options) are listed above. -## dotnet ef migrations add +## `dotnet ef migrations add` Adds a new migration. @@ -253,7 +253,7 @@ Options: The [common options](#common-options) are listed above. -## dotnet ef migrations list +## `dotnet ef migrations list` Lists available migrations. @@ -266,7 +266,7 @@ Options: The [common options](#common-options) are listed above. -## dotnet ef migrations remove +## `dotnet ef migrations remove` Removes the last migration (rolls back the code changes that were done for the migration). @@ -278,7 +278,7 @@ Options: The [common options](#common-options) are listed above. -## dotnet ef migrations script +## `dotnet ef migrations script` Generates a SQL script from migrations. diff --git a/entity-framework/ef6/fundamentals/configuring/code-based.md b/entity-framework/ef6/fundamentals/configuring/code-based.md index da997c5108..0bfe2f5aa1 100644 --- a/entity-framework/ef6/fundamentals/configuring/code-based.md +++ b/entity-framework/ef6/fundamentals/configuring/code-based.md @@ -13,20 +13,20 @@ Configuration for an Entity Framework application can be specified in a config f Configuration in a config file is described in a [separate article](xref:ef6/fundamentals/configuring/config-file). The config file takes precedence over code-based configuration. In other words, if a configuration option is set in both code and in the config file, then the setting in the config file is used. -## Using DbConfiguration +## Using `DbConfiguration` -Code-based configuration in EF6 and above is achieved by creating a subclass of System.Data.Entity.Config.DbConfiguration. The following guidelines should be followed when subclassing DbConfiguration: +Code-based configuration in EF6 and above is achieved by creating a subclass of System.Data.Entity.Config.`DbConfiguration`. The following guidelines should be followed when subclassing `DbConfiguration`: -- Create only one DbConfiguration class for your application. This class specifies app-domain wide settings. -- Place your DbConfiguration class in the same assembly as your DbContext class. (See the *Moving DbConfiguration* section if you want to change this.) -- Give your DbConfiguration class a public parameterless constructor. -- Set configuration options by calling protected DbConfiguration methods from within this constructor. +- Create only one `DbConfiguration` class for your application. This class specifies app-domain wide settings. +- Place your `DbConfiguration` class in the same assembly as your `DbContext` class. (See the *Moving `DbConfiguration`* section if you want to change this.) +- Give your `DbConfiguration` class a public parameterless constructor. +- Set configuration options by calling protected `DbConfiguration` methods from within this constructor. Following these guidelines allows EF to discover and use your configuration automatically by both tooling that needs to access your model and when your application is run. ## Example -A class derived from DbConfiguration might look like this: +A class derived from `DbConfiguration` might look like this: ``` csharp using System.Data.Entity; @@ -48,11 +48,11 @@ namespace MyNamespace This class sets up EF to use the SQL Azure execution strategy - to automatically retry failed database operations - and to use Local DB for databases that are created by convention from Code First. -## Moving DbConfiguration +## Moving `DbConfiguration` -There are cases where it is not possible to place your DbConfiguration class in the same assembly as your DbContext class. For example, you may have two DbContext classes each in different assemblies. There are two options for handling this. +There are cases where it is not possible to place your `DbConfiguration` class in the same assembly as your `DbContext` class. For example, you may have two `DbContext` classes each in different assemblies. There are two options for handling this. -The first option is to use the config file to specify the DbConfiguration instance to use. To do this, set the codeConfigurationType attribute of the entityFramework section. For example: +The first option is to use the config file to specify the `DbConfiguration` instance to use. To do this, set the codeConfigurationType attribute of the entityFramework section. For example: ``` xml @@ -60,9 +60,9 @@ The first option is to use the config file to specify the DbConfiguration instan ``` -The value of codeConfigurationType must be the assembly and namespace qualified name of your DbConfiguration class. +The value of codeConfigurationType must be the assembly and namespace qualified name of your `DbConfiguration` class. -The second option is to place DbConfigurationTypeAttribute on your context class. For example: +The second option is to place `DbConfigurationTypeAttribute` on your context class. For example: ``` csharp [DbConfigurationType(typeof(MyDbConfiguration))] @@ -71,7 +71,7 @@ public class MyContextContext : DbContext } ``` -The value passed to the attribute can either be your DbConfiguration type - as shown above - or the assembly and namespace qualified type name string. For example: +The value passed to the attribute can either be your `DbConfiguration` type - as shown above - or the assembly and namespace qualified type name string. For example: ``` csharp [DbConfigurationType("MyNamespace.MyDbConfiguration, MyAssembly")] @@ -80,28 +80,28 @@ public class MyContextContext : DbContext } ``` -## Setting DbConfiguration explicitly +## Setting `DbConfiguration` explicitly -There are some situations where configuration may be needed before any DbContext type has been used. Examples of this include: +There are some situations where configuration may be needed before any `DbContext` type has been used. Examples of this include: -- Using DbModelBuilder to build a model without a context -- Using some other framework/utility code that utilizes a DbContext where that context is used before your application context is used +- Using `DbModelBuilder` to build a model without a context +- Using some other framework/utility code that utilizes a `DbContext` where that context is used before your application context is used In such situations EF is unable to discover the configuration automatically and you must instead do one of the following: -- Set the DbConfiguration type in the config file, as described in the *Moving DbConfiguration* section above -- Call the static DbConfiguration.SetConfiguration method during application startup +- Set the `DbConfiguration` type in the config file, as described in the *Moving `DbConfiguration`* section above +- Call the static `DbConfiguration`.SetConfiguration method during application startup -## Overriding DbConfiguration +## Overriding `DbConfiguration` -There are some situations where you need to override the configuration set in the DbConfiguration. This is not typically done by application developers but rather by third party providers and plug-ins that cannot use a derived DbConfiguration class. +There are some situations where you need to override the configuration set in the `DbConfiguration`. This is not typically done by application developers but rather by third party providers and plug-ins that cannot use a derived `DbConfiguration` class. For this, EntityFramework allows an event handler to be registered that can modify existing configuration just before it is locked down. It also provides a sugar method specifically for replacing any service returned by the EF service locator. This is how it is intended to be used: - At app startup (before EF is used) the plug-in or provider should register the event handler method for this event. (Note that this must happen before the application uses EF.) - The event handler makes a call to ReplaceService for every service that needs to be replaced. -For example, to replace IDbConnectionFactory and DbProviderService you would register a handler something like this: +For example, to replace `IDbConnectionFactory` and `DbProviderService` you would register a handler something like this: ``` csharp DbConfiguration.Loaded += (_, a) => @@ -111,10 +111,10 @@ DbConfiguration.Loaded += (_, a) => }; ``` -In the code above MyProviderServices and MyConnectionFactory represent your implementations of the service. +In the code above, `MyProviderServices` and `MyConnectionFactory` represent your implementations of the service. You can also add additional dependency handlers to get the same effect. -Note that you could also wrap DbProviderFactory in this way, but doing so will only affect EF and not uses of the DbProviderFactory outside of EF. For this reason you’ll probably want to continue to wrap DbProviderFactory as you have before. +Note that you could also wrap `DbProviderFactory` in this way, but doing so will only affect EF and not uses of the `DbProviderFactory` outside of EF. For this reason you’ll probably want to continue to wrap `DbProviderFactory` as you have before. -You should also keep in mind the services that you run externally to your application - for example, when running migrations from the Package Manager Console. When you run migrate from the console it will attempt to find your DbConfiguration. However, whether or not it will get the wrapped service depends on where the event handler it registered. If it is registered as part of the construction of your DbConfiguration then the code should execute and the service should get wrapped. Usually this won’t be the case and this means that tooling won’t get the wrapped service. +You should also keep in mind the services that you run externally to your application - for example, when running migrations from the Package Manager Console. When you run migrate from the console it will attempt to find your `DbConfiguration`. However, whether or not it will get the wrapped service depends on where the event handler it registered. If it is registered as part of the construction of your `DbConfiguration` then the code should execute and the service should get wrapped. Usually this won’t be the case and this means that tooling won’t get the wrapped service. diff --git a/samples/core/ChangeTracking/AdditionalChangeTrackingFeatures/Program.cs b/samples/core/ChangeTracking/AdditionalChangeTrackingFeatures/Program.cs index ee89c3854f..41ff74e4c0 100644 --- a/samples/core/ChangeTracking/AdditionalChangeTrackingFeatures/Program.cs +++ b/samples/core/ChangeTracking/AdditionalChangeTrackingFeatures/Program.cs @@ -9,7 +9,7 @@ public static void Main() Console.WriteLine("Samples for _Identity Resolution in EF Core_"); Console.WriteLine(); - Samples.DbContext_verses_DbSet_methods_1(); + Samples.DbContext_versus_DbSet_methods_1(); Samples.Temporary_values_1(); Samples.Temporary_values_2(); diff --git a/samples/core/ChangeTracking/AdditionalChangeTrackingFeatures/Samples.cs b/samples/core/ChangeTracking/AdditionalChangeTrackingFeatures/Samples.cs index 653b64fde3..6c5b8f614f 100644 --- a/samples/core/ChangeTracking/AdditionalChangeTrackingFeatures/Samples.cs +++ b/samples/core/ChangeTracking/AdditionalChangeTrackingFeatures/Samples.cs @@ -8,15 +8,15 @@ namespace Optional { public class Samples { - public static void DbContext_verses_DbSet_methods_1() + public static void DbContext_versus_DbSet_methods_1() { - Console.WriteLine($">>>> Sample: {nameof(DbContext_verses_DbSet_methods_1)}"); + Console.WriteLine($">>>> Sample: {nameof(DbContext_versus_DbSet_methods_1)}"); Console.WriteLine(); Helpers.RecreateCleanDatabase(); Helpers.PopulateDatabase(); - #region DbContext_verses_DbSet_methods_1 + #region DbContext_versus_DbSet_methods_1 using var context = new BlogsContext(); var post = context.Posts.Single(e => e.Id == 3);