WriteFile function (fileapi.h)

Writes data to the specified file or input/output (I/O) device.

This function is designed for both synchronous and asynchronous operation. For a similar function designed solely for asynchronous operation, see WriteFileEx.

Syntax

Parameters

A handle to the file or I/O device (for example, a file, file stream, physical disk, volume, console buffer, tape drive, socket, communications resource, mailslot, or pipe).

The hFile parameter must have been created with the write access. For more information, see Generic Access Rights and File Security and Access Rights.

For asynchronous write operations, hFile can be any handle opened with the CreateFile function using the FILE_FLAG_OVERLAPPED flag or a socket handle returned by the socket or accept function.

A pointer to the buffer containing the data to be written to the file or device.

This buffer must remain valid for the duration of the write operation. The caller must not use this buffer until the write operation is completed.

The number of bytes to be written to the file or device.

A value of zero specifies a null write operation. The behavior of a null write operation depends on the underlying file system or communications technology.

Windows ServerВ 2003 and WindowsВ XP:В В Pipe write operations across a network are limited in size per write. The amount varies per platform. For x86 platforms it’s 63.97 MB. For x64 platforms it’s 31.97 MB. For Itanium it’s 63.95 MB. For more information regarding pipes, see the Remarks section.

A pointer to the variable that receives the number of bytes written when using a synchronous hFile parameter. WriteFile sets this value to zero before doing any work or error checking. Use NULL for this parameter if this is an asynchronous operation to avoid potentially erroneous results.

This parameter can be NULL only when the lpOverlapped parameter is not NULL.

For more information, see the Remarks section.

A pointer to an OVERLAPPED structure is required if the hFile parameter was opened with FILE_FLAG_OVERLAPPED, otherwise this parameter can be NULL.

For an hFile that supports byte offsets, if you use this parameter you must specify a byte offset at which to start writing to the file or device. This offset is specified by setting the Offset and OffsetHigh members of the OVERLAPPED structure. For an hFile that does not support byte offsets, Offset and OffsetHigh are ignored.

To write to the end of file, specify both the Offset and OffsetHigh members of the OVERLAPPED structure as 0xFFFFFFFF. This is functionally equivalent to previously calling the CreateFile function to open hFile using FILE_APPEND_DATA access.

For more information about different combinations of lpOverlapped and FILE_FLAG_OVERLAPPED, see the Remarks section and the Synchronization and File Position section.

Return value

If the function succeeds, the return value is nonzero (TRUE).

If the function fails, or is completing asynchronously, the return value is zero (FALSE). To get extended error information, call the GetLastError function.

Remarks

The WriteFile function returns when one of the following conditions occur:

• The number of bytes requested is written.
• A read operation releases buffer space on the read end of the pipe (if the write was blocked). For more information, see the Pipes section.
• An asynchronous handle is being used and the write is occurring asynchronously.
• An error occurs.

The WriteFile function may fail with ERROR_INVALID_USER_BUFFER or ERROR_NOT_ENOUGH_MEMORY whenever there are too many outstanding asynchronous I/O requests.

To cancel all pending asynchronous I/O operations, use either:

• CancelIo—this function cancels only operations issued by the calling thread for the specified file handle.
• CancelIoEx—this function cancels all operations issued by the threads for the specified file handle.

Use the CancelSynchronousIo function to cancel pending synchronous I/O operations.

I/O operations that are canceled complete with the error ERROR_OPERATION_ABORTED.

The WriteFile function may fail with ERROR_NOT_ENOUGH_QUOTA, which means the calling process’s buffer could not be page-locked. For more information, see SetProcessWorkingSetSize.

If part of the file is locked by another process and the write operation overlaps the locked portion, WriteFile fails.

When writing to a file, the last write time is not fully updated until all handles used for writing have been closed. Therefore, to ensure an accurate last write time, close the file handle immediately after writing to the file.

Accessing the output buffer while a write operation is using the buffer may lead to corruption of the data written from that buffer. Applications must not write to, reallocate, or free the output buffer that a write operation is using until the write operation completes. This can be particularly problematic when using an asynchronous file handle. Additional information regarding synchronous versus asynchronous file handles can be found later in the Synchronization and File Position section and Synchronous and Asynchronous I/O.

Note that the time stamps may not be updated correctly for a remote file. To ensure consistent results, use unbuffered I/O.

The system interprets zero bytes to write as specifying a null write operation and WriteFile does not truncate or extend the file. To truncate or extend a file, use the SetEndOfFile function.

Characters can be written to the screen buffer using WriteFile with a handle to console output. The exact behavior of the function is determined by the console mode. The data is written to the current cursor position. The cursor position is updated after the write operation. For more information about console handles, see CreateFile.

When writing to a communications device, the behavior of WriteFile is determined by the current communication time-out as set and retrieved by using the SetCommTimeouts and GetCommTimeouts functions. Unpredictable results can occur if you fail to set the time-out values. For more information about communication time-outs, see COMMTIMEOUTS.

Although a single-sector write is atomic, a multi-sector write is not guaranteed to be atomic unless you are using a transaction (that is, the handle created is a transacted handle; for example, a handle created using CreateFileTransacted). Multi-sector writes that are cached may not always be written to the disk right away; therefore, specify FILE_FLAG_WRITE_THROUGH in CreateFile to ensure that an entire multi-sector write is written to the disk without potential caching delays.

If you write directly to a volume that has a mounted file system, you must first obtain exclusive access to the volume. Otherwise, you risk causing data corruption or system instability, because your application’s writes may conflict with other changes coming from the file system and leave the contents of the volume in an inconsistent state. To prevent these problems, the following changes have been made in WindowsВ Vista and later:

• A write on a volume handle will succeed if the volume does not have a mounted file system, or if one of the following conditions is true:
  • The sectors to be written to are boot sectors.
  • The sectors to be written to reside outside of file system space.
  • You have explicitly locked or dismounted the volume by using FSCTL_LOCK_VOLUME or FSCTL_DISMOUNT_VOLUME.
  • The volume has no actual file system. (In other words, it has a RAW file system mounted.)
• A write on a disk handle will succeed if one of the following conditions is true:
  • The sectors to be written to do not fall within a volume’s extents.
  • The sectors to be written to fall within a mounted volume, but you have explicitly locked or dismounted the volume by using FSCTL_LOCK_VOLUME or FSCTL_DISMOUNT_VOLUME.
  • The sectors to be written to fall within a volume that has no mounted file system other than RAW.

There are strict requirements for successfully working with files opened with CreateFile using FILE_FLAG_NO_BUFFERING. For details see File Buffering.

If hFile was opened with FILE_FLAG_OVERLAPPED, the following conditions are in effect:

• The lpOverlapped parameter must point to a valid and unique OVERLAPPED structure, otherwise the function can incorrectly report that the write operation is complete.
• The lpNumberOfBytesWritten parameter should be set to NULL. To get the number of bytes written, use the GetOverlappedResult function. If the hFile parameter is associated with an I/O completion port, you can also get the number of bytes written by calling the GetQueuedCompletionStatus function.

In Windows ServerВ 2012, this function is supported by the following technologies.

Technology	Supported
Server Message Block (SMB) 3.0 protocol	Yes
SMB 3.0 Transparent Failover (TFO)	Yes
SMB 3.0 with Scale-out File Shares (SO)	Yes
Cluster Shared Volume File System (CsvFS)	Yes
Resilient File System (ReFS)	Yes

В

Synchronization and File Position

Pipes

If the pipe buffer is full when an application uses the WriteFile function to write to a pipe, the write operation may not finish immediately. The write operation will be completed when a read operation (using the ReadFile function) makes more system buffer space available for the pipe.

When writing to a non-blocking, byte-mode pipe handle with insufficient buffer space, WriteFile returns TRUE with *lpNumberOfBytesWritten —>

Учебник. Перенос существующего кода со ссылочными типами, допускающими значение null Tutorial: Migrate existing code with nullable reference types

В C# 8 вводятся ссылочные типы, допускающие значение null, которые дополняют ссылочные типы таким же образом, как типы значений, допускающие значение null, дополняют другие типы значений. C# 8 introduces nullable reference types, which complement reference types the same way nullable value types complement value types. Чтобы объявить переменную как имеющую ссылочный тип, допускающий значение null, добавьте ? к типу. You declare a variable to be a nullable reference type by appending a ? to the type. Например, string? соответствует типу string , допускающему значение null. For example, string? represents a nullable string . Эти новые типы можно использовать для более четкого выражения проектного замысла: некоторые переменные всегда должны содержать значение, а в других они могут отсутствовать. You can use these new types to more clearly express your design intent: some variables must always have a value, others may be missing a value. Любые существующие переменные ссылочного типа будут интерпретироваться как не допускающие значение null. Any existing variables of a reference type would be interpreted as a non-nullable reference type.

В этом руководстве вы узнаете, как: In this tutorial, you’ll learn how to:

• включить проверку пустых ссылок при работе с кодом; Enable null reference checks as you work with code.
• выполнить диагностику и устранение различных предупреждений, связанных со значениями null; Diagnose and correct different warnings related to null values.
• управлять интерфейсом между контекстами, допускающими значение null и не допускающими его; Manage the interface between nullable enabled and nullable disabled contexts.
• контролировать контекст заметок, допускающих значение null. Control nullable annotation contexts.

Предварительные требования Prerequisites

Вам нужно настроить свой компьютер для выполнения .NET Core, включая компилятор C# 8.0. You’ll need to set up your machine to run .NET Core, including the C# 8.0 compiler. Компилятор C# 8 доступен, начиная с версии 16.3 Visual Studio 2019 или в пакете SDK .NET Core 3.0. The C# 8 compiler is available starting with Visual Studio 2019 version 16.3 or .NET Core 3.0 SDK.

В этом руководстве предполагается, что вы знакомы с C# и .NET, включая Visual Studio или .NET Core CLI. This tutorial assumes you’re familiar with C# and .NET, including either Visual Studio or the .NET Core CLI.

Изучение примера приложения Explore the sample application

Пример приложения, который вы будете переносить, представляет собой веб-приложение для чтения RSS-каналов. The sample application that you’ll migrate is an RSS feed reader web app. Оно читает один RSS-канал и отображает сводки самых последних статей. It reads from a single RSS feed and displays summaries for the most recent articles. Вы можете выбрать любую статью, чтобы перейти на страницу сайта. You can select any of the articles to visit the site. Приложение относительно новое, но было написано до того, как ссылочные типы, допускающие значение null, стали доступными. The application is relatively new but was written before nullable reference types were available. Проектные решения для приложения представляют разумные принципы, но не используют преимущества этой важной функции языка. The design decisions for the application represented sound principles, but don’t take advantage of this important language feature.

Пример приложения содержит библиотеку модульных тестов, которые проверяют основную функциональность приложения. The sample application includes a unit test library that validates the major functionality of the app. Этот проект облегчит безопасное обновление, если вы измените любую из реализаций на основе сгенерированных предупреждений. That project will make it easier to upgrade safely, if you change any of the implementation based on the warnings generated. Скачать начальный код можно из репозитория GitHub dotnet/samples. You can download the starter code from the dotnet/samples GitHub repository.

Целью переноса проекта является использование новых возможностей языка, позволяющих четко выразить свои намерения относительно переменных, допускающих значение null, таким образом, чтобы компилятор не генерировал предупреждения в случае контекста заметок, допускающих значение null, и установки для контекста предупреждений о допустимости значения null значения enabled . Your goal migrating a project should be to leverage the new language features so that you clearly express your intent on the nullability of variables, and do so in such a way that the compiler doesn’t generate warnings when you have the nullable annotation context and nullable warning context set to enabled .

Переход проекта на C# 8 Upgrade the projects to C# 8

Сначала рекомендуется определить область задачи перехода. A good first step is to determine the scope of the migration task. В первую очередь мы перейдем на использование C# 8.0 (или более поздней версии). Start by upgrading the project to C# 8.0 (or newer). Добавьте элемент LangVersion в PropertyGroup в CSPROJ-файлах веб-проекта и проекта модульных тестов: Add the LangVersion element to the PropertyGroup in both csproj files for the web project and the unit test project:

Версия языка обновляется до C# 8.0, но без включения контекста заметок, допускающих значение null, или контекста предупреждений о допустимости значения null. Upgrading the language version selects C# 8.0, but does not enable the nullable annotation context or the nullable warning context. Перестройте проект так, чтобы сборка выполнялась без предупреждений. Rebuild the project to ensure that it builds without warnings.

Следующим шагом является включение контекста заметок, допускающих значение null, и просмотр количества генерируемых предупреждений. A good next step is to turn on the nullable annotation context and see how many warnings are generated. Добавьте следующий элемент прямо под элементом LangVersion в оба CSPROJ-файла решения: Add the following element to both csproj files in the solution, directly under the LangVersion element:

Выполните тестовую сборку и обратите внимание на список предупреждений. Do a test build, and notice the warning list. В этом небольшом приложении компилятор генерирует пять предупреждений, так что, скорее всего, вы оставите контекст заметок, допускающих значение null, включенным и начнете исправлять предупреждения для всего проекта. In this small application, the compiler generates five warnings, so it’s likely you’d leave the nullable annotation context enabled and start fixing warnings for the entire project.

Эта стратегия работает только для небольших проектов. That strategy works only for smaller projects. Для крупных проектов из-за включения контекста заметок, допускающих значение null, для всей базы кода генерируется большое количество предупреждений. Это затрудняет систематическое исправление этих предупреждений. For any larger projects, the number of warnings generated by enabling the nullable annotation context for the entire codebase makes it harder to fix the warnings systematically. Для крупных корпоративных проектов часто нужно будет переносить один проект за раз. For larger enterprise projects, you’ll often want to migrate one project at a time. В каждом проекте переносите один класс или файл за раз. In each project, migrate one class or file at a time.

Предупреждения помогают определить исходное намерение проекта Warnings help discover original design intent

Существует два класса, которые генерируют предупреждения. There are two classes that generate multiple warnings. Начнем с класса NewsStoryViewModel . Start with the NewsStoryViewModel class. Удалите элемент Nullable из обоих CSPROJ-файлов, чтобы ограничить область предупреждений до фрагментов кода, над которыми вы работаете. Remove the Nullable element from both csproj files so that you can limit the scope of warnings to the sections of code you’re working with. Откройте файл NewsStoryViewModel.cs и добавьте следующие директивы, чтобы включить контекст заметок, допускающих значение null, для класса NewsStoryViewModel , и восстановите класс в соответствии со следующим определением: Open the NewsStoryViewModel.cs file and add the following directives to enable the nullable annotation context for the NewsStoryViewModel and restore it following that class definition:

Эти две директивы помогут сфокусировать трудозатраты перехода. These two directives help you focus your migration efforts. Предупреждения о допустимости значений null генерируются для той области кода, над которой вы активно работаете. The nullable warnings are generated for the area of code you’re actively working on. Оставьте так до тех пор, пока не будете готовы включить предупреждения для всего проекта. You’ll leave them on until you’re ready to turn on the warnings for the entire project. Необходимо использовать значение restore , а не disable , чтобы случайно не отключить контекст, когда вы включите заметки, допускающие значение null, для всего проекта. You should use the restore rather than disable value so that you don’t accidentally disable the context later when you’ve turned on nullable annotations for the entire project. После включения контекста заметок, допускающих значение null, для всего проекта вы можете удалить все прагмы-директивы #nullable из проекта. Once you’ve turned on the nullable annotation context for the entire project, you can remove all the #nullable pragmas from that project.

Класс NewsStoryViewModel является объектом передачи данных (DTO), а двое из его свойств — строками чтения и записи: The NewsStoryViewModel class is a data transfer object (DTO) and two of the properties are read/write strings:

Эти два свойства вызывают ошибку CS8618 : «Non-nullable property is uninitialized» (Отменена инициализация свойства, которое не является свойством необязательной определенности). These two properties cause CS8618 , «Non-nullable property is uninitialized». Это очевидно: оба свойства string при создании объекта NewsStoryViewModel имеют значение по умолчанию null . That’s clear enough: both string properties have the default value of null when a NewsStoryViewModel is constructed. Важно выяснить, как создаются объекты NewsStoryViewModel . What’s important to discover is how NewsStoryViewModel objects are constructed. Глядя на этот класс, невозможно определить то, является ли значение null частью решения разработки, или то, устанавливаются ли для этих объектов ненулевые значения во время их создания. Looking at this class, you can’t tell if the null value is part of the design, or if these objects are set to non-null values whenever one is created. Новости (newsStory) создаются в методе GetNews класса NewsService : The news stories are created in the GetNews method of the NewsService class:

В предыдущем блоке кода довольно много важного. There’s quite a bit going on in the preceding block of code. Это приложение использует пакет NuGet AutoMapper для создания элемента новостей на основе элемента ISyndicationItem . This application uses the AutoMapper NuGet package to construct a news item from an ISyndicationItem . Видно также, что в этом одном операторе и создаются элементы новостей, и задаются свойства. You’ve discovered that the news story items are constructed and the properties are set in that one statement. Это означает, что проектное решение класса NewsStoryViewModel указывает, что эти свойства никогда не должны иметь значение null . That means the design for the NewsStoryViewModel indicates that these properties should never have the null value. Эти свойства должны быть ссылочного типа, не допускающего значение null. These properties should be nonnullable reference types. Это лучше всего выражает исходное намерение проекта. That best expresses the original design intent. Фактически, экземпляр любого объекта создается NewsStoryViewModel правильно с ненулевыми значениями. In fact, any NewsStoryViewModel is correctly instantiated with non-null values. Следующий код инициализации является допустимым исправлением: That makes the following initialization code a valid fix:

Присвоение строкам Title и Uri значения default , которое является null для типа string , не изменяет поведение программы во время выполнения. The assignment of Title and Uri to default which is null for the string type doesn’t change the runtime behavior of the program. Объекты класса NewsStoryViewModel все еще создаются с нулевыми значениями, но теперь компилятор не выдает предупреждений. The NewsStoryViewModel is still constructed with null values, but now the compiler reports no warnings. Оператором, разрешающим значение null, является символ ! . В этом примере он стоит после выражения default и сообщает компилятору, что предыдущее выражение не является нулевым. The null-forgiving operator, the ! character following the default expression tells the compiler that the preceding expression is not null. Эта методика может быть целесообразной, если другие изменения вызывают гораздо большие изменения базы кода, но в этом приложении есть лучшее и относительно быстрое решение. Оно состоит в том, чтобы сделать NewsStoryViewModel неизменяемым типом, где все свойства устанавливаются в конструкторе. This technique may be expedient when other changes force much larger changes to a code base, but in this application there is a relatively quick and better solution: Make the NewsStoryViewModel an immutable type where all the properties are set in the constructor. Внесите следующие изменения в класс NewsStoryViewModel : Make the following changes to the NewsStoryViewModel :

После этого нужно обновить код, который настраивает AutoMapper так, чтобы тот использовал конструктор, а не инициализировал свойства. Once that’s done, you need to update the code that configures the AutoMapper so that it uses the constructor rather than setting properties. Откройте файл NewsService.cs и найдите следующий код в нижней части: Open NewsService.cs and look for the following code at the bottom of the file:

Этот код сопоставляет свойства объектов ISyndicationItem и NewsStoryViewModel . That code maps properties of the ISyndicationItem object to the NewsStoryViewModel properties. Нам нужно, чтобы AutoMapper предоставил сопоставление, используя вместо этого конструктор. You want the AutoMapper to provide the mapping using a constructor instead. Замените приведенный выше код на следующую конфигурацию AutoMapper: Replace the above code with the following automapper configuration:

Обратите внимание, так как этот класс небольшой и вы внимательно изучили его, необходимо включить директиву #nullable enable над объявлением класса. Notice that because this class is small, and you’ve examined carefully, you should turn on the #nullable enable directive above this class declaration. Изменение в конструкторе могло нарушить какой-то код, поэтому стоит выполнить все тесты и протестировать приложение, прежде чем двигаться дальше. The change to the constructor could have broken something, so it’s worthwhile to run all the tests and test the application before moving on.

Первый набор изменений показал, как определить, что в исходном намерении для переменных не должно устанавливаться значение null . The first set of changes showed you how to discover when the original design indicated that variables shouldn’t be set to null . Это методика называется правильным конструированием. The technique is referred to as correct by construction. Вы объявляете, что объект и его свойства не могут иметь значение null при создании. You declare that an object and its properties cannot be null when it’s constructed. Анализ потока компилятором гарантирует, что для этих свойств не будет задано значение null после создания. The compiler’s flow analysis provides assurance that those properties aren’t set to null after construction. Обратите внимание, что конструктор вызывается внешним кодом, который не обращает внимания на допустимость значений null. Note that this constructor is called by external code, and that code is nullable oblivious. Новый синтаксис не обеспечивает проверку во время выполнения. The new syntax doesn’t provide runtime checking. Внешний код может обойти анализ потока компилятором. External code might circumvent the compiler’s flow analysis.

В других случаях структура класса предоставляет различные подсказки к пониманию намерения. Other times, the structure of a class provides different clues to the intent. Откройте файл Error.cshtml.cs в папке Pages. Open the Error.cshtml.cs file in the Pages folder. Класс ErrorViewModel содержит следующий код: The ErrorViewModel contains the following code:

Добавьте директиву #nullable enable перед объявлением класса и директиву #nullable restore после объявления. Add the #nullable enable directive before the class declaration, and a #nullable restore directive after it. Вы получите одно предупреждение о том, что RequestId не инициализирован. You’ll get one warning that RequestId is not initialized. Посмотрев на класс, вы должны решить, что в некоторых случаях свойство RequestId должно быть со значением null. By looking at the class, you should decide that the RequestId property should be null in some cases. Наличие свойства ShowRequestId указывает, что возможны пропущенные значения. The existence of the ShowRequestId property indicates that missing values are possible. Так как значение null является допустимым, добавьте ? в тип string , чтобы указать, что свойство RequestId является ссылочного типа, допускающего значение null. Because null is valid, add the ? on the string type to indicate the RequestId property is a nullable reference type. Окончательное определение класса выглядит следующим образом: The final class looks like the following example:

Проверьте использование свойства. Вы увидите, что перед отображением свойства в исправлении оно проверяется на значение null на соответствующей странице. Check for the uses of the property, and you see that in the associated page, the property is checked for null before rendering it in markup. Это безопасное использование ссылочного типа, допускающего значение null, поэтому мы закончим работу с этим классом. That’s a safe use of a nullable reference type, so you’re done with this class.

Исправление значений null приводит к изменениям Fixing nulls causes change

Часто исправление одного набора предупреждений создает новые предупреждения в связанном коде. Frequently, the fix for one set of warnings creates new warnings in related code. Давайте посмотрим на предупреждения в действии, исправив класс index.cshtml.cs . Let’s see the warnings in action by fixing the index.cshtml.cs class. Откройте файл index.cshtml.cs и изучите код. Open the index.cshtml.cs file and examine the code. В этом файле содержится код для страницы индексов: This file contains the code behind for the index page:

Добавьте директиву #nullable enable , и вы увидите два предупреждения. Add the #nullable enable directive and you’ll see two warnings. Ни свойство ErrorText , ни свойство NewsItems не инициализированы. Neither the ErrorText property nor the NewsItems property is initialized. Изучив этот класс, вы придете к выводу, что оба свойства должны быть ссылочного типа, допускающего значение null: оба имеют частные методы задания. An examination of this class would lead you to believe that both properties should be nullable reference types: Both have private setters. Один из этих методов назначается в методе OnGet . Exactly one is assigned in the OnGet method. Прежде чем вносить изменения, посмотрите на объекты-получатели обоих свойств. Before making changes, look at the consumers of both properties. На самой странице объект ErrorText проверяется на значение null перед созданием исправления ошибок. In the page itself, the ErrorText is checked against null before generating markup for any errors. Коллекция NewsItems проверяется на значение null , а также на наличие в ней элементов. The NewsItems collection is checked against null , and checked to ensure the collection has items. Чтобы быстро решить эту проблему, можно присвоить этим свойствам ссылочные типы, допускающие значение null. A quick fix would be to make both properties nullable reference types. Но лучше было бы сделать коллекцию ссылочного типа, не допускающего значение null, и добавлять элементы в существующую коллекцию при получении новостей. A better fix would be to make the collection a nonnullable reference type, and add items to the existing collection when retrieving news. Первое исправление заключается в добавлении ? к типу string для свойства ErrorText : The first fix is to add the ? to the string type for the ErrorText :

Это изменение не будет распространяться на другой код, потому что любой доступ к свойству ErrorText уже защищен проверками на значение null. That change won’t ripple through other code, because any access to the ErrorText property was already guarded by null checks. Далее инициализируйте список NewsItems и удалите метод задания свойств, сделав этот список свойством, доступным только для чтения: Next, initialize the NewsItems list and remove the property setter, making it a readonly property:

Это исправило предупреждение, но внесло ошибку. That fixed the warning but introduced an error. Список NewsItems теперь правильно сконструирован, но код, который устанавливает список в OnGet , нужно изменить, чтобы соответствовать новому API. The NewsItems list is now correct by construction, but the code that sets the list in OnGet must change to match the new API. Вместо присваивания вызовите метод AddRange , чтобы добавить элементы новостей в существующий список: Instead of an assignment, call AddRange to add the news items to the existing list:

Использование метода AddRange вместо присваивания означает, что метод GetNews может вернуть IEnumerable вместо List . Using AddRange instead of an assignment means that the GetNews method can return an IEnumerable instead of a List . Это экономит одно распределение. That saves one allocation. Измените сигнатуру метода и удалите вызов ToList , как показано в следующем примере кода: Change the signature of the method, and remove the ToList call, as shown in the following code sample:

Изменение сигнатуры также прерывает один из тестов. Changing the signature breaks one of tests as well. Откройте файл NewsServiceTests.cs в папке Services проекта SimpleFeedReader.Tests . Open the NewsServiceTests.cs file in the Services folder of the SimpleFeedReader.Tests project. Перейдите к тесту Returns_News_Stories_Given_Valid_Uri и измените тип переменной result на IEnumerable . Navigate to the Returns_News_Stories_Given_Valid_Uri test and change the type of the result variable to IEnumerable . Изменение типа означает, что свойство Count больше недоступно, поэтому замените свойство Count в классе Assert вызовом метода Any() : Changing the type means the Count property is no longer available, so replace the Count property in the Assert with a call to Any() :

Необходимо также добавить оператор using System.Linq в начало файла. You’ll need to add a using System.Linq statement to the beginning of the file as well.

Этот набор изменений уделяет особое внимание обновлению кода, который включает создание универсальных экземпляров. This set of changes highlights special consideration when updating code that includes generic instantiations. И список, и элементы в списке типов, не допускающих значение null. Both the list and the elements in the list of non-nullable types. Любой из них или оба могут быть типа, допускающего значение null. Either or both could be nullable types. Разрешены следующие объявления: All the following declarations are allowed:

• List : список, не допускающий значение null, моделей представлений, не допускающих значение null; List : nonnullable list of nonullable view models.
• List : список, не допускающий значение null, моделей представлений, допускающих значение null; List : nonnullable list of nullable view models.
• List ? : список, допускающий значение null, моделей представлений, не допускающих значение null; List ? : nullable list of nonnullable view models.
• List ? : список, допускающий значение null, моделей представлений, допускающих значение null. List ? : nullable list of nullable view models.

Интерфейсы с внешним кодом Interfaces with external code

Вы внесли изменения в класс NewsService , поэтому включите для него заметку #nullable enable . You’ve made changes to the NewsService class, so turn on the #nullable enable annotation for that class. После этого новые предупреждения больше не будут генерироваться. This won’t generate any new warnings. Однако тщательное изучение класса помогает проиллюстрировать некоторые ограничения анализа потоков компилятором. However, careful examination of the class helps to illustrate some of the limitations of the compiler’s flow analysis. Изучите следующий конструктор: Examine the constructor:

Параметр IMapper вводится в качестве ссылки, не допускающей значение null. The IMapper parameter is typed as a nonnullable reference. Он вызывается кодом инфраструктуры ASP.NET Core, поэтому компилятор не знает, что IMapper никогда не будет иметь значение null. It’s called by ASP.NET Core infrastructure code, so the compiler doesn’t really know that the IMapper will never be null. Контейнер по умолчанию для внедрения зависимостей ASP.NET Core генерирует исключение, если не может устранить необходимую службу, чтобы код оставался правильным. The default ASP.NET Core dependency injection (DI) container throws an exception if it can’t resolve a necessary service, so the code is correct. Компилятор не может проверить все вызовы ваших общедоступных API, даже если код скомпилирован с включенными контекстами заметок, допускающих значение null. The compiler can’t validate all calls to your public APIs, even if your code is compiled with nullable annotation contexts enabled. Кроме того, библиотеки могут использоваться в проектах, которые еще не перешли на ссылочные типы, допускающие значение null. Furthermore, your libraries may be consumed by projects that have not yet opted into using nullable reference types. Проверяйте входные данные для общедоступных API, даже если вы объявили их как типы, не допускающие значение null. Validate inputs to public APIs even though you’ve declared them as nonnullable types.

Получение кода Get the code

Вы исправили предупреждения, полученные в начальной тестовой компиляции, поэтому теперь можете включить контекст заметок, допускающих значение null, в обоих проектах. You’ve fixed the warnings you identified in the initial test compile, so now you can turn on the nullable annotation context for both projects. Перестройте проекты. Компилятор не выдаст ни одного предупреждения. Rebuild the projects; the compiler reports no warnings. Получить код готового проекта можно в репозитории GitHub dotnet/samples. You can get the code for the finished project in the dotnet/samples GitHub repository.

Новые возможности, поддерживающие ссылочные типы, допускающие значение null, помогают находить и исправлять потенциальные ошибки в обработке значений null в коде. The new features that support nullable reference types help you find and fix potential errors in how you handle null values in your code. Включение контекста заметок, допускающих значение null, позволяет выразить намерение проекта: некоторые переменные никогда не должны быть нулевыми, тогда как другие могут. Enabling the nullable annotation context allows you to express your design intent: some variables should never be null, other variables may contain null values. Используя эти возможности, проще выразить намерение проекта. These features make it easier for you to declare your design intent. Аналогичным образом контекст предупреждений о допустимости значения null указывает компилятору выдавать предупреждения при нарушении намерения проекта. Similarly, the nullable warning context instructs the compiler to issue warnings when you have violated that intent. Благодаря этим предупреждениям вы сможете внести обновления, которые сделают код более устойчивым и уменьшат вероятность создания исключений NullReferenceException во время выполнения. Those warnings guide you to make updates that make your code more resilient and less likely to throw a NullReferenceException during execution. Вы можете контролировать область этих контекстов, чтобы сосредоточиться на локальных областях кода, которые нужно перенести, пока оставшаяся база кода остается без изменений. You can control the scope of these contexts so that you can focus on local areas of code to migrate while the remaining codebase is untouched. На практике можно сделать эту задачу перехода частью регулярного обслуживания классов. In practice, you can make this migration task a part of regular maintenance to your classes. В этом руководстве продемонстрирован процесс перехода приложения на использование ссылочных типов, допускающих значение null. This tutorial demonstrated the process to migrate an application to use nullable reference types. Вы можете ознакомиться с гораздо большим реальным примером этого процесса, изучив запрос на вытягивание Джона Скита, созданный для перехода на ссылочные типы, допускающие значение null, в NodaTime. You can explore a larger real-world example of this process by examining the PR Jon Skeet made to incorporate nullable reference types into NodaTime. Кроме того, можно изучить приемы использования ссылочных типов, допускающих значения NULL, с Entity Framework Core. Or just In addition, you can learn techniques for using nullable reference types with Entity Framework Core in Entity Framework Core — Working with nullable reference types.