General Actions:
DevForce 2010 Resource Center » DevForce development » Start » EntityManager » EntityManager by task
Last modified on August 15, 2012 17:21
Contents
This page categories the public API of the EntityManager class by task type. The types of tasks largely parallel the high-level organization seen in the DevForce development tree-view.
This topic strives to be a birds-eye view of the EntityManager API from the perspective of some trying to grasp the scope and purpose of this, the most important and largest class in DevForce.
To that end, the API is presented in a task-oriented fashion, with API member categorized into major functional areas. For example, you will find the query-oriented members gathered together under the "Query" section. This affords a better appreciation of the scope and variety of query operations than you might obtain otherwise by sifting an alphabetical list of class members.
This is not a definitive list or description of EntityManager features. Only the API documentation for EntityManager is authoritative in that respect. The point of this topic is to orient you to the possibilities.
To that end, most of the public members of the EntityManager class are mentioned and receive a sentence or two of explanation.
Configure
The EntityManager members with which to configure a new EntityManager and learn about its current configuration. Constructors have been omitted.
A few members you can set or attach to:
| Member | Summary |
|---|---|
| AuthorizedThreadId | Get and set the id of the thread on which this manager can run. See the topic on thread safety for more information. |
| EntityManagerCreated | Static event raised whenever a new EntityManager is created. Useful for tracking and uniformly configuring the managers created in multiple EntityManager scenarios. |
| EntityServerError | Event raised when the EntityServer returns an exception for any reason. |
| DefaultEntityReferenceStrategy | Gets or sets the EntityReferenceStrategy to be used as a default for any navigation properties with an unspecified EntityReferenceStrategy |
| DefaultQueryStrategy | Gets or sets the QueryStrategy to be used as a default for any queries with an unspecified QueryStrategy. |
| DefaultSaveOptions | Gets or sets the SaveOptions to be used as a default for any save with unspecified SaveOptions. |
| Options | Access to the EntityManagerOptions controlling miscellaneous aspects of the EntityManager's behavior. |
| Tag | Get and set an arbitrary object. Useful for distinguishing one manager from another in multiple EntityManager scenarios. |
| UseAsyncNavigation | (Obsolete - Use the DefaultEntityReferenceStrategy above instead). Get and set whether property navigations that must retrieve related entities from the server will "lazy load" asynchronously. It is always true for a Silverlight EntityManager because all server requests must be asynchronous; you cannot set this value in Silverlight. It is false by default in full .NET environments where "lazy loads" tend to be performed synchronously but you can change it to true. |
| VerifierEngine | Get and set the DevForce validation engine assigned to this manager. This is the validation engine used by automatic property validation within a cached entity. |
Many of the configuration members you can only read:
| Member | Summary |
|---|---|
| CompositionContext | Gets the CompositionContext instance that helps determine how MEF will compose some of the components that support this manager, a key part of the DevForce extensibilty story. You establish the manager's CompositionContext when you construct it. |
| DataSourceExtension | Get the string that identifies the data source targeted by this manager. You set the manager's DataSourceExtension when you construct it. |
| EntityServiceOption | The enumeration indicating whether the manager connects to a remote service (n-Tier), a local service (2-tier) or uses the setting from the configuration file. You establish the manager's EntityServiceOption when you construct it. |
| IsClient | Whether the manager is running on a client or on the server. The valus is usually true - meaning the manager is running on the client - but a number of processes on the server are provided with a server-side EntityManager; the EntityServer interceptor classes and your custom remote service methods are good examples. The value would be false for these server-side EntityManagers. |
| MetadataStore | Get the application-wide EntityMetadataStore, the store of metadata about all currently known entity types in the application. |
| UsesDistributedEntityService | Get whether this EntityManager communicates with a remote server as it must for a Silverlight EntityManager. It is false for 2-tier deployments. |
Query
The EntityManager members related to querying entities, either from remote data sources or from its entity cache.
Many of the members that can fetch entities from the server come in both synchronous and asynchronous versions. The asynchronous versions can be used on any client EntityManager. The synchronous versions are only available for regular .NET clients and also can be used by custom server methods calling into a server-side EntityManager. You cannot use (or even see) these synchronous methods on a Silverlight EntityManager.
Members that read exclusively from the entity cache are always synchronous and are available to all EntityManagers, including Silverlight EntityManagers.
| Member | Summary |
|---|---|
| ExecuteQuery | Synchronously executes its IEntityQuery query argument, returning an untyped IEnumerable of entities. Not available in Silverlight. |
| ExecuteQuery<T> | Synchronously executes its strongly typed IEntityQuery<T> query argument, returning an IEnumerable<T> of T-type entities. Not available in Silverlight. |
| ExecuteQueryAsync | Executes asynchronously its IEntityQuery query argument. An untyped IEnumerable of entities is returned in the completed event args. |
| ExecuteQueryAsync<T> | Executes asynchronously its strongly typed IEntityQuery<T> query argument. , An IEnumerable<T> of "T" entities is returned in the completed event args. |
| ExecuteQueryForObject | Synchronously executes its IEntityQuery query argument, returning a single, untyped object such as a count or the first entity that satisfies the query criteria. Not available in Silverlight. |
| ExecuteQueryForObjectAsync<T> | Executes asynchronously its strongly-typed IEntityQuery<T> query argument. A a single, untyped object, such as an integer count or the first entity that satisfies the query criteria, is returned in the completed event args. |
| FindEntities<T> | Searches the entity cache for entities of type "T" which also have an entitystate that matches one of the flag values in the EntityState argument. |
| FindEntities | Searches the entity cache for all entities whose entitystate matches one of the flag values the EntityState argument. Can optionally limit the search to entities of a specified type. |
| FindEntity | Searches the entity cache for an entity with a given EntityKey. By default the search would not return a deleted entity with that key but you can indicate with a boolean flag that you want the entity if it is deleted. |
| FindEntityGraph | Searches the entity cache for the entity "roots" passed as arguments to the method and also returns the entities related to those root entities. The "entity graph" is the combination of a root and its related entities. The extent of the graph is defined by the relationships identified in the EntitySpan argument. |
| GetNullEntity<T> | Get the "null entity" (aka, the "nullo") for the entity type "T" that represents the "entity not found". Reference navigation from an entity-in-cache (e.g., anOrder.Customer) returns the "nullo" rather than null if the entity can't be found. |
| GetNullEntity | The untyped variant of GetNullEntity<T>. |
| GetQuery<T> | Returns an EntityQuery<T> that, if executed, would query for all entities of type "T". The statement, manager.GetEntity<Customer>()), returns a query that, if executed, would retrieve all customers in the database. It is typically the foundation query to which the developer adds filter clauses to narrow the search. |
| RefetchEntities | Refreshes the entities identified in the method arguments with the most recent data available from the database. A synchronous method that is not available in Silverlight. |
| RefetchEntitiesAsync | The asynchronous version of RefetchEntities that is available in Silverlight. |
Some EntityManager members notify subscribers about query activity.
| Member | Summary |
|---|---|
| Querying | A cancellable event raised when the manager is about to process a query. The manager has not yet determined if it will satisfy the query from its entity cache or will have to go to the server for entities. It is raised before Fetching. |
| OnQuerying | The virtual method that a derived EntityManager can override to raise the Querying event. |
| Fetching | A cancellable event raised when the manager, while processing a query, has determined that it must go to the server for entities. It is raised before sending a query to the server. It won't be raised if the manager expects to satisfy the query entirely from its entity cache. Compare to Querying. |
| OnFetching | The virtual method that a derived EntityManager can override to raise the Fetching event. |
| Queried | An event raised by the manager after it has processed a query request successfully; not raised if the query failed. The query may or may not have fetched data from the server. If it did, the event is raised after entities were retrieved successfully and merged into the entity cache. The EventArgs can tell you whether the query involved a trip to the server and, if so, which of the entities retrieved from the server (including related entities) resulted in changes to the entity cache. |
| OnQueried | The virtual method that a derived EntityManager can override to raise the Queried event. |
Finally, a few query-control members.
| Member | Summary |
|---|---|
| CancelAsync | Cancel a pending asynchronous query. Actually not just for canceling queries. It can cancel any unfinished asynchronous operation but it is most often used to cancel queries. |
| DefaultQueryStrategy | Get and set the QueryStrategy the manager should use if the query itself does not specify a QueryStrategy. |
| QueryCache | Get the manager's QueryCache, the special cache that remembers previously issued queries. The manager may decide to fulfill a new query request entirely from its entity cache if the manager finds the query in its QueryCache. Adding and removing queries from the QueryCache is largely automatic but you can manipulate it directly once you gain access to it through this property. |
Save
The EntityManager members related to saving cached entities with pending changes.
| Member | Summary |
|---|---|
| DefaultSaveOptions | Gets or sets the SaveOptions to be used as a default for any save with unspecified SaveOptions. |
| HasChanges | Get whether the manager's entity cache contains a changed entity. More specifically whether the entitystate of any cached entity is other than Unchanged. |
| SaveChanges | Save synchronously all changed entities in cache. Overloads accept optional parameters such as callback delegate, SaveOptions, and a caller-defined "user-state" object to keep track of and differentiate individual save calls. The returned SaveResult provides information about success or failure and the entities that were saved. Because synchronous, it is not available in Silverlight. |
| SaveChanges (entities, ...) | A SaveChanges variant that saves just the entities specified in the argument |
| SaveChangesAsync | Save asynchronously all changed entities in cache. Same overloads as SaveChange. Because asynchronous, the completed event args provide information about success or failure and the entities that were saved. This method is available on all .NET clients, including Silverlight. |
| SaveChangesAsync (entities, ...) | A SaveChangesAsync variant that saves just the entities specified in the argument |
Some EntityManager members notify subscribers about save activity.
| Member | Summary |
|---|---|
| Saving | A cancellable event raised when the manager is about to save. The manager provides the handler with a list of entities it intends to save. |
| OnSaving | The virtual method that a derived EntityManager can override to raise the Saving event. |
| Saved | A cancellable event raised when the manager has saved successfully; not raised if the save failed. The event args provide information about success or failure and the entities that were saved. |
| OnSaved | The virtual method that a derived EntityManager can override to raise the Saved event. |
Finally, a few save-control members for special situations.
| Member | Summary |
|---|---|
| ForceIdFixup | Immediately replace the temporary ids of newly-created entities with server-generated permanent ids for entities whose keys are generated by a custom method. The save process performs this "fix-up" automatically but you can force it to happen sooner. Because synchronous, it is not available in Silverlight. |
| ForceIdFixupAsync | The asynchronous version of ForceIdFixup available on all .NET clients including Silverlight. |
Access the entity cache
Some EntityManager members yield insights into the manager's entity cache.
| Member | Summary |
|---|---|
| IsEntityLoaded(key) | Whether an entity with given EntityKey is in the manager's cache. |
| CacheStateManager | Get the manager's CacheStateManager through which you can save and restore a copy of the entity cache in the form of an EntityCacheState. |
| GetEntityGroup,T> | Get the EntityGroup inside the cache that holds the cached instances of type "T". |
| GetEntityGroup | The non-generic version of GetEntityGroup<T> takes the entity type as a parameter. |
| GetEntityGroups | Get an array of all EntityGroups in the cache. There will be a group for every type the cache has ever seen. |
Many operations move entities into and out of a manager's entity cache automatically. You can manipulate this cache directly using these EntityManager members.
| Member | Summary |
|---|---|
| AddEntities | Add entities to the cache as if they were new, Added entities that do not exist in the database and will be inserted if saved. |
| AddEntity | Add an entity to the cache as if it were a new, Added entity that does not exist in the database and will be inserted if saved. |
| AttachEntities | Attach entities to the cache as if they were pre-existing, Unchanged entities that might have been queried from the database. |
| AttachEntity | Attach an entity to the cache as if it were a pre-existing, Unchanged entity that might have been queried from the database. |
| Clear | Clear the cache, emptying it of all entities. Also clears the QueryCache described in the Query section above. |
| Cleared | Event raised when Clear is called. |
| RemoveEntities (entityState, ...) | Remove all entities with the given entitystate, optionally clearing the QueryCache (the default) |
| RemoveEntities (entities, ...) | Remove the entities in the argument, optionally clearing the QueryCache (the default). |
| RemoveEntities (entityType, entityState) | Remove entities of a particular and entitystate, optionally clearing the QueryCache (the default). |
| RemoveEntity | Remove the entity, optionally clearing the QueryCache (the default). |
| ImportEntities | Import shallow copies of the entities into the cache, merging them according to the provided MergeStrategy. |
Create, modify and delete
These methods assist the developer in the course of creating, modifying and deleting entities.
| Member | Summary |
|---|---|
| AcceptChanges | Treat all entities with pending changes as if they had been saved. They should appear as if they had been freshly retrieved from the database. Added and Modified entities become Unchanged, their current version values overwrite their original version values. Deleted entities are removed from cache, becoming Detached. |
| RejectChanges | Rollback all entities with pending changes. They should appear as if they had been freshly retrieved from the database. Deleted and Modified entities become Unchanged, their current version values restored from their original version values. Added entities are removed from cache, becoming Detached. |
| CreateEntity<T> | Create new entity of type "T"; the entity remains detached although the entity retains the inaccessible memory of the manager that created it. |
| CreateEntity | Create an entity dynamically with this non-geneneric version of CreateEntity. |
| EntityChanging | Cancellable event raised when a cached entity is about to change, e.g., an entity is about to be added, modified, attached, queried, imported, deleted, detached, committed or rolled back. |
| EntityChanged | Event raised when a cached entity has changed, e.g., an entity was added, modified, attached, queried, imported, deleted, deEtached, committed or rolled back. |
| GenerateId | Generate a temporary id for a newly created entity that requires custom Id generation; that temp id becomes permanent during save as result of an id fix-up process. |
Miscellaneous server calls
The EntityManager is often the application's sole channel for all communications with the server. Most communications concern data. Security and other kinds of server communications are addressed by the following members.
Connectivity
By default, the EntityManager automatically and immediately tries to connect to the server upon construction. But you may have to connect and disconnect for a variety of reasons with a method listed here:
| Member | Summary |
|---|---|
| Connect | Connect to the server explicitly and synchronously. Not available in Silverlight because synchronous. |
| ConnectAsync | Connect to the server explicitly asynchronously. Available on all client platforms. |
| Disconnect | Disconnect the manager deliberately and continue running offline. |
| IsConnected | Get whether this manager believes it is connected to the server. |
| ConnectionStateChanged | Event raised when the connection state of the manager to the EntityServer changes. |
Secure
We devote a full topic to security elsewhere. In brief, all DevForce EntityManager instances must have acquired a local security context before performing most server operations. The manager may acquire that context implicitly (as when relying upon cookie-based security) or explicitly with some of these EntityManager methods.
| Member | Summary |
|---|---|
| AuthenticationContext | Get or set the security context used by this manager. |
The EntityManager includes several security-related members which have been deprecated. The list below describes these members, and indicates what to use in its place.
| Member | Summary |
|---|---|
| IsLoggedIn | Get whether this manager is currently authenticated. Use AuthenticationContext.LoginState instead. |
| LinkForAuthentication | Link this manager's security context to that of the source EntityManager passed as a parameter. Enables multiple EntityManagers to share the security context of a single master EntityManager that can login and logout on their behalf. |
| Login | Login (authenticate) synchronously with the server using the supplied credentials. Not available in Silverlight because synchronous. Use Authenticator.Login instead. |
| LoginAsync | The asynchronous variant of Login, available on all client technologies. Use Authenticator.LoginAsync instead. |
| Logout | Logout (de-authenticate) synchronously with the server. The server will not accept new requests from this manager until it logs-in again. Not available in Silverlight because synchronous. Use Authenticator.Logout instead. |
| LogoutAsync | The asynchronous variant of Logout, available on all client technologies. Use Authenticator.LogoutAsync instead. |
| Principal | Get the IPrincipal instance that identifies the current user and his/her roles. The concrete instance is often a richer, custom IPrincipal implementation such as a derivative of the DevForce UserBase class. Use AuthenticationContext.Principal instead. |
Remote Service Method
The client may call a custom application method on the application server using one of these two Invoke... methods. These methods are untyped, affording the developer the ultimate luxury of sending almost anything as parameters and receiving almost any kind of result. The developer should consider wrapping these commands in a type-safe manner before exposing them to higher level application layers.
| Member | Summary |
|---|---|
| InvokeServerMethod | Call a remote server method synchronously, passing in optional service method parameters of any type. The parameters must be both serializable and understood by the server method. InvokeServerMethod returns the object result that was itself returned by the remote server method. The client may cast the result or otherwise interpret it as best it can. Not available in Silverlight because synchronous. |
| InvokeServerMethodAsync | The asynchronous variant of InvokeServerMethod, available on all .NET clients. Because it is asynchronous, the value returned by the remote service method becomes accessible on the client in the callback's event args. |
Push notification
Two asynchronous members are involved in the server notification service (aka, Push).
| Member | Summary |
|---|---|
| RegisterCallback | Register a callback method with notification service on the server, include a userToken and pass in optional service parameters. The callback gets called with each notification until it is cancelled. |
| CancelCallback | Unsubscribe to the notification service by cancelling the callback via its associated userToken. |