Document C# 8 nullable reference types #1709

roji · 2019-09-09T14:35:07Z

Closes #1654
Closes #1655

entity-framework/core/miscellaneous/nullable-reference-types.md

roji · 2019-09-09T14:52:14Z

So there's a new "nullable reference types" under "miscellaneous" (which is accessible under "fundamentals" in the site TOC, we're changing that right?), plus some additional changes in other pages.

In some cases the code sample shown in the doc page is huge, anyone know if we can show a subset of lines (not highlight)?
The sample depends on 3.0.0-preview9, we'll need to update that when we RTM

divega

Some suggestions.

entity-framework/core/managing-schemas/scaffolding.md

entity-framework/core/modeling/required-optional.md

divega · 2019-09-12T11:47:22Z

entity-framework/core/miscellaneous/nullable-reference-types.md

@@ -0,0 +1,64 @@
+---


Add this file to the ToC?

Will do, but was hesitating where to put it. As it's cross-cutting (modeling, querying...), it seems like it would fit well in a Miscellaneous section - see #1726. Will add it under Fundamentals for now.

Oh, you are right, and this got me thinking... Whether we add or not an article focused on nullable reference types to the EF Core docs, the main thing we should be focusing on is making sure we enhance existing pages with information relevant to nullable reference types.

For example:

The main place information on nullable reference types is in core/modeling/required-optional article. Adding the information there is coherent with the fact that form the EF Core perspective, there is a single concept of nullability/requiredness, and we want to treat nullable value types, nullable reference types and the [Required] attribute all the same as much as possible.

The part about initialization belongs in some topic about modeling entity properties.

Though the comments specific to the initialization of DbSets belongs probably in working with DbContext.

Understandably nullable reference types are new and us and our customers have learned a lot about them very recently, but if we make nullable reference types too special in the EF Core docs, I don't think that is great. Long term NRT should become routine, more or less just like using Nullable<T> is routine today, and we don't maintain a dedicated page about Nullable<T> in the EF Core docs.

I agree that we should add NRT-related notes to the property modeling articles and DbSet/DbContext articles. At the same time, at least in the foreseeable future NRTs is a new feature and we should probably have a dedicated page for migrating to it, much like we have an EF6->Core migration page - just to concentrate all the relevant information in a single place for people thinking about moving and wanting to understand all the consequences.

Some links back and forth are OK, and if we end up with some duplication I don't think it's the end of the world either...

If that sounds good I'll work on refactoring the information into the specific articles too.

Yeah, sounds good if you are convinced. Though I prefer the dedicated page to be mostly links to the other ones. As you say, it is a cross cutting feature. We need the information to be included where it matters. Also, new features are supposed to go in “what’s new”, and aspects of migrating to new versions can go to an article about upgrading to 3.0. We have an issue for creating the later.

entity-framework/core/miscellaneous/nullable-reference-types.md

divega · 2019-09-12T11:50:15Z

entity-framework/core/miscellaneous/nullable-reference-types.md

+
+This page introduces EF Core's support fo nullable reference types, and describes best practices for working with them.
+
+## Required and optional properties


Consider only including a short paragraph and a link to the required-optional article rather than entirely duplicating its contents here.

OK. Note that means we'd have links going both ways, but it seems fine.

entity-framework/core/managing-schemas/scaffolding.md

divega · 2019-09-16T00:34:42Z

entity-framework/core/miscellaneous/nullable-reference-types.md

@@ -0,0 +1,64 @@
+---


Oh, you are right, and this got me thinking... Whether we add or not an article focused on nullable reference types to the EF Core docs, the main thing we should be focusing on is making sure we enhance existing pages with information relevant to nullable reference types.

For example:

The main place information on nullable reference types is in core/modeling/required-optional article. Adding the information there is coherent with the fact that form the EF Core perspective, there is a single concept of nullability/requiredness, and we want to treat nullable value types, nullable reference types and the [Required] attribute all the same as much as possible.

The part about initialization belongs in some topic about modeling entity properties.

Though the comments specific to the initialization of DbSets belongs probably in working with DbContext.

Understandably nullable reference types are new and us and our customers have learned a lot about them very recently, but if we make nullable reference types too special in the EF Core docs, I don't think that is great. Long term NRT should become routine, more or less just like using Nullable<T> is routine today, and we don't maintain a dedicated page about Nullable<T> in the EF Core docs.

entity-framework/core/miscellaneous/nullable-reference-types.md

divega · 2019-09-16T01:14:53Z

entity-framework/core/miscellaneous/nullable-reference-types.md

+> [!NOTE]
+> Exercise caution when enabling nullable reference types on an existing project: reference type properties which were previously configured as optional will now be configured as required, unless they are explicitly annotated to be nullable. When managing a relational database schema, this may cause migrations to be generated which alter the database column's nullability.
+
+## DbContext and DbSet


This entire section would probably go into core/miscellaneous/configuring-dbcontext. The only problem is that we don't have there the basics of adding DbSets to include a type in the model.

I find that page a bit confusing and not necessarily suitable for newcomers (e.g. it starts with "Design-time DbContext configuration" which seems very specific and somewhat advanced). I think core/modeling/index could be a better candidate. But see also my comments above on a specific nullability page etc.

Yes, I agree the configuring DbContext page can be improved, reorganized, and that some of the more basic/introductory content is currently missing from it. However it exists for good reasons and many of the more advanced things including in it are there because they happen to be too common pitfalls that we have been forced to document.

If the root modeling page is a better candidate to explain how the DbSets on the DbContext contribute to the model, I guess the configuring DbContext page should have a paragraph and a link to that page too.

entity-framework/core/miscellaneous/nullable-reference-types.md

divega · 2019-09-19T19:15:48Z

entity-framework/core/miscellaneous/nullable-reference-types.md

+> [!NOTE]
+> Exercise caution when enabling nullable reference types on an existing project: reference type properties which were previously configured as optional will now be configured as required, unless they are explicitly annotated to be nullable. When managing a relational database schema, this may cause migrations to be generated which alter the database column's nullability.
+
+## DbContext and DbSet


Yes, I agree the configuring DbContext page can be improved, reorganized, and that some of the more basic/introductory content is currently missing from it. However it exists for good reasons and many of the more advanced things including in it are there because they happen to be too common pitfalls that we have been forced to document.

If the root modeling page is a better candidate to explain how the DbSets on the DbContext contribute to the model, I guess the configuring DbContext page should have a paragraph and a link to that page too.

roji · 2019-09-23T09:25:37Z

@divega I've merged your suggestions. I agree that we should integrate NRT information in various relevant pages rather than only in a single page (#1709 (comment)), but that requires a more complete rethinking/restructuring of the docs (interacts with modeling changes in #1669, work on the DbContext page, etc.). So unless you object I suggest we merge this PR as-is - it's sub-optimal but it does provide complete information right away for 3.0. I'll open a separate issue to track introducing NRT information into the other relevant pages, link back and forth etc.

Does that sound OK?

roji · 2019-09-23T09:42:55Z

Note: am working on some further improvements on this PR, especially with regards to the samples.

divega · 2019-09-23T12:33:39Z

Does that sound OK?

I am ok with this plan.

Closes #1654 Closes #1655

roji · 2019-09-23T12:46:48Z

I am ok with this plan.

Thanks @divega! Have made some improvements and will merge.

roji force-pushed the NRT branch 3 times, most recently from bab0353 to 4d01b62 Compare September 9, 2019 14:49

roji commented Sep 9, 2019

View reviewed changes

entity-framework/core/miscellaneous/nullable-reference-types.md Show resolved Hide resolved

divega reviewed Sep 12, 2019

View reviewed changes

divega reviewed Sep 16, 2019

View reviewed changes

roji force-pushed the NRT branch from 1af7710 to f095ca3 Compare September 16, 2019 11:22

divega reviewed Sep 19, 2019

View reviewed changes

roji force-pushed the NRT branch from b67590b to 07e6788 Compare September 23, 2019 09:31

roji marked this pull request as ready for review September 23, 2019 09:33

roji force-pushed the NRT branch 6 times, most recently from 933d29e to 4406495 Compare September 23, 2019 12:32

divega approved these changes Sep 23, 2019

View reviewed changes

roji force-pushed the NRT branch 2 times, most recently from 61543ee to e9f3d09 Compare September 23, 2019 12:41

Document C# 8 nullable reference types

e00d498

Closes #1654 Closes #1655

roji force-pushed the NRT branch from e9f3d09 to e00d498 Compare September 23, 2019 12:43

roji merged commit 0888e34 into master Sep 23, 2019

This was referenced Sep 23, 2019

Integrate information about nullable reference types in relevant topics #1762

Open

Add NRT page to TOC #1763

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document C# 8 nullable reference types #1709

Document C# 8 nullable reference types #1709

roji commented Sep 9, 2019

roji commented Sep 9, 2019

divega left a comment

divega Sep 12, 2019

roji Sep 12, 2019

divega Sep 16, 2019

roji Sep 16, 2019

divega Sep 16, 2019 •

edited

Loading

divega Sep 12, 2019

roji Sep 12, 2019

divega Sep 16, 2019

divega Sep 16, 2019

roji Sep 16, 2019

divega Sep 19, 2019

divega Sep 19, 2019

roji commented Sep 23, 2019

roji commented Sep 23, 2019

divega commented Sep 23, 2019

roji commented Sep 23, 2019


		This page introduces EF Core's support fo nullable reference types, and describes best practices for working with them.

		## Required and optional properties

Document C# 8 nullable reference types #1709

Document C# 8 nullable reference types #1709

Conversation

roji commented Sep 9, 2019

roji commented Sep 9, 2019

divega left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

divega Sep 16, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

roji commented Sep 23, 2019

roji commented Sep 23, 2019

divega commented Sep 23, 2019

roji commented Sep 23, 2019

divega Sep 16, 2019 •

edited

Loading