{"id":24002,"date":"2019-08-06T13:29:02","date_gmt":"2019-08-06T20:29:02","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/dotnet\/?p=24002"},"modified":"2021-09-29T12:16:32","modified_gmt":"2021-09-29T19:16:32","slug":"try-out-nullable-reference-types","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/dotnet\/try-out-nullable-reference-types\/","title":{"rendered":"Try out Nullable Reference Types"},"content":{"rendered":"<h1 id=\"try-out-nullable-reference-types\">Try out Nullable Reference Types<\/h2>\n<p>With the release of .NET Core 3.0 Preview 7, C# 8.0 is considered &quot;feature complete&quot;. That means that the biggest feature of them all, <a href=\"https:\/\/docs.microsoft.com\/dotnet\/csharp\/nullable-references\">Nullable Reference Types<\/a>, is also locked down behavior-wise for the .NET Core release. It will continue to improve after C# 8.0, but it is now considered stable with the rest of C# 8.0.<\/p>\n<p>At this time, our aim is to collect as much feedback about the process of adopting nullability as possible, catch any issues, and collect feedback on further improvements to the feature that we can do after .NET Core 3.0. This is one of the largest features ever built for C#, and although we&#8217;ve done our best to get things right, we need your help!<\/p>\n<p>It is at this junction that we especially call upon .NET library authors to try out the feature and begin annotating your libraries. We&#8217;d love to hear your feedback and help resolve any issues you come across.<\/p>\n<h2 id=\"familiarize-yourself-with-the-feature\">Familiarize yourself with the feature<\/h2>\n<p>We recommend reading some of the <a href=\"https:\/\/docs.microsoft.com\/dotnet\/csharp\/nullable-references\">Nullable Reference Types documentation<\/a> before getting started with the feature. It covers essentials like:<\/p>\n<ul>\n<li>A conceptual overview<\/li>\n<li>How to specify a nullable reference type<\/li>\n<li>How to control compiler analysis or override compiler analysis<\/li>\n<\/ul>\n<p>If you&#8217;re unfamiliar with these concepts, please give the documentation a quick read before proceeding.<\/p>\n<h2 id=\"turn-on-nullable-reference-types\">Turn on Nullable Reference Types<\/h2>\n<p>The first step in adopting nullability for your library is to turn it on. Here&#8217;s how:<\/p>\n<h3 id=\"make-sure-youre-using-c-80\">Make sure you&#8217;re using C# 8.0<\/h3>\n<p>If your library explicitly targets <code>netcoreapp3.0<\/code>, you&#8217;ll get C# 8.0 by default. When we ship Preview 8, you&#8217;ll get C# 8.0 by default if you target <code>netstandard2.1<\/code> too.<\/p>\n<p>.NET Standard itself doesn&#8217;t have any nullable annotations yet. If you&#8217;re targeting .NET Standard, then you can use multi-targeting for .NET Standard and <code>netcoreapp3.0<\/code>, even if you don&#8217;t need .NET Core specific APIs. The benefit is that the compiler will use the nullable annotations from CoreFX to help you get your own annotations right.<\/p>\n<p>If you cannot update your TFM for some reason, you can set the <code>LangVersion<\/code> explicitly:<\/p>\n<pre><code class=\"language-xml\">&lt;PropertyGroup&gt;\r\n    &lt;LangVersion&gt;8.0&lt;\/LangVersion&gt;\r\n&lt;\/PropertyGroup&gt;\r\n<\/code><\/pre>\n<p>Note that C# 8.0 is not meant for older targets, such as .NET Core 2.x or .NET Framework 4.x. So some additional language features may not work unless you are targeting .NET Core 3.0 or .NET Standard 2.1<\/p>\n<p>From here, we recommend two general approaches to adopting nullability.<\/p>\n<h3 id=\"opt-in-a-project-opt-out-files\">Opt in a project, opt out files<\/h3>\n<p>This approach is best for projects where you&#8217;ll be adding new files over time. The process is straightforward:<\/p>\n<ol>\n<li>\n<p>Apply the following property to your project file:<\/p>\n<pre><code class=\"language-xml\">&lt;PropertyGroup&gt;\r\n    &lt;Nullable&gt;enable&lt;\/Nullable&gt;\r\n&lt;\/PropertyGroup&gt;\r\n<\/code><\/pre>\n<\/li>\n<li>\n<p>Disable nullability in every file for that project by adding this to the top of every existing file in the project:<\/p>\n<pre><code class=\"language-csharp\">#nullable disable\r\n<\/code><\/pre>\n<\/li>\n<li>\n<p>Pick a file, remove the <code>#nullable disable<\/code> directive, and fix the warnings. Repeat until all <code>#nullable disable<\/code> directives are gone.<\/p>\n<\/li>\n<\/ol>\n<p>This approach requires a bit more up front work, but it means that you can continue working in your library while you&#8217;re porting and ensure that any new files are automatically opted-in to nullability. This is the approach we generally recommend, and we are currently using it in <a href=\"https:\/\/github.com\/dotnet\/project-system\/blob\/master\/src\/Directory.Build.props#L28\">some of our own codebases<\/a>.<\/p>\n<p>Note that you can also apply the <code>Nullable<\/code> property to a <code>Directory.build.props<\/code> file if that fits your workflow better.<\/p>\n<h3 id=\"opt-in-files-one-at-a-time\">Opt in files one at a time<\/h3>\n<p>This approach is the inverse of the previous one.<\/p>\n<ol>\n<li>\n<p>Enable nullability in a file for a project by adding this to the top of the file:<\/p>\n<pre><code class=\"language-csharp\">#nullable enable\r\n<\/code><\/pre>\n<\/li>\n<li>\n<p>Continue adding this to files until all files are annotated and all nullability warnings are addressed.<\/p>\n<\/li>\n<li>\n<p>Apply the following property to your project file:<\/p>\n<pre><code class=\"language-xml\">&lt;PropertyGroup&gt;\r\n    &lt;Nullable&gt;enable&lt;\/Nullable&gt;\r\n&lt;\/PropertyGroup&gt;\r\n<\/code><\/pre>\n<\/li>\n<li>\n<p>Remove all <code>#nullable enable<\/code> directives in source.<\/p>\n<\/li>\n<\/ol>\n<p>This approach requires more work at the end, but it allows you to start fixing nullability warnings immediately.<\/p>\n<p>Note that you can also apply the <code>Nullable<\/code> property to a <code>Directory.build.props<\/code> file if that fits your workflow better.<\/p>\n<h2 id=\"whats-new-in-nullable-reference-types-for-preview-7\">What&#8217;s new in Nullable Reference Types for Preview 7<\/h2>\n<p>The most critical additions to the feature are tools for working with generics and more advanced API usage scenarios. These were derived from our experience in beginning to annotate .NET Core.<\/p>\n<h3 id=\"the-notnull-generic-constraint\">The <code>notnull<\/code> generic constraint<\/h3>\n<p>It is quite common to intend that a generic type is specifically not allowed to be nullable. For example, given the following interface:<\/p>\n<p><script src=\"https:\/\/gist.github.com\/cartermp\/c55433ba06a666e415a5a216fa905045.js\"><\/script><\/p>\n<p>It may be desirable to only allow non-nullable reference and value types. So substituting with <code>string<\/code> or <code>int<\/code> should be fine, but substituting with <code>string?<\/code> or <code>int?<\/code> should not.<\/p>\n<p>This can be accomplished with the <code>notnull<\/code> constraint:<\/p>\n<p><script src=\"https:\/\/gist.github.com\/cartermp\/aece5e6c944aeca1f7e1e74119bc7c0a.js\"><\/script><\/p>\n<p>This will then generate a warning if any implementing class does not also apply the same <code>notnull<\/code> constraints:<\/p>\n<p><script src=\"https:\/\/gist.github.com\/cartermp\/c6db17df1c4d4b51f3f23fbb74d7fcc6.js\"><\/script><\/p>\n<p>To fix it, we need to apply the same constraints:<\/p>\n<p><script src=\"https:\/\/gist.github.com\/cartermp\/0f74e35ba226e8d3a75281f54addfacb.js\"><\/script><\/p>\n<p>And when creating an instance of that class, if you substitute it with a nullable reference type, a warning will also be generated:<\/p>\n<p><script src=\"https:\/\/gist.github.com\/cartermp\/0fd0b2b74d9450f53b447af2ca053904.js\"><\/script><\/p>\n<p>It also works for value types:<\/p>\n<p><script src=\"https:\/\/gist.github.com\/cartermp\/58eea2eb6c134d02514f1f4e53d03982.js\"><\/script><\/p>\n<p>This constraint is useful for generic code where you want to ensure that only non-nullable reference types can be used. One prominent example is <code>Dictionary&lt;TKey, TValue<\/code>, where <code>TKey<\/code> is now constrained to be <code>notnull<\/code>, which disallows using <code>null<\/code> as a key:<\/p>\n<p><script src=\"https:\/\/gist.github.com\/cartermp\/65cd67b60b5304460f70ecf7f9405cc6.js\"><\/script><\/p>\n<p>However, not all nullability problems with generics can be solved in this way. This is where we&#8217;ve added some new attributes to allow you to influence nullable analysis in the compiler.<\/p>\n<h3 id=\"the-issue-with-t\">The issue with <code>T?<\/code><\/h3>\n<p>So you have have wondered: why not &quot;just&quot; allow <code>T?<\/code> when specifying a generic type that could be substituted with a nullable reference or value type? The answer is, unfortunately, complicated.<\/p>\n<p>A natural definition of <code>T?<\/code> would mean, &quot;any nullable type&quot;. However, this would imply that <code>T<\/code> would mean &quot;any non-nullable type&quot;, and that is not true! It is possible to substitute a <code>T<\/code> with a nullable value type today (such as <code>bool?<\/code>). This is because <code>T<\/code> is already an unconstrained generic type. This change in semantics would likely be unexpected and cause some grief for the vast amount of existing code that uses <code>T<\/code> as an unconstrained generic type.<\/p>\n<p>Next, it&#8217;s important to note that a nullable reference type is <em>not<\/em> the same thing as a nullable value type. Nullable value types map to a concrete class type in .NET. So <code>int?<\/code> is actually <code>Nullable&lt;int&gt;<\/code>. But for <code>string?<\/code>, it&#8217;s actually the same <code>string<\/code> but with a compiler-generated attribute annotating it. This is done for backwards compatibility. In other words, <code>string?<\/code> is kind of a &quot;fake type&quot;, whereas <code>int?<\/code> is not.<\/p>\n<p>This distinction between nullable value types and nullable reference types comes up in a pattern such as this:<\/p>\n<pre><code class=\"language-csharp\">void M&lt;T&gt;(T? t) where T: notnull\r\n<\/code><\/pre>\n<p>This would mean that the parameter is the nullable version of <code>T<\/code>, and <code>T<\/code> is constrained to be <code>notnull<\/code>. If <code>T<\/code> were a <code>string<\/code>, then the actual signature of <code>M<\/code> would be <code>M&lt;string&gt;([NullableAttribute] T t)<\/code>, but if <code>T<\/code> were an <code>int<\/code>, then <code>M<\/code> would be <code>M&lt;int&gt;(Nullable&lt;int&gt; t)<\/code>. These two signatures are fundamentally different, and this difference is not reconcilable.<\/p>\n<p>Because of this issue between the concrete representations of nullable reference types and nullable value types, any use of <code>T?<\/code> must also require you to constrain the <code>T<\/code> to be either <code>class<\/code> or <code>struct<\/code>.<\/p>\n<p>Finally, the existence of a <code>T?<\/code> that worked for both nullable reference types and nullable value types does not address every issue with generics. You may want to allow for nullable types in a single direction (i.e., as only an input or only an output) and that is not expressible with either <code>notnull<\/code> nor a <code>T<\/code> and <code>T?<\/code> split unless you artificially add separate generic types for inputs and outputs.<\/p>\n<h3 id=\"nullable-preconditions-allownull-and-disallownull\">Nullable preconditions: <code>AllowNull<\/code> and <code>DisallowNull<\/code><\/h3>\n<p>Consider the following example:<\/p>\n<p><script src=\"https:\/\/gist.github.com\/cartermp\/71a9de4eaf4cd3e01b00113a97cda045.js\"><\/script><\/p>\n<p>This might have been an API that we supported prior to C# 8.0. However, the meaning of <code>string<\/code> now means non-nullable <code>string<\/code>! We may wish to actually still allow <code>null<\/code> values, but always give back some <code>string<\/code> value with the <code>get<\/code>. Here&#8217;s where <code>AllowNull<\/code> can come in and let you get fancy:<\/p>\n<p><script src=\"https:\/\/gist.github.com\/cartermp\/5f5cf63a5b9668a676b165db5ba30dd1.js\"><\/script><\/p>\n<p>Since we always make sure that we get no <code>null<\/code> value with the getter, I&#8217;d like the type to remain <code>string<\/code>. But we want to still accept <code>null<\/code> values for backwards compatibility. The <code>AllowNull<\/code> attribute lets you specify that the setter accepts <code>null<\/code> values. Callers are then affected as you&#8217;d expect:<\/p>\n<p><script src=\"https:\/\/gist.github.com\/cartermp\/0fa2723dbd96f29a8a87c5da35a77577.js\"><\/script><\/p>\n<p>Note: there is currently <a href=\"https:\/\/github.com\/dotnet\/roslyn\/issues\/37313\">a bug<\/a> where assignment of <code>null<\/code> conflicts with nullable analysis. This will be addressed in a future update of the compiler.<\/p>\n<p>Consider another API:<\/p>\n<p><script src=\"https:\/\/gist.github.com\/cartermp\/b3c2ab16a7145fd8e45d3843ae5efb0c.js\"><\/script><\/p>\n<p>In this case, <code>MyHandle<\/code> refers to some handle to a resource. Typical use for this API is that we have a non-<code>null<\/code> instance that we pass by reference, but when it is cleared, the reference is <code>null<\/code>. We can get fancy and represent this with <code>DisallowNull<\/code>:<\/p>\n<p><script src=\"https:\/\/gist.github.com\/cartermp\/3bd5b681294b6fceba525cb5e3bc6d6b.js\"><\/script><\/p>\n<p>This will affect any caller by emitting a warning if they pass <code>null<\/code>, but will warn if you attempt to &quot;dot&quot; into the <code>handle<\/code> after the method is called:<\/p>\n<p><script src=\"https:\/\/gist.github.com\/cartermp\/c4e1fbc410482d18faf1562cdf01b5ce.js\"><\/script><\/p>\n<p>These two attributes allow us single-direction nullability or non-nullability for those cases where we need them.<\/p>\n<p>More formally:<\/p>\n<p>The <code>AllowNull<\/code> attribute allows callers to pass <code>null<\/code> even if the type doesn&#8217;t allow it. The <code>DisallowNull<\/code> attribute disallows callers to pass <code>null<\/code> even if the type allows it. They can be specified on anything that takes input:<\/p>\n<ul>\n<li>Value parameters<\/li>\n<li><code>in<\/code> parameters<\/li>\n<li><code>ref<\/code> parameters<\/li>\n<li>fields<\/li>\n<li>properties<\/li>\n<li>indexers<\/li>\n<\/ul>\n<p><strong>Important:<\/strong> These attributes only affect nullable analysis for the <em>callers<\/em> of methods that are annotated with them. The bodies of annotated methods  and things like interface implementation do not respect these attributes. We may add support for that in the future.<\/p>\n<h3 id=\"nullable-postconditions-maybenull-and-notnull\">Nullable postconditions: <code>MaybeNull<\/code> and <code>NotNull<\/code><\/h3>\n<p>Consider the following example API:<\/p>\n<p><script src=\"https:\/\/gist.github.com\/cartermp\/7954ebc992a40a119981aca9f8ab4e76.js\"><\/script><\/p>\n<p>Here we have another problem. We&#8217;d like <code>Find<\/code> to give back <code>default<\/code> if nothing is found, which is <code>null<\/code> for reference types. We&#8217;d like <code>Resize<\/code> to accept a possibly <code>null<\/code> input, but we want to ensure that after <code>Resize<\/code> is called, the <code>array<\/code> value passed by reference is always non-<code>null<\/code>. Again, applying the <code>notnull<\/code> constraint doesn&#8217;t solve this. Uh-oh!<\/p>\n<p>Enter <code>[MaybeNull]<\/code> and <code>[NotNull]<\/code>. Now we can get fancy with the nullability of the outputs! We can modify the example as such:<\/p>\n<p><script src=\"https:\/\/gist.github.com\/cartermp\/135417c4ec7e448ae9c8ea8b2f84fdcc.js\"><\/script><\/p>\n<p>And these can now affect call sites:<\/p>\n<p><script src=\"https:\/\/gist.github.com\/cartermp\/6320ad7c3fe9aceca5db658a80a99967.js\"><\/script><\/p>\n<p>The first method specifies that the <code>T<\/code> that is returned could be a <code>null<\/code> value. This means that callers of this method must check for <code>null<\/code> when using its result.<\/p>\n<p>The second method has a trickier signature: <code>[NotNull] ref T[]? array<\/code>. This means that <code>array<\/code> could be <code>null<\/code> as an input, but when <code>Resize<\/code> is called, <code>array<\/code> will not be <code>null<\/code>. This means that if you &quot;dot&quot; into <code>array<\/code> after calling <code>Resize<\/code>, you will not get a warning. But after <code>Resize<\/code> is called, <code>array<\/code> will no longer be <code>null<\/code>.<\/p>\n<p>More formally:<\/p>\n<p>The <code>MaybeNull<\/code> attribute allows for a return type to be <code>null<\/code>, even if its type doesn&#8217;t allow it. The <code>NotNull<\/code> attribute disallows <code>null<\/code> results even if the type allows it. They can be specified on anything that produces output:<\/p>\n<ul>\n<li>Method returns<\/li>\n<li><code>out<\/code> parameters (after a method is called)<\/li>\n<li><code>ref<\/code> parameters (after a method is called)<\/li>\n<li>fields<\/li>\n<li>properties<\/li>\n<li>indexers<\/li>\n<\/ul>\n<p><strong>Important:<\/strong> These attributes only affect nullable analysis for the <em>callers<\/em> of methods that are annotated with them. The bodies of annotated methods  and things like interface implementation do not respect these attributes. We may add support for that in the future.<\/p>\n<h3 id=\"conditional-postconditions-maybenullwhenbool-and-notnullwhenbool\">Conditional postconditions: <code>MaybeNullWhen(bool)<\/code> and <code>NotNullWhen(bool)<\/code><\/h3>\n<p>Consider the following example:<\/p>\n<p><script src=\"https:\/\/gist.github.com\/cartermp\/b363b362fd413d10f3360d24cb69dc5c.js\"><\/script><\/p>\n<p>Methods like this are everywhere in .NET, where the return value of <code>true<\/code> or <code>false<\/code> corresponds to the nullability (or possible nullability) of a parameter. The <code>MyQueue<\/code> case is also a bit special, since it&#8217;s generic. <code>TryDequeue<\/code> should give a <code>null<\/code> for <code>result<\/code> if the result is <code>false<\/code>, but only if <code>T<\/code> is a reference type. If <code>T<\/code> is a struct, then it won&#8217;t be <code>null<\/code>.<\/p>\n<p>So, we want to do three things:<\/p>\n<ol>\n<li>Signal that if <code>IsNullOrEmpty<\/code> returns <code>false<\/code>, then <code>value<\/code> is non-<code>null<\/code><\/li>\n<li>Signal that if <code>TryParse<\/code> returns <code>true<\/code>, then <code>version<\/code> is non-<code>null<\/code><\/li>\n<li>Signal that if <code>TryDequeue<\/code> returns <code>false<\/code>, then <code>result<\/code> <em>could<\/em> be <code>null<\/code>, provided it&#8217;s a reference type<\/li>\n<\/ol>\n<p>Unfortunately, the C# compiler does not associate the return value of a method with the nullability of one of its parameters! Uh-oh!<\/p>\n<p>Enter <code>NotNullWhen(bool)<\/code> and <code>MaybeNullWhen(bool)<\/code>. Now we can get <em>even fancier<\/em> with parameters:<\/p>\n<p><script src=\"https:\/\/gist.github.com\/cartermp\/9c3ec4bb1525c08d2566f5aafefaad3c.js\"><\/script><\/p>\n<p>And these can now affect call sites:<\/p>\n<p><script src=\"https:\/\/gist.github.com\/cartermp\/790652ac43946e6d4da2d1e5e526a472.js\"><\/script><\/p>\n<p>This enables callers to work with APIs using the same patterns that they&#8217;ve used before, without any spurious warnings from the compiler:<\/p>\n<ul>\n<li>If <code>IsNullOrEmpty<\/code> is true, it&#8217;s safe to &quot;dot&quot; into <code>value<\/code><\/li>\n<li>If <code>TryParse<\/code> is true, then <code>version<\/code> was parsed and is safe to &quot;dot&quot; into<\/li>\n<li>If <code>TryDequeue<\/code> is false, then <code>result<\/code> might be <code>null<\/code> and a check is needed (example: returning <code>false<\/code> when the type is a struct is non-<code>null<\/code>, but <code>false<\/code> for a reference type means it could be <code>null<\/code>)<\/li>\n<\/ul>\n<p>More formally:<\/p>\n<p>The <code>NotNullWhen(bool)<\/code> signifies that a parameter is not null even if the type allows it, conditional on the <code>bool<\/code> returned value of the method. The <code>MaybeNullWhen(bool)<\/code> signifies that a parameter could be null even if the type disallows it, conditional on the <code>bool<\/code> returned value of the method. They can be specified on any parameter type.<\/p>\n<h3 id=\"nullness-dependence-between-inputs-and-outputs-notnullifnotnullstring\">Nullness dependence between inputs and outputs: <code>NotNullIfNotNull(string)<\/code><\/h3>\n<p>Consider the following example:<\/p>\n<p><script src=\"https:\/\/gist.github.com\/cartermp\/56ca416bb757d3897f0b4e5ff3929850.js\"><\/script><\/p>\n<p>In this case, we&#8217;d like to return a possibly <code>null<\/code> string, and we should also be able to accept a <code>null<\/code> value as input. So the signature accomplishes what I&#8217;d like to express.<\/p>\n<p>However, if <code>path<\/code> is not <code>null<\/code>, we&#8217;d like to ensure that we always give back a string. That is, we want the return value of <code>GetFileName<\/code> to be non-null, conditional on the nullness of <code>path<\/code>. There&#8217;s no way to express this as-is. Uh-oh!<\/p>\n<p>Enter <code>NotNullIfNotNull(string)<\/code>. This attribute can make your code the <em>fanciest<\/em>, so use it with care! Here&#8217;s how we&#8217;ll use it in my API:<\/p>\n<p><script src=\"https:\/\/gist.github.com\/cartermp\/6b060abd518344d7d0c702e389800c9a.js\"><\/script><\/p>\n<p>And this can now affect call sites:<\/p>\n<p><script src=\"https:\/\/gist.github.com\/cartermp\/15e62beb92ade84ca5265a80b1368630.js\"><\/script><\/p>\n<p>More formally:<\/p>\n<p>The <code>NotNullIfNotNull(string)<\/code> attribute signifies that any output value is non-<code>null<\/code> conditional on the nullability of a given parameter whose name is specified. They can be specified on the following constructs:<\/p>\n<ul>\n<li>Method returns<\/li>\n<li><code>ref<\/code> parameters<\/li>\n<\/ul>\n<h3 id=\"flow-attributes-doesnotreturn-and-doesnotreturnifbool\">Flow attributes: <code>DoesNotReturn<\/code> and <code>DoesNotReturnIf(bool)<\/code><\/h3>\n<p>You may work with multiple methods that affect control flow of your program. For example, an exception helper method that will throw an exception if called, or an assertion method that will throw an exception if an input is <code>true<\/code> or <code>false<\/code>.<\/p>\n<p>You may wish to do something like <em>assert<\/em> that a value is non-null, and we think you&#8217;d also like it if the compiler could understand that.<\/p>\n<p>Enter <code>DoesNotReturn<\/code> and <code>DoesNotReturnIf(bool)<\/code>. Here&#8217;s an example of how you could use either:<\/p>\n<p><script src=\"https:\/\/gist.github.com\/cartermp\/0236d0bc8dd418b6d1d728435ad75ac1.js\"><\/script><\/p>\n<p>When <code>ThrowArgumentNullException<\/code> is called in a method, it throws an exception. The <code>DoesNotReturn<\/code> it is annotated with will signal to the compiler that no nullable analysis needs to happen after that point, since that code would be unreachable.<\/p>\n<p>When <code>MyAssert<\/code> is called and the condition passed to it is <code>false<\/code>, it throws an exception. The <code>DoesNotReturnIf(false)<\/code> that annotates the <code>condition<\/code> parameter lets the compiler know that program flow will not continue if that condition is false. This is helpful if you want to assert the nullability of a value. In the code path following <code>MyAssert(value != null);<\/code> the compiler can assume <code>value<\/code> is not null.<\/p>\n<p><code>DoesNotReturn<\/code> can be used on methods. <code>DoesNotReturnIf(bool)<\/code> can be used on input parameters.<\/p>\n<h2 id=\"evolving-your-annotations\">Evolving your annotations<\/h2>\n<p>Once you annotate a public API, you&#8217;ll want to consider the fact that updating an API can have downstream effects:<\/p>\n<ul>\n<li>Adding nullable annotations where there weren&#8217;t any may introduce warnings to user code<\/li>\n<li>Removing nullable annotations can also introduce warnings (e.g., interface implementation)<\/li>\n<\/ul>\n<p>Nullable annotations are an integral part of your public API. Adding or removing annotations introduce new warnings. We recommend starting with a preview release where you solicit feedback, with aims to not change any annotations after a full release. This isn&#8217;t always going to be possible, but we recommend it nonetheless.<\/p>\n<h2 id=\"current-status-of-microsoft-frameworks-and-libraries\">Current status of Microsoft frameworks and libraries<\/h2>\n<p>Because Nullable Reference Types are so new, the large majority of Microsoft-authored C# frameworks and libraries have not yet been appropriately annotated.<\/p>\n<p>That said, the &quot;Core Lib&quot; part of .NET Core, which represents about ~20% of the .NET Core shared framework, has been fully updated. It includes namespaces like <code>System<\/code>, <code>System.IO<\/code>, and <code>System.Collections.Generic<\/code>. We&#8217;re looking for feedback on our decisions so that we can make appropriate tweaks as soon as possible, and before their usage becomes widespread.<\/p>\n<p>Although there is still ~80% CoreFX to still annotate, the most-used APIs are fully annotated.<\/p>\n<h2 id=\"roadmap-for-nullable-reference-types\">Roadmap for Nullable Reference Types<\/h2>\n<p>Currently, we view the <em>full<\/em> Nullable Reference Types experience as being in preview. It&#8217;s stable, but the feature involves spreading nullable annotations throughout our own technologies and the greater .NET ecosystem. This will take some time to complete.<\/p>\n<p>That said, we&#8217;re encouraging library authors to start annotating their libraries now. The feature will only get better as more libraries adopt nullability, helping .NET become a more <code>null<\/code>-safe place.<\/p>\n<p>Over the coming year or so, we&#8217;re going to continue to improve the feature and spread its use throughout Microsoft frameworks and libraries.<\/p>\n<p>For the language, especially compiler analysis, we&#8217;ll be making numerous enhancements so that we can minimize your need to do things like use the null-forgiveness (<code>!<\/code>) operator. Many of these enhancements are <a href=\"https:\/\/github.com\/dotnet\/roslyn\/issues?q=is%3Aissue+is%3Aopen+label%3A%22New+Language+Feature+-+Nullable+Reference+Types%22\">already tracked on the Roslyn repo<\/a>.<\/p>\n<p>For CoreFX, we&#8217;ll be annotating the remaining ~80% of APIs and making appropriate tweaks based on feedback.<\/p>\n<p>For ASP.NET Core and Entity Framework, we&#8217;ll be annotating public APIs once some new additions to CoreFX and the compiler are added.<\/p>\n<p>We haven&#8217;t yet planned how to annotate WinForms and WPF APIs, but we&#8217;d love to hear your feedback on what kinds of things matter!<\/p>\n<p>Finally, we&#8217;re going to continue enhancing C# tooling in Visual Studio. We have multiple ideas for features to help using the feature, but we&#8217;d love your input as well!<\/p>\n<h2 id=\"next-steps\">Next steps<\/h2>\n<p>If you&#8217;re still reading and haven&#8217;t tried out the feature in your code, especially your library code, give it a try and please give us feedback on anything you feel ought to be different. The journey to make unanticipated <code>NullReferenceException<\/code>s in .NET go away will be lengthy, but we hope that in the long run, developers simply won&#8217;t have to worry about getting bitten by implicit <code>null<\/code> values anymore. You can help us. Try out the feature and begin annotating your libraries. Feedback on your experience will help shorten that journey.<\/p>\n<p>Cheers, and happy hacking!<\/p>\n","protected":false},"excerpt":{"rendered":"<p>Try out Nullable Reference Types With the release of .NET Core 3.0 Preview 7, C# 8.0 is considered &quot;feature complete&quot;. That means that the biggest feature of them all, Nullable Reference Types, is also locked down behavior-wise for the .NET Core release. It will continue to improve after C# 8.0, but it is now considered [&hellip;]<\/p>\n","protected":false},"author":678,"featured_media":58792,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[685],"tags":[4],"class_list":["post-24002","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-dotnet","tag-net"],"acf":[],"blog_post_summary":"<p>Try out Nullable Reference Types With the release of .NET Core 3.0 Preview 7, C# 8.0 is considered &quot;feature complete&quot;. That means that the biggest feature of them all, Nullable Reference Types, is also locked down behavior-wise for the .NET Core release. It will continue to improve after C# 8.0, but it is now considered [&hellip;]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/posts\/24002","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/users\/678"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/comments?post=24002"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/posts\/24002\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/media\/58792"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/media?parent=24002"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/categories?post=24002"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/tags?post=24002"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}