From b84ba5031c942d389bdbcdd343efbd772e6c8101 Mon Sep 17 00:00:00 2001 From: Smit Patel Date: Thu, 9 Jul 2020 10:29:39 -0700 Subject: [PATCH] Get rid of some future warnings --- .../core/miscellaneous/cli/dotnet.md | 119 +++++++++--------- .../core/modeling/entity-properties.md | 18 +-- .../core/what-is-new/ef-core-5.0/plan.md | 23 ++-- 3 files changed, 82 insertions(+), 78 deletions(-) diff --git a/entity-framework/core/miscellaneous/cli/dotnet.md b/entity-framework/core/miscellaneous/cli/dotnet.md index dd276f920e..b8f8ba53aa 100644 --- a/entity-framework/core/miscellaneous/cli/dotnet.md +++ b/entity-framework/core/miscellaneous/cli/dotnet.md @@ -121,12 +121,10 @@ Entity Framework Core .NET Command-line Tools 2.1.3-rtm-32065 ``` - ## Updating the tools Use `dotnet tool update --global dotnet-ef` to update the global tools to the latest available version, if you have the tools installed locally in your project use `dotnet tool update dotnet-ef`. Install a specific version by appending `--version ` to your command. See the [Update](/dotnet/core/tools/dotnet-tool-update) section of the dotnet tool documentation for more details. - ## Using the tools Before using the tools, you might have to create a startup project or set the environment. @@ -158,19 +156,19 @@ To specify the environment for ASP.NET Core projects, set the **ASPNETCORE_ENVIR ## Common options -| | Option | Description | -|:------------------|:----------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| | `--json` | Show JSON output. | -| `-c` | `--context ` | The `DbContext` class to use. Class name only or fully qualified with namespaces. If this option is omitted, EF Core will find the context class. If there are multiple context classes, this option is required. | -| `-p` | `--project ` | Relative path to the project folder of the target project. Default value is the current folder. | -| `-s` | `--startup-project ` | Relative path to the project folder of the startup project. Default value is the current folder. | -| | `--framework ` | The [Target Framework Moniker](/dotnet/standard/frameworks#supported-target-framework-versions) for the [target framework](/dotnet/standard/frameworks). Use when the project file specifies multiple target frameworks, and you want to select one of them. | -| | `--configuration ` | The build configuration, for example: `Debug` or `Release`. | -| | `--runtime ` | The identifier of the target runtime to restore packages for. For a list of Runtime Identifiers (RIDs), see the [RID catalog](/dotnet/core/rid-catalog). | -| `-h` | `--help` | Show help information. | -| `-v` | `--verbose` | Show verbose output. | -| | `--no-color` | Don't colorize output. | -| | `--prefix-output` | Prefix output with level. | +| Option | Short | Description | +|:-----------------------------------------------|:------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--json` | | Show JSON output. | +| `--context ` | `-c` | The `DbContext` class to use. Class name only or fully qualified with namespaces. If this option is omitted, EF Core will find the context class. If there are multiple context classes, this option is required. | +| `--project ` | `-p` | Relative path to the project folder of the target project. Default value is the current folder. | +| `--startup-project ` | `-s` | Relative path to the project folder of the startup project. Default value is the current folder. | +| `--framework ` | | The [Target Framework Moniker](/dotnet/standard/frameworks#supported-target-framework-versions) for the [target framework](/dotnet/standard/frameworks). Use when the project file specifies multiple target frameworks, and you want to select one of them. | +| `--configuration ` | | The build configuration, for example: `Debug` or `Release`. | +| `--runtime ` | | The identifier of the target runtime to restore packages for. For a list of Runtime Identifiers (RIDs), see the [RID catalog](/dotnet/core/rid-catalog). | +| `--help` | `-h` | Show help information. | +| `--verbose` | `-v` | Show verbose output. | +| `--no-color` | | Don't colorize output. | +| `--prefix-output` | | Prefix output with level. | ## dotnet ef database drop @@ -178,10 +176,10 @@ Drops the database. Options: -| | Option | Description | -|:------------------|:-------------------------|:---------------------------------------------------------| -| `-f` | `--force` | Don't confirm. | -| | `--dry-run` | Show which database would be dropped, but don't drop it. | +| Option | Short | Description | +|:-------------------------|:------------------|:---------------------------------------------------------| +| `--force` | `-f` | Don't confirm. | +| `--dry-run` | | Show which database would be dropped, but don't drop it. | ## dotnet ef database update @@ -189,16 +187,15 @@ Updates the database to the last migration or to a specified migration. Arguments: -| Argument | Description | -|:--------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `` | The target migration. Migrations may be identified by name or by ID. The number 0 is a special case that means *before the first migration* and causes all migrations to be reverted. If no migration is specified, the command defaults to the last migration. | +| Argument | Description | +|:---------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `` | The target migration. Migrations may be identified by name or by ID. The number 0 is a special case that means *before the first migration* and causes all migrations to be reverted. If no migration is specified, the command defaults to the last migration. | Options: -| | Option | Description | -|:------------------|:-------------------------|:---------------------------------------------------------| -| | `--connection ` | The connection string to the database. Defaults to the one specified in `AddDbContext` or `OnConfiguring`. (Available from EF Core 5.0.0 onwards.) | - +| Option | Description | +|:------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------| +| `--connection ` | The connection string to the database. Defaults to the one specified in `AddDbContext` or `OnConfiguring`. (Available from EF Core 5.0.0 onwards.) | The following examples update the database to a specified migration. The first uses the migration name and the second uses the migration ID and a specified connection: @@ -221,26 +218,26 @@ Generates code for a `DbContext` and entity types for a database. In order for t Arguments: -| Argument | Description | -|:---------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `` | The connection string to the database. For ASP.NET Core 2.x projects, the value can be *name=\*. In that case the name comes from the configuration sources that are set up for the project. | -| `` | The provider to use. Typically this is the name of the NuGet package, for example: `Microsoft.EntityFrameworkCore.SqlServer`. | +| Argument | Description | +|:----------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `` | The connection string to the database. For ASP.NET Core 2.x projects, the value can be *name=\*. In that case the name comes from the configuration sources that are set up for the project. | +| `` | The provider to use. Typically this is the name of the NuGet package, for example: `Microsoft.EntityFrameworkCore.SqlServer`. | Options: -| | Option | Description | -|:----------------|:-----------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `-d` | `--data-annotations` | Use attributes to configure the model (where possible). If this option is omitted, only the fluent API is used. | -| `-c` | `--context ` | The name of the `DbContext` class to generate. | -| | `--context-dir ` | The directory to put the `DbContext` class file in. Paths are relative to the project directory. Namespaces are derived from the folder names. | -| | `--context-namespace ` | The namespace to use for the generated `DbContext` class. Note: overrides `--namespace`. (Available from EF Core 5.0.0 onwards.) | -| `-f` | `--force` | Overwrite existing files. | -| `-o` | `--output-dir ` | The directory to put entity class files in. Paths are relative to the project directory. | -| `-n` | `--namespace ` | The namespace to use for all generated classes. Defaults to generated from the root namespace and the output directory. (Available from EF Core 5.0.0 onwards.) | -| | `--schema ...` | The schemas of tables to generate entity types for. To specify multiple schemas, repeat `--schema` for each one. If this option is omitted, all schemas are included. | -| `-t` | `--table `... | The tables to generate entity types for. To specify multiple tables, repeat `-t` or `--table` for each one. If this option is omitted, all tables are included. | -| | `--use-database-names` | Use table and column names exactly as they appear in the database. If this option is omitted, database names are changed to more closely conform to C# name style conventions. | -| | `--no-onconfiguring` | Suppresses generation of the `OnConfiguring` method in the generated `DbContext` class. (Available from EF Core 5.0.0 onwards.) | +| Option | Short | Description | +|:-----------------------------------------|:------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--data-annotations` | `-d` | Use attributes to configure the model (where possible). If this option is omitted, only the fluent API is used. | +| `--context ` | `-c` | The name of the `DbContext` class to generate. | +| `--context-dir ` | | The directory to put the `DbContext` class file in. Paths are relative to the project directory. Namespaces are derived from the folder names. | +| `--context-namespace ` | | The namespace to use for the generated `DbContext` class. Note: overrides `--namespace`. (Available from EFCore 5.0.0 onwards.) | +| `--force` | `-f` | Overwrite existing files. | +| `--output-dir ` | `-o` | The directory to put entity class files in. Paths are relative to the project directory. | +| `--namespace ` | `-n` | The namespace to use for all generated classes. Defaults to generated from the root namespace and the output directory. (Available from EFCore 5.0.0 onwards.) | +| `--schema ...` | | The schemas of tables to generate entity types for. To specify multiple schemas, repeat `--schema` for each one. If this option is omitted, all schemas are included. | +| `--table `... | `-t` | The tables to generate entity types for. To specify multiple tables, repeat `-t` or `--table` for each one. If this option is omitted, all tables are included. | +| `--use-database-names` | | Use table and column names exactly as they appear in the database. If this option is omitted, database names are changed to more closely conform to C# name style conventions. | +| `--no-onconfiguring` | | Suppresses generation of the `OnConfiguring` method in the generated `DbContext` class. (Available from EFCore 5.0.0 onwards.) | The following example scaffolds all schemas and tables and puts the new files in the *Models* folder. @@ -260,16 +257,16 @@ Adds a new migration. Arguments: -| Argument | Description | -|:---------|:---------------------------| -| `` | The name of the migration. | +| Argument | Description | +|:----------------------|:---------------------------| +| `` | The name of the migration. | Options: -| | Option | Description | -|:------------------|:-----------------------------------|:-----------------------------------------------------------------------------------------------------------------| -| `-o` | `--output-dir ` | The directory use to output the files. Paths are relative to the target project directory. Defaults to "Migrations". | -| `-n` | `--namespace ` | The namespace to use for the generated classes. Defaults to generated from the output directory. (Available from EF Core 5.0.0 onwards.) | +| Option | Short | Description | +|:---------------------------------------|:------------------|:----------------------------------------------------------------------------------------------------------------------------------------| +| `--output-dir ` | `-o` | The directory use to output the files. Paths are relative to the target project directory. Defaults to "Migrations". | +| `--namespace ` | `-n` | The namespace to use for the generated classes. Defaults to generated from the output directory. (Available from EFCore 5.0.0 onwards.) | ## dotnet ef migrations list @@ -281,9 +278,9 @@ Removes the last migration (rolls back the code changes that were done for the m Options: -| | Option | Description | -|:------------------|:----------|:--------------------------------------------------------------------------------| -| `-f` | `--force` | Revert the migration (roll back the changes that were applied to the database). | +| Option | Short | Description | +|:-----------------------|:------------------|:--------------------------------------------------------------------------------| +| `--force` | `-f` | Revert the migration (roll back the changes that were applied to the database). | ## dotnet ef migrations script @@ -291,17 +288,17 @@ Generates a SQL script from migrations. Arguments: -| Argument | Description | -|:---------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `` | The starting migration. Migrations may be identified by name or by ID. The number 0 is a special case that means *before the first migration*. Defaults to 0. | -| `` | The ending migration. Defaults to the last migration. | +| Argument | Description | +|:----------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `` | The starting migration. Migrations may be identified by name or by ID. The number 0 is a special case that means *before the first migration*. Defaults to 0. | +| `` | The ending migration. Defaults to the last migration. | Options: -| | Option | Description | -|:------------------|:------------------|:-------------------------------------------------------------------| -| `-o` | `--output ` | The file to write the script to. | -| `-i` | `--idempotent` | Generate a script that can be used on a database at any migration. | +| Option | Short | Description | +|:-------------------------------|:------------------|:-------------------------------------------------------------------| +| `--output ` | `-o` | The file to write the script to. | +| `--idempotent` | `-i` | Generate a script that can be used on a database at any migration. | The following example creates a script for the InitialCreate migration: diff --git a/entity-framework/core/modeling/entity-properties.md b/entity-framework/core/modeling/entity-properties.md index f6b9226602..2e2dd9d996 100644 --- a/entity-framework/core/modeling/entity-properties.md +++ b/entity-framework/core/modeling/entity-properties.md @@ -30,7 +30,7 @@ Specific properties can be excluded as follows: By convention, when using a relational database, entity properties are mapped to table columns having the same name as the property. -If you prefer to configure your columns with different names, you can do so as following: +If you prefer to configure your columns with different names, you can do so as following code snippet: ### [Data Annotations](#tab/data-annotations) @@ -48,7 +48,7 @@ When using a relational database, the database provider selects a data type base For example, SQL Server maps `DateTime` properties to `datetime2(7)` columns, and `string` properties to `nvarchar(max)` columns (or to `nvarchar(450)` for properties that are used as a key). -You can also configure your columns to specify an exact data type for a column. For example the following code configures `Url` as a non-unicode string with maximum length of `200` and `Rating` as decimal with precision of `5` and scale of `2`: +You can also configure your columns to specify an exact data type for a column. For example, the following code configures `Url` as a non-unicode string with maximum length of `200` and `Rating` as decimal with precision of `5` and scale of `2`: ### [Data Annotations](#tab/data-annotations) @@ -81,7 +81,7 @@ In the following example, configuring a maximum length of 500 will cause a colum ### Precision and Scale -Starting with EFCore 5.0, you can use fluent API to configure the precision and scale. It tells the database provider how much storage is needed for a given column. It only applies to data types where the provider allows the precision and scale to vary - usually just `decimal` and `DateTime`. +Starting with EFCore 5.0, you can use fluent API to configure the precision and scale. It tells the database provider how much storage is needed for a given column. It only applies to data types where the provider allows the precision and scale to vary - usually `decimal` and `DateTime`. For `decimal` properties, precision defines the maximum number of digits needed to express any value the column will contain, and scale defines the maximum number of decimal places needed. For `DateTime` properties, precision defines the maximum number of digits needed to express fractions of seconds, and scale is not used. @@ -90,6 +90,10 @@ For `decimal` properties, precision defines the maximum number of digits needed In the following example, configuring the `Score` property to have precision 14 and scale 2 will cause a column of type `decimal(14,2)` to be created on SQL Server, and configuring the `LastUpdated` property to have precision 3 will cause a column of type `datetime2(3)`: +#### [Data Annotations](#tab/data-annotations) + +Currently not possible to use data annotations to configure. + #### [Fluent API](#tab/fluent-api) [!code-csharp[Main](../../../samples/core/Modeling/FluentAPI/PrecisionAndScale.cs?name=PrecisionAndScale&highlight=3-9)] @@ -109,8 +113,8 @@ By convention, a property whose .NET type can contain null will be configured as C# 8 introduced a new feature called [nullable reference types](/dotnet/csharp/tutorials/nullable-reference-types), which allows reference types to be annotated, indicating whether it is valid for them to contain null or not. This feature is disabled by default, and if enabled, it modifies EF Core's behavior in the following way: -* If nullable reference types are disabled (the default), all properties with .NET reference types are configured as optional by convention (e.g. `string`). -* If nullable reference types are enabled, properties will be configured based on the C# nullability of their .NET type: `string?` will be configured as optional, whereas `string` will be configured as required. +* If nullable reference types are disabled (the default), all properties with .NET reference types are configured as optional by convention (for example, `string`). +* If nullable reference types are enabled, properties will be configured based on the C# nullability of their .NET type: `string?` will be configured as optional, but `string` will be configured as required. The following example shows an entity type with required and optional properties, with the nullable reference feature disabled (the default) and enabled: @@ -150,10 +154,10 @@ A property that would be optional by convention can be configured to be required > [!NOTE] > This feature is introduced in EF Core 5.0. -A collation can be defined on text columns, determining how they are compared and ordered. For example, the following configures a SQL Server column to be case-insensitive: +A collation can be defined on text columns, determining how they are compared and ordered. For example, the following code snippet configures a SQL Server column to be case-insensitive: [!code-csharp[Main](../../../samples/core/Miscellaneous/Collations/Program.cs?range=42-43)] If all columns in a database need to use a certain collation, define the collation at the database level instead. -General information about EF Core support for collations can be found in the [collation documentation page](xref:core/miscellaneous/collations-and-case-sensitivity). \ No newline at end of file +General information about EF Core support for collations can be found in the [collation documentation page](xref:core/miscellaneous/collations-and-case-sensitivity). diff --git a/entity-framework/core/what-is-new/ef-core-5.0/plan.md b/entity-framework/core/what-is-new/ef-core-5.0/plan.md index ddbce13847..bbe4ac45fb 100644 --- a/entity-framework/core/what-is-new/ef-core-5.0/plan.md +++ b/entity-framework/core/what-is-new/ef-core-5.0/plan.md @@ -9,10 +9,12 @@ uid: core/what-is-new/ef-core-5.0/plan As described in the [planning process](xref:core/what-is-new/release_planning), we have gathered input from stakeholders into a tentative plan for the EF Core 5.0 release. -> [!IMPORTANT] +> [!IMPORTANT] > This plan is still a work-in-progress. Nothing here is a commitment. This plan is a starting point that will evolve as we learn more. Some things not currently planned for 5.0 may get pulled in. Some things currently planned for 5.0 may get punted out. -### Version number and release date. +## General information + +### Version number and release date EF Core 5.0 is currently scheduled for release at [the same time as .NET 5.0](https://devblogs.microsoft.com/dotnet/introducing-net-5/). The version "5.0" was chosen to align with .NET 5.0. @@ -105,9 +107,9 @@ EF Core 3.0 changed the default behavior to create a single SQL query for a give This caused large performance regressions for queries that use Include for multiple collections. In EF Core 5.0, we are retaining the new default behavior. -However, EF Core 5.0 will now allow generation of multiple queries for collection Includes where having a single query is causing bad performance.. +However, EF Core 5.0 will now allow generation of multiple queries for collection Includes where having a single query is causing bad performance. -## Rationalize ToTable, ToQuery, ToView, FromSql, etc. +## Rationalize ToTable, ToQuery, ToView, FromSql, etc Lead developers: @maumar and @smitpatel @@ -160,7 +162,7 @@ We want to deliver a better experience here that allows an easy way to migrate t The result is likely to be many small improvements in EF Core (for example, better Migrations on SQLite), together with guidance and longer-term collaborations with other teams to improve end-to-end experiences that go beyond just EF. -## EF Core platforms experience +## EF Core platforms experience Lead developers: @roji and @bricelam @@ -242,10 +244,11 @@ T-shirt size: L Status: In-progress We are already in the process of updating documentation for the 3.0 and 3.1 releases. We are also working on: - * An overhaul of the getting started docs to make them more approachable/easier to follow - * Reorganization of docs to make things easier to find and to add cross-references - * Adding more details and clarifications to existing docs - * Updating the samples and adding more examples + +* An overhaul of the getting started docs to make them more approachable/easier to follow +* Reorganization of docs to make things easier to find and to add cross-references +* Adding more details and clarifications to existing docs +* Updating the samples and adding more examples ## Fixing bugs @@ -281,6 +284,6 @@ These are bug fixes and enhancements that are **not** currently scheduled for th In addition, we always consider the [most voted issues](https://github.com/dotnet/efcore/issues?q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc) when planning. Cutting any of these issues from a release is always painful, but we do need a realistic plan for the resources we have. -## Feedback +## Suggestions Your feedback on planning is important. The best way to indicate the importance of an issue is to vote (thumbs-up) for that issue on GitHub. This data will then feed into the [planning process](xref:core/what-is-new/release_planning) for the next release.