Соображения относительно версии и обновления для разработчиков на C#Version and update considerations for C# developers

Совместимость очень важна при добавлении новых функций языка C#.Compatibility is a very important goal as new features are added to the C# language. В большинстве случаев существующий код сможет компилироваться в новой версии компилятора безо всяких проблем.In almost all cases, existing code can be recompiled with a new compiler version without any issue.

Особое внимание требуется в тех случаях, когда в библиотеку добавляются новые возможности языка.More care may be required when you adopt new language features in a library. Например, если вы создаете новую библиотеку с функциями из последней версии, но ее должны использовать приложения, созданные в предыдущих версиях компилятора.You may be creating a new library with features found in the latest version and need to ensure apps built using previous versions of the compiler can use it. Или же вы обновляете существующую библиотеку, но многие ваши пользователи пока используют старые версии.Or you may be upgrading an existing library and many of your users may not have upgraded versions yet. Принимая решения о внедрении новых функций, необходимо учесть два аспекта совместимости: на уровне исходного кода и на уровне двоичных файлов.As you make decisions on adopting new features, you'll need to consider two variations of compatibility: source compatible and binary compatible.

Изменения, совместимые на уровне двоичных файловBinary compatible changes

Изменения библиотеки считаются совместимыми на уровне двоичных файлов, если новую версию библиотеки можно использовать без повторной сборки приложении и других библиотек, которые ее используют.Changes to your library are binary compatible when your updated library can be used without rebuilding applications and libraries that use it. В этом сценарии не нужно перестраивать зависимые сборки и (или) вносить изменения в исходный код.Dependent assemblies are not required to be rebuilt, nor are any source code changes required. Измерения, совместимые на уровне двоичных файлов, всегда совместимы и на уровне исходного кода.Binary compatible changes are also source compatible changes.

Изменения, совместимые на уровне исходного кодаSource compatible changes

Изменения библиотеки будут совместимыми на уровне исходного кода, если для приложений и библиотек, которые используют новую библиотеку, не потребуется изменять исходный код, но для правильной работы нужно заново скомпилировать их с новой версией.Changes to your library are source compatible when applications and libraries that use your library do not require source code changes, but the source must be recompiled against the new version to work correctly.

Несовместимые измененияIncompatible changes

Если изменение не является совместимым ни на уровне исходного кода, ни на уровне двоичных файлов, для зависимых приложений и библиотек потребуется изменить исходный код и заново скомпилировать их.If a change is neither source compatible nor binary compatible, source code changes along with recompilation are required in dependent libraries and applications.

Оценка существующих библиотекEvaluate your library

Эти концепции совместимости влияют на компоненты библиотеки с атрибутами public и protected, но не на ее внутреннюю реализацию.These compatibility concepts affect the public and protected declarations for your library, not its internal implementation. Любые новые возможности внутри библиотеки всегда совместимы на уровне двоичных файлов.Adopting any new features internally are always binary compatible.

К совместимым на уровне двоичных файлов изменениям относится любой новый синтаксис, который создает такой же скомпилированный код любых открытых (public) объявлений, как и со старым синтаксисом.Binary compatible changes provide new syntax that generates the same compiled code for public declarations as the older syntax. Например, замена метода на член, воплощающий выражение, будет совместимым на уровне двоичных файлов изменением.For example, changing a method to an expression-bodied member is a binary compatible change:

Исходный код:Original code:

public double CalculateSquare(double value)
{
    return value * value;
}

Новый код:New code:

public double CalculateSquare(double value) => value * value;

Изменения, совместимые на уровне исходного кода, создают новый синтаксис, который изменяет скомпилированный код одного или нескольких открытых (public) членов таким образом, который сохраняет его совместимость со всеми существующими вызывающими объектами.Source compatible changes introduce syntax that changes the compiled code for a public member, but in a way that is compatible with existing call sites. Например, если подпись метода ранее передавала параметр по значению, а теперь содержит in с параметром по ссылке, такое изменение будет совместимым на уровне исходного кода, но не на уровне двоичных файлов:For example, changing a method signature from a by value parameter to an in by reference parameter is source compatible, but not binary compatible:

Исходный код:Original code:

public double CalculateSquare(double value) => value * value;

Новый код:New code:

public double CalculateSquare(in double value) => value * value;

Во всех статьях о новых возможностях всегда указано, является ли новая функция для открытых объявлений совместимый на уровне исходного кода или на уровне двоичных файлов.The What's new articles note if introducing a feature that affects public declarations is source compatible or binary compatible.