自跟踪实体Self-tracking entities

重要

我们不再建议使用自跟踪实体模板。We no longer recommend using the self-tracking-entities template. 它将仅继续用于支持现有应用程序。It will only continue to be available to support existing applications. 如果应用程序需要使用断开连接的实体图,请考虑其他替代方案,例如可跟踪实体,它与自跟踪实体类似,社区在更积极地开发这种技术,或使用低级别更改跟踪 API 编写自定义代码。If your application requires working with disconnected graphs of entities, consider other alternatives such as Trackable Entities, which is a technology similar to Self-Tracking-Entities that is more actively developed by the community, or writing custom code using the low-level change tracking APIs.

在基于实体框架的应用程序中,上下文负责跟踪对象中的更改。In an Entity Framework-based application, a context is responsible for tracking changes in your objects. 然后,使用 SaveChanges 方法将更改保存到数据库。You then use the SaveChanges method to persist the changes to the database. 使用 N 层应用程序时,实体对象通常会从上下文断开连接,用户必须决定如何跟踪更改并向上下文报告这些更改。When working with N-Tier applications, the entity objects are usually disconnected from the context and you must decide how to track changes and report those changes back to the context. 自跟踪实体 (STE) 有助于跟踪任意层中的更改,之后可将这些更改重放入上下文中进行保存。Self-Tracking Entities (STEs) can help you track changes in any tier and then replay these changes into a context to be saved.

仅当上下文在更改对象图所在的层上不可用时才使用 STE。Use STEs only if the context is not available on a tier where the changes to the object graph are made. 如果上下文可用,则无需使用 STE,因为上下文将负责跟踪更改。If the context is available, there is no need to use STEs because the context will take care of tracking changes.

此模板项会生成两个 .tt(文本模板)文件:This template item generates two .tt (text template) files:

  • <model name>.tt 文件可生成实体类型、包含自跟踪实体使用的更改跟踪逻辑的 Helper 类以及允许设置自跟踪实体的状态的扩展方法。The <model name>.tt file generates the entity types and a helper class that contains the change-tracking logic that is used by self-tracking entities and the extension methods that allow setting state on self-tracking entities.
  • <model name>.Context.tt 文件生成派生的上下文和扩展类,该类包含 ObjectContext 和 ObjectSet 类的 ApplyChanges 方法。The <model name>.Context.tt file generates a derived context and an extension class that contains ApplyChanges methods for the ObjectContext and ObjectSet classes. 这些方法检查自跟踪实体图中包含的更改跟踪信息,以推断在数据库中保存这些更改所必须执行的一组操作。These methods examine the change-tracking information that is contained in the graph of self-tracking entities to infer the set of operations that must be performed to save the changes in the database.

入门Get Started

若要开始操作,请访问自跟踪实体演练页。To get started, visit the Self-Tracking Entities Walkthrough page.

使用自跟踪实体时的功能性注意事项Functional Considerations When Working with Self-Tracking Entities

重要

我们不再建议使用自跟踪实体模板。We no longer recommend using the self-tracking-entities template. 它将仅继续用于支持现有应用程序。It will only continue to be available to support existing applications. 如果应用程序需要使用断开连接的实体图,请考虑其他替代方案,例如可跟踪实体,它与自跟踪实体类似,社区在更积极地开发这种技术,或使用低级别更改跟踪 API 编写自定义代码。If your application requires working with disconnected graphs of entities, consider other alternatives such as Trackable Entities, which is a technology similar to Self-Tracking-Entities that is more actively developed by the community, or writing custom code using the low-level change tracking APIs.

使用自跟踪实体时应考虑以下事项:Consider the following when working with self-tracking entities:

  • 确保您的客户端项目具有对包含实体类型的程序集的引用。Make sure that your client project has a reference to the assembly containing the entity types. 如果您只将服务引用添加到客户端项目,则客户端项目将使用 WCF 代理类型,而不是实际的自跟踪实体类型。If you add only the service reference to the client project, the client project will use the WCF proxy types and not the actual self-tracking entity types. 这意味着您将不能获得管理客户端上实体跟踪的自动通知功能。This means that you will not get the automated notification features that manage the tracking of the entities on the client. 如果您不希望包含实体类型,则必须手动设置客户端的更改跟踪信息以便将更改发送回服务。If you intentionally do not want to include the entity types, you will have to manually set change-tracking information on the client for the changes to be sent back to the service.

  • 对服务操作的调用应是无状态的,并且创建一个新的对象上下文实例。Calls to the service operation should be stateless and create a new instance of object context. 同样建议在 using 块中创建对象上下文****。We also recommend that you create object context in a using block.

  • 如果在将客户端上已修改的图发送到服务后想要在客户端上继续使用同一张图,则必须手动循环访问该图,并对每个对象调用 AcceptChanges 方法以重置更改跟踪器****。When you send the graph that was modified on the client to the service and then intend to continue working with the same graph on the client, you have to manually iterate through the graph and call the AcceptChanges method on each object to reset the change tracker.

    如果图中的对象包含具有数据库生成的值(例如,标识值或并发值)的属性,则在调用 SaveChanges 方法后,实体框架将把这些属性的值替换为数据库生成的值****。If objects in your graph contain properties with database-generated values (for example, identity or concurrency values), Entity Framework will replace values of these properties with the database-generated values after the SaveChanges method is called. 可实现服务操作以返回保存的对象或生成的属性值列表,从而将对象发送回客户端。You can implement your service operation to return saved objects or a list of generated property values for the objects back to the client. 然后,客户端需要将对象实例或对象属性值替换为从服务操作返回的对象或属性值。The client would then need to replace the object instances or object property values with the objects or property values returned from the service operation.

  • 合并多个服务请求的关系图可能会在生成的关系图中引入具有重复键值的对象。Merging graphs from multiple service requests may introduce objects with duplicate key values in the resulting graph. 调用 ApplyChanges 方法时,实体框架不会删除具有重复键的对象,但会引发异常****。Entity Framework does not remove the objects with duplicate keys when you call the ApplyChanges method but instead throws an exception. 为了避免生成具有重复键值的图,请遵循以下博客中所述的模式之一:自跟踪实体:ApplyChanges 和重复实体To avoid having graphs with duplicate key values follow one of the patterns described in the following blog: Self-Tracking Entities: ApplyChanges and duplicate entities.

  • 当您通过设置外键属性更改对象之间的关系时,引用导航属性设置为 Null,并且不同步到客户端上的相应主体实体。When you change the relationship between objects by setting the foreign key property, the reference navigation property is set to null and not synchronized to the appropriate principal entity on the client. 将图附加到对象上下文之后(例如,调用 ApplyChanges 方法之后),会同步外键属性和导航属性****。After the graph is attached to the object context (for example, after you call the ApplyChanges method), the foreign key properties and navigation properties are synchronized.

    如果您已对外键关系指定级联删除,则引用导航属性与相应主体对象不同步会是个问题。Not having a reference navigation property synchronized with the appropriate principal object could be an issue if you have specified cascade delete on the foreign key relationship. 如果您删除了主体,则这种删除将不会传播到依赖对象。If you delete the principal, the delete will not be propagated to the dependent objects. 如果您已指定级联删除,则使用导航属性更改关系,而不是设置外键属性。If you have cascade deletes specified, use navigation properties to change relationships instead of setting the foreign key property.

  • 执行延迟加载时不启用自跟踪实体。Self-tracking entities are not enabled to perform lazy loading.

  • 自跟踪实体不支持二进制序列化和针对 ASP.NET 状态管理对象的序列化。Binary serialization and serialization to ASP.NET state management objects is not supported by self-tracking entities. 但是,您可以自定义此模板来添加二进制序列化支持。However, you can customize the template to add the binary serialization support. 有关详细信息,请参阅将二进制序列化和 ViewState 用于自跟踪实体For more information, see Using Binary Serialization and ViewState with Self-Tracking Entities.

安全注意事项Security Considerations

使用自跟踪实体时,应考虑以下安全注意事项:The following security considerations should be taken into account when working with self-tracking entities:

  • 服务不应信任从不受信任的客户端或通过不受信任的通道检索或更新数据的请求。A service should not trust requests to retrieve or update data from a non-trusted client or through a non-trusted channel. 客户端必须经身份验证:应使用安全通道或消息信封。A client must be authenticated: a secure channel or message envelope should be used. 必须验证客户端更新或检索数据的请求,从而确保这些请求符合对于给定方案合法的预期更改。Clients' requests to update or retrieve data must be validated to ensure they conform to expected and legitimate changes for the given scenario.
  • 避免将敏感信息用作实体键(例如身份证号码)。Avoid using sensitive information as entity keys (for example, social security numbers). 这样可降低意外地将自跟踪实体图中的敏感信息序列化到不完全可信的客户端的可能性。This mitigates the possibility of inadvertently serializing sensitive information in the self-tracking entity graphs to a client that is not fully trusted. 通过使用独立关联,实体中与正在序列化的键相关的原始键也可能会发送到客户端。With independent associations, the original key of an entity that is related to the one that is being serialized might be sent to the client as well.
  • 为了避免向客户端层传播包含敏感数据的异常消息,应将服务器层上对 ApplyChanges 和 SaveChanges 的调用包装到异常处理代码中********。To avoid propagating exception messages that contain sensitive data to the client tier, calls to ApplyChanges and SaveChanges on the server tier should be wrapped in exception-handling code.