数据序列化如何影响应用程序升级How data serialization affects an application upgrade

应用程序滚动升级过程中,升级应用于部分节点,一次一个升级域。In a rolling application upgrade, the upgrade is applied to a subset of nodes, one upgrade domain at a time. 在此过程中,一些升级域位于较新版本的应用程序上,而一些升级域位于较旧版本的应用程序上。During this process, some upgrade domains are on the newer version of your application, and some upgrade domains are on the older version of your application. 在滚动更新期间,新版本的应用程序必须能够读取旧版本的数据,并且旧版本的应用程序必须能够读取新版本的数据。During the rollout, the new version of your application must be able to read the old version of your data, and the old version of your application must be able to read the new version of your data. 如果数据格式不向前和向后兼容,则升级可能会失败(或更糟),甚至可能丢失数据。If the data format is not forward and backward compatible, the upgrade may fail, or worse, data may be lost or corrupted. 本文介绍数据格式的构成,并提供确保数据向前和向后兼容的最佳实践。This article discusses what constitutes your data format and offers best practices for ensuring that your data is forward and backward compatible.

数据格式由哪些部分构成?What makes up your data format?

在 Azure Service Fabric 中,保留和复制的数据来自于 C# 类。In Azure Service Fabric, the data that is persisted and replicated comes from your C# classes. 对于使用 Reliable Collections 的应用程序,此数据是可靠字典和队列中的对象。For applications that use Reliable Collections, that data is the objects in the reliable dictionaries and queues. 对于使用 Reliable Actors 的应用程序,它是执行组件的备用状态。For applications that use Reliable Actors, that is the backing state for the actor. 这些 C# 类必须可序列化,以进行保留和复制。These C# classes must be serializable to be persisted and replicated. 因此,数据格式由已序列化的字段和属性及其序列化方式定义。Therefore, the data format is defined by the fields and properties that are serialized, as well as how they are serialized. 例如,在 IReliableDictionary<int, MyClass> 中,数据是一个序列化的 int 和一个序列化的 MyClassFor example, in an IReliableDictionary<int, MyClass> the data is a serialized int and a serialized MyClass.

导致数据格式更改的代码更改Code changes that result in a data format change

由于数据格式由 C# 类确定,所以对类进行更改可能会导致数据格式更改。Since the data format is determined by C# classes, changes to the classes may cause a data format change. 必须格外小心,以确保滚动升级可以处理数据格式更改。Care must be taken to ensure that a rolling upgrade can handle the data format change. 可能会导致数据格式更改的示例:Examples that may cause data format changes:

  • 添加或删除字段或属性Adding or removing fields or properties
  • 重命名字段或属性Renaming fields or properties
  • 更改字段或属性的类型Changing the types of fields or properties
  • 更改类名或命名空间Changing the class name or namespace

用作默认序列化程序的数据约定Data Contract as the default serializer

序列化程序通常负责读取数据并将其反序列化到当前版本中,即使该数据位于较旧或较新版本中。The serializer is generally responsible for reading the data and deserializing it into the current version, even if the data is in an older or newer version. 默认序列化程序是 数据协定序列化程序,它具有定义完善的版本控制规则。The default serializer is the Data Contract serializer, which has well-defined versioning rules. Reliable Collections 允许替代序列化程序,但 Reliable Actors 目前不允许。Reliable Collections allow the serializer to be overridden, but Reliable Actors currently do not. 数据序列化程序在启用滚动升级中扮演着重要的角色。The data serializer plays an important role in enabling rolling upgrades. 数据协定序列化程序是建议用于 Service Fabric 应用程序的序列化程序。The Data Contract serializer is the serializer that we recommend for Service Fabric applications.

数据格式如何影响滚动升级How the data format affects a rolling upgrade

滚动升级期间,主要在两种情景下序列化程序可能会遇到较旧的数据版本或 较新 的数据版本:During a rolling upgrade, there are two main scenarios where the serializer may encounter an older or newer version of your data:

  1. 节点升级并启动备份后,新的序列化程序会加载旧版本保留到磁盘的数据。After a node is upgraded and starts back up, the new serializer will load the data that was persisted to disk by the old version.
  2. 滚动升级期间,群集中将混合新旧版本的代码。During the rolling upgrade, the cluster will contain a mix of the old and new versions of your code. 由于副本可能放置在不同的升级域中,并且副本会相互发送数据,因此新和/或旧版本的序列化程序可能会遇到新和/或旧版本的数据。Since replicas may be placed in different upgrade domains, and replicas send data to each other, the new and/or old version of your data may be encountered by the new and/or old version of your serializer.

备注

此处的“新版本”和“旧版本”是指正在运行的代码版本。The "new version" and "old version" here refer to the version of your code that is running. “新序列化程序”是指在新版本的应用程序中执行的序列化程序代码。The "new serializer" refers to the serializer code that is executing in the new version of your application. “新数据”是指新版本的应用程序中已序列化的 C# 类。The "new data" refers to the serialized C# class from the new version of your application.

代码和数据格式的两个版本必须同时向前和向后兼容。The two versions of code and data format must be both forward and backward compatible. 如果它们不兼容,则滚动升级可能失败,甚至可能丢失数据。If they are not compatible, the rolling upgrade may fail or data may be lost. 滚动升级可能失败,因为代码或序列化程序在遇到另一个版本时可能会引发异常或错误。The rolling upgrade may fail because the code or serializer may throw exceptions or a fault when it encounters the other version. 例如,如果添加了一个新属性,但旧的序列化程序在反序列化期间弃用了该新属性,则数据可能会丢失。Data may be lost if, for example, a new property was added but the old serializer discards it during deserialization.

数据协定是为确保数据兼容所建议的解决方案。Data Contract is the recommended solution for ensuring that your data is compatible. 它具有定义完善的版本控制规则,可用于添加、删除和更改字段。It has well-defined versioning rules for adding, removing, and changing fields. 它还支持处理未知字段、挂接到序列化和反序列化过程以及类继承。It also has support for dealing with unknown fields, hooking into the serialization and deserialization process, and dealing with class inheritance. 有关详细信息,请参阅 使用数据协定For more information, see Using Data Contract.

后续步骤Next steps

Upgrading your Application Using Visual Studio (使用 Visual Studio 升级应用程序)逐步讲解了如何使用 Visual Studio 进行应用程序升级。Upgrading your Application Using Visual Studio walks you through an application upgrade using Visual Studio.

使用 Powershell 升级应用程序逐步讲解了如何使用 PowerShell 进行应用程序升级。Upgrading your Application Using Powershell walks you through an application upgrade using PowerShell.

使用升级参数来控制应用程序的升级方式。Control how your application upgrades by using Upgrade Parameters.

参考高级主题,了解如何在升级应用程序时使用高级功能。Learn how to use advanced functionality while upgrading your application by referring to Advanced Topics.

参考 Troubleshooting Application Upgrades(对应用程序升级进行故障排除)中的步骤来解决应用程序升级时的常见问题。Fix common problems in application upgrades by referring to the steps in Troubleshooting Application Upgrades.