Specifica del manifesto del providerProvider Manifest Specification

Questa sezione illustra come un provider dell'archivio dati può supportare i tipi e le funzioni di tale archivio.This section discusses how a data store provider can support the types and functions in the data store.

I servizi di entità funzionano indipendentemente da un provider dell'archivio dati specifico, tuttavia consentono comunque a un provider di dati di definire in modo esplicito l'interazione di modelli, mapping e query con un archivio dati sottostante.Entity Services operates independently of a specific data store provider yet still allows a data provider to explicitly define how models, mappings, and queries interact with an underlying data store. Su un piano prettamente pratico, i servizi di entità potrebbero essere destinati solo a un provider di dati o a un archivio dati specifico.Without a layer of abstraction, Entity Services could only be targeted at a specific data store or data provider.

I tipi supportati dal provider sono supportati direttamente o indirettamente dal database sottostante.Types that the provider supports are directly or indirectly supported by the underlying database. Tali tipi no sono necessariamente i tipi di archivio, bensì i tipi usati dal provider per supportare Entity FrameworkEntity Framework.These types are not necessarily the exact store types, but the types the provider uses to support the Entity FrameworkEntity Framework. I tipi di archivio/provider vengono descritti in termini EDM (Entity Data Model).Provider/store types are described in the Entity Data Model (EDM) terms.

I tipi di parametri e i tipi restituiti per le funzioni supportate dall'archivio dati vengono specificati in termini EDM.Parameter and return types for the functions supported by the data store are specified in EDM terms.

RequisitiRequirements

Entity FrameworkEntity Framework e l'archivio dati devono essere in grado di passare i dati da e verso tipi noti senza troncamento o perdita di dati.The Entity FrameworkEntity Framework and the data store need to be able to pass data back and forth in known types without any data loss or truncation.

Il manifesto del provider deve essere caricabile dagli strumenti in fase di progettazione senza che sia necessario aprire una connessione all'archivio dati.The provider manifest must be loadable by tools at design time without having to open a connection to the data store.

Il Entity FrameworkEntity Framework avviene sensibili, ma potrebbe non essere nell'archivio dati sottostante.The Entity FrameworkEntity Framework is case sensitive, but the underlying data store may not be. Quando nel manifesto vengono definiti e usati gli elementi di EDM, ad esempio identificatori e nomi dei tipi, è necessario che venga usata la distinzione tra maiuscole e minuscole di Entity FrameworkEntity Framework.When EDM artifacts (identifiers and type names, for example) are defined and used in the manifest, they must use the Entity FrameworkEntity Framework case sensitivity. Se nel manifesto del provider vengono visualizzati elementi dell'archivio dati per cui potrebbe essere rilevata la distinzione tra maiuscole e minuscole, è necessario mantenere tale distinzione nel manifesto del provider.If data store elements that may be case sensitive appear in the provider manifest, that casing needs to be maintained in the provider manifest.

Entity FrameworkEntity Framework richiede un manifesto del provider per tutti i provider di dati.The Entity FrameworkEntity Framework requires a provider manifest for all data providers. Se si tenta di utilizzare un provider che non dispone di un provider del manifesto con il Entity FrameworkEntity Framework, si verificherà un errore.If you try to use a provider that does not have a provider manifest with the Entity FrameworkEntity Framework, you will get an error.

Nella tabella seguente vengono descritti i tipi di eccezioni che verrebbero generati da Entity FrameworkEntity Framework quando l'interazione del provider genera eccezioni:The following table describes the kinds of exceptions the Entity FrameworkEntity Framework would throw when exceptions arise through provider interaction:

ProblemaIssue EccezioneException
Il provider non supporta GetProviderManifest in DbProviderServices.The Provider does not support GetProviderManifest in DbProviderServices. ProviderIncompatibleExceptionProviderIncompatibleException
Manifesto del provider mancante: il provider restituisce null se si prova a recuperare il manifesto del provider.Missing provider manifest: the provider returns null when attempting to retrieve the provider manifest. ProviderIncompatibleExceptionProviderIncompatibleException
Manifesto del provider non valido: il provider restituisce un XML non valido se si prova a recuperare il manifesto del provider.Invalid provider manifest: the provider returns invalid XML when attempting to retrieve the provider manifest. ProviderIncompatibleExceptionProviderIncompatibleException

ScenariScenarios

Un provider deve supportare gli scenari seguenti:A provider should support the following scenarios:

Scrittura di un provider con mapping dei tipi simmetricoWriting a Provider with Symmetric Type Mapping

È possibile scrivere un provider per il Entity FrameworkEntity Framework in cui ogni tipo di archivio esegue il mapping a un solo tipo EDM, indipendentemente dalla direzione del mapping.You can write a provider for the Entity FrameworkEntity Framework where each store type maps to a single EDM type, regardless of the mapping direction. Per un tipo di provider che presenta un mapping molto semplice che corrisponde a un tipo EDM, è possibile usare una soluzione simmetrica, in quanto il sistema dei tipi è semplice o corrisponde ai tipi EDM.For a provider type that has very simple mapping that corresponds with an EDM type, you can use a symmetric solution because the type system is simple or matches EDM types.

È possibile usare la semplicità del dominio e produrre un manifesto del provider dichiarativo statico.You can use the simplicity of their domain and produce a static declarative provider manifest.

Scrivere un file XML con due sezioni:You write an XML file that has two sections:

  • Un elenco di tipi di provider espresso in termini di "controparte EDM" di una funzione o di un tipo di archivio.A list of provider types expressed in terms of the "EDM counterpart" of a store type or function. I tipi di archivio presentano tipi EDM della controparte.Store types have counterpart EDM types. Le funzioni di archivio presentano funzioni EDM corrispondenti.Store functions have corresponding EDM functions. Ad esempio, varchar è un tipo SQL Server ma il tipo EDM corrispondente è stringa.For example, varchar is a SQL Server type but the corresponding EDM type is string.

  • Un elenco di funzioni supportate dal provider in cui i tipi di parametri e i tipi restituiti sono espressi in termini EDM.A list of functions supported by the provider where parameter and return types are expressed in EDM terms.

Scrittura di un provider con mapping dei tipi asimmetricoWriting a Provider with Asymmetric Type Mapping

Quando si scrive un provider dell'archivio dati per Entity FrameworkEntity Framework, è possibile che per alcuni tipi il mapping da EDM al tipo di provider sia diverso da quello dal provider al tipo EDM.When writing a data store provider for the Entity FrameworkEntity Framework, the EDM-to-provider type mapping for some types may be different from provider-to-EDM type mapping. Ad esempio, PrimitiveTypeKind.String EDM potrebbe essere mappato a nvarchar (4000) sul provider, mentre nvarchar (4000) viene mappato a PrimitiveTypeKind.String(MaxLength=4000) EDM.For instance, unbounded EDM PrimitiveTypeKind.String may map to nvarchar(4000) on the provider, while nvarchar(4000) maps to the EDM PrimitiveTypeKind.String(MaxLength=4000).

Scrivere un file XML con due sezioni:You write an XML file that has two sections:

  • Un elenco di tipi di provider espresso in termini EDM con la definizione del mapping per entrambe le direzioni: da EDM a provider e da provider a EDM.A list of provider types expressed in EDM terms and define mapping for both direction: EDM-to-provider and provider-to-EDM.

  • Un elenco di funzioni supportate dal provider in cui i tipi di parametri e i tipi restituiti sono espressi in termini EDM.A list of functions supported by the provider where parameter and return types are expressed in EDM terms.

Individuabilità del manifesto del providerProvider Manifest Discoverability

Il manifesto viene usato indirettamente da diversi tipi di componenti nei servizi di entità, ad esempio strumenti o query, ma più direttamente viene usato dai metadati tramite l'uso del caricatore di metadati dell'archivio dati.The manifest is used indirectly by several component types in Entity Services (for example Tools or Query) but more directly leveraged by metadata through the use of the data store metadata loader.

dfb3d02b-7a8c-4d51-ac5a-a73d8aa145e6dfb3d02b-7a8c-4d51-ac5a-a73d8aa145e6

È tuttavia possibile che un provider specificato supporti archivi diversi o versioni diverse dello stesso archivio.However, a given provider may support different stores or different versions of the same store. È necessario pertanto che per ogni archivio dati supportato dal provider sia indicato un manifesto diverso.Therefore, a provider must report a different manifest for each supported data store.

Token del manifesto del providerProvider Manifest Token

Quando viene aperta una connessione a un archivio dati, il provider può richiedere informazioni tramite query per ottenere il manifesto appropriato.When a data store connection is opened, the provider can query for information to return the right manifest. Questa operazione potrebbe non essere possibile negli scenari offline in cui le informazioni di connessione non sono disponibili oppure quando non è possibile eseguire la connessione all'archivio.This may not be possible in offline scenarios where connection information is not available or when it is not possible to connect to the store. Identificare il manifesto tramite l'attributo ProviderManifestToken dell'elemento Schema nel file con estensione ssdl.Identify the manifest by using the ProviderManifestToken attribute of the Schema element in the .ssdl file. Non esiste un formato obbligatorio per questo attributo. Il provider sceglie le informazioni minime necessarie che consentono di identificare un manifesto senza dover aprire una connessione all'archivio.There is no required format for this attribute; the provider chooses the minimum information needed to identify a manifest without opening a connection to the store.

Ad esempio:For example:

<Schema Namespace="Northwind" Provider="System.Data.SqlClient" ProviderManifestToken="2005" xmlns:edm="http://schemas.microsoft.com/ado/2006/04/edm/ssdl" xmlns="http://schemas.microsoft.com/ado/2006/04/edm/ssdl">  

Modello di programmazione del manifesto del providerProvider Manifest Programming Model

I provider derivano da DbXmlEnabledProviderManifest, che consente loro di specificare in modo dichiarativo i propri manifesti.Providers derive from DbXmlEnabledProviderManifest, which allows them to specify their manifests declaratively. Nell'illustrazione seguente viene mostrata la gerarchia di classi di un provider:The following illustration shows the class hierarchy of a provider:

NessunaNone

API di individuabilitàDiscoverability API

Il manifesto del provider viene caricato dal caricatore dei metadati dell'archivio (StoreItemCollection) tramite una connessione all'archivio dati o un token del manifesto del provider.The provider manifest is loaded by the Store Metadata loader (StoreItemCollection), either by using a data store connection or a provider manifest token.

Uso di una connessione all'archivio datiUsing a Data Store Connection

Quando è disponibile la connessione all'archivio dati, chiamare DbProvderServices.GetProviderManifestToken per restituire il token passato al metodo GetProviderManifest, che restituisce DbProviderManifest.When the data store connection is available, call DbProvderServices.GetProviderManifestToken to return the token that is passed to the GetProviderManifest method, which returns DbProviderManifest. Tale metodo funge da delegato per l'implementazione del provider di GetDbProviderManifestToken.This method delegates to the provider's implementation of GetDbProviderManifestToken.

public string GetProviderManifestToken(DbConnection connection);  
public DbProviderManifest GetProviderManifest(string manifestToken);  

Uso di un token del manifesto del providerUsing a Provider Manifest Token

Per lo scenario offline il token viene scelto dalla rappresentazione SSDL.For the offline scenario, the token is picked from SSDL representation. il SSDL consente di specificare un ProviderManifestToken (vedere elemento dello Schema (SSDL) per altre informazioni).The SSDL allows you to specify a ProviderManifestToken (see Schema Element (SSDL) for more information). Se ad esempio non è possibile aprire una connessione, in SSDL è disponibile un token del manifesto del provider che specifica informazioni sul manifesto.For example, if a connection cannot be opened, the SSDL has a provider manifest token that specifies information about the manifest.

public DbProviderManifest GetProviderManifest(string manifestToken);  

Schema del manifesto del providerProvider Manifest Schema

Lo schema di informazioni definito per ogni provider contiene le informazioni statiche che devono essere usate dai metadati:The schema of information defined for each provider contains the static information to be consumed by metadata:

<?xml version="1.0" encoding="utf-8"?>  
<xs:schema elementFormDefault="qualified"  
   xmlns:xs="http://www.w3.org/2001/XMLSchema"  
   targetNamespace="http://schemas.microsoft.com/ado/2006/04/edm/providermanifest"  
   xmlns:pm="http://schemas.microsoft.com/ado/2006/04/edm/providermanifest">  

  <xs:element name="ProviderManifest">  
    <xs:complexType>  
      <xs:sequence>  
        <xs:element name="Types" type="pm:TTypes" minOccurs="1" maxOccurs="1" />  
        <xs:element name="Functions" type="pm:TFunctions" minOccurs="0" maxOccurs="1"/>  
      </xs:sequence>  
      <xs:attribute name="Namespace" type="xs:string" use="required"/>  
    </xs:complexType>  
  </xs:element>  
  <xs:complexType name="TVersion">  
    <xs:attribute name="Major" type="xs:int" use="required" />  
    <xs:attribute name="Minor" type="xs:int" use="required" />  
    <xs:attribute name="Build" type="xs:int" use="required" />  
    <xs:attribute name="Revision" type="xs:int" use="required" />  
  </xs:complexType>  

  <xs:complexType name="TIntegerFacetDescription">  
    <xs:attribute name="Minimum" type="xs:int" use="optional" />  
    <xs:attribute name="Maximum" type="xs:int" use="optional" />  
    <xs:attribute name="DefaultValue" type="xs:int" use="optional" />  
    <xs:attribute name="Constant" type="xs:boolean" default="false" />  
  </xs:complexType>  

  <xs:complexType name="TBooleanFacetDescription">  
    <xs:attribute name="DefaultValue" type="xs:boolean" use="optional" />  
    <xs:attribute name="Constant" type="xs:boolean" default="true" />  
  </xs:complexType>  

  <xs:complexType name="TDateTimeFacetDescription">  
    <xs:attribute name="Constant" type="xs:boolean" default="false" />  
  </xs:complexType>  

  <xs:complexType name="TFacetDescriptions">  
    <xs:choice maxOccurs="unbounded">  
      <xs:element name="Precision" minOccurs="0" maxOccurs="1" type="pm:TIntegerFacetDescription"/>  
      <xs:element name="Scale" minOccurs="0" maxOccurs="1" type="pm:TIntegerFacetDescription"/>  
      <xs:element name="MaxLength" minOccurs="0" maxOccurs="1" type="pm:TIntegerFacetDescription"/>  
      <xs:element name="Unicode" minOccurs="0" maxOccurs="1" type="pm:TBooleanFacetDescription"/>  
      <xs:element name="FixedLength" minOccurs="0" maxOccurs="1" type="pm:TBooleanFacetDescription"/>  
    </xs:choice>  
  </xs:complexType>  

  <xs:complexType name="TType">  
    <xs:sequence>  
      <xs:element name="FacetDescriptions" type="pm:TFacetDescriptions" minOccurs="0" maxOccurs="1"/>  
    </xs:sequence>  
    <xs:attribute name="Name" type="xs:string" use="required"/>  
    <xs:attribute name="PrimitiveTypeKind" type="pm:TPrimitiveTypeKind" use="required" />  
  </xs:complexType>  

  <xs:complexType name="TTypes">  
    <xs:sequence>  
      <xs:element name="Type" type="pm:TType" minOccurs="0" maxOccurs="unbounded"/>  
    </xs:sequence>  
  </xs:complexType>  

  <xs:attributeGroup name="TFacetAttribute">  
    <xs:attribute name="Precision" type="xs:int" use="optional"/>  
    <xs:attribute name="Scale" type="xs:int" use="optional"/>  
    <xs:attribute name="MaxLength" type="xs:int" use="optional"/>  
    <xs:attribute name="Unicode" type="xs:boolean" use="optional"/>  
    <xs:attribute name="FixedLength" type="xs:boolean" use="optional"/>  
  </xs:attributeGroup>  

  <xs:complexType name="TFunctionParameter">  
    <xs:attribute name="Name" type="xs:string" use="required" />  
    <xs:attribute name="Type" type="xs:string" use="required" />  
    <xs:attributeGroup ref="pm:TFacetAttribute" />  
    <xs:attribute name="Mode" type="pm:TParameterDirection" use="required" />  
  </xs:complexType>  

  <xs:complexType name="TReturnType">  
    <xs:attribute name="Type" type="xs:string" use="required" />  
    <xs:attributeGroup ref="pm:TFacetAttribute" />  
  </xs:complexType>  

  <xs:complexType name="TFunction">  
    <xs:choice minOccurs="0" maxOccurs ="unbounded">  
      <xs:element name ="ReturnType" type="pm:TReturnType" minOccurs="0" maxOccurs="1" />  
      <xs:element name="Parameter" type="pm:TFunctionParameter" minOccurs="0" maxOccurs="unbounded"/>  
    </xs:choice>  
    <xs:attribute name="Name" type="xs:string" use="required" />  
    <xs:attribute name="Aggregate" type="xs:boolean" use="optional" />  
    <xs:attribute name="BuiltIn" type="xs:boolean" use="optional" />  
    <xs:attribute name="StoreFunctionName" type="xs:string" use="optional" />  
    <xs:attribute name="NiladicFunction" type="xs:boolean" use="optional" />  
    <xs:attribute name="ParameterTypeSemantics" type="pm:TParameterTypeSemantics" use="optional" default="AllowImplicitConversion" />  
  </xs:complexType>  

  <xs:complexType name="TFunctions">  
    <xs:sequence>  
      <xs:element name="Function" type="pm:TFunction" minOccurs="0" maxOccurs="unbounded"/>  
    </xs:sequence>  
  </xs:complexType>  

  <xs:simpleType name="TPrimitiveTypeKind">  
    <xs:restriction base="xs:string">  
      <xs:enumeration value="Binary"/>  
      <xs:enumeration value="Boolean"/>  
      <xs:enumeration value="Byte"/>  
      <xs:enumeration value="Decimal"/>  
      <xs:enumeration value="DateTime"/>  
      <xs:enumeration value="Time"/>  
      <xs:enumeration value="DateTimeOffset"/>          
      <xs:enumeration value="Double"/>  
      <xs:enumeration value="Guid"/>  
      <xs:enumeration value="Single"/>  
      <xs:enumeration value="SByte"/>  
      <xs:enumeration value="Int16"/>  
      <xs:enumeration value="Int32"/>  
      <xs:enumeration value="Int64"/>  
      <xs:enumeration value="String"/>  
    </xs:restriction>  
  </xs:simpleType>  

  <xs:simpleType name="TParameterDirection">  
    <xs:restriction base="xs:string">  
      <xs:enumeration value="In"/>  
      <xs:enumeration value="Out"/>  
      <xs:enumeration value="InOut"/>  
    </xs:restriction>  
  </xs:simpleType>  

  <xs:simpleType name="TParameterTypeSemantics">  
    <xs:restriction base="xs:string">  
      <xs:enumeration value="ExactMatchOnly" />  
      <xs:enumeration value="AllowImplicitPromotion" />  
      <xs:enumeration value="AllowImplicitConversion" />  
    </xs:restriction>  
  </xs:simpleType>  
</xs:schema>  

Nodo TypesTypes Node

Il nodo Types nel manifesto del provider contiene informazioni sugli oggetti Types supportati a livello nativo dall'archivio dati o tramite il provider.The Types node in the provider manifest contains information about the Types that are supported natively by the data store or through the provider.

Nodo TypeType Node

Ogni nodo Type definisce un tipo di provider in termini di EDM.Each Type node defines a provider type in terms of EDM. Il nodo Type descrive il nome del tipo di provider, informazioni correlate al tipo di modello al quale viene mappato, nonché facet per descrivere il mapping dei tipi specifico.The Type node describes the name of the provider type, and information related to the model type it maps to and facets to describe that type mapping.

Per esprimere queste informazioni sui tipi nel manifesto del provider, è necessario che ogni dichiarazione TypeInformation definisca diverse descrizioni di facet per ogni oggetto Type:In order to express this type information in the provider manifest, each TypeInformation declaration must define several facet descriptions for each Type:

Nome attributoAttribute Name Tipo di datiData Type ObbligatorioRequired Valore predefinitoDefault Value DescrizioneDescription
NomeName StringString Yes n/dn/a Nome del tipo di dati specifico del providerProvider-specific data type name
PrimitiveTypeKindPrimitiveTypeKind PrimitiveTypeKindPrimitiveTypeKind Yes n/dn/a Nome del tipo EDMEDM type name
Nodo FunctionFunction Node

Ogni oggetto Function definisce una sola funzione disponibile tramite il provider.Each Function defines a single function available through the provider.

Nome attributoAttribute Name Tipo di datiData Type ObbligatorioRequired Valore predefinitoDefault Value DescrizioneDescription
NomeName StringString Yes n/dn/a Nome/identificatore della funzioneIdentifier/name of the function
ReturnTypeReturnType StringString NoNo VoidVoid Il tipo restituito EDM della funzioneThe EDM return type of the function
AggregateAggregate BooleanBoolean NoNo FalseFalse Restituisce True se si tratta di una funzione di aggregazioneTrue if the function is an aggregate function
BuiltInBuiltIn BooleanBoolean NoNo TrueTrue Restituisce True se la funzione è inclusa nell'archivio datiTrue if the function is built into the data store
StoreFunctionNameStoreFunctionName StringString NoNo <Nome ><Name> Nome della funzione nell'archivio dati.Function Name in the data store. Consente di eseguire un determinato tipo di reindirizzamento dei nomi delle funzioni.Allows for a level of redirection of function names.
NiladicFunctionNiladicFunction BooleanBoolean NoNo FalseFalse Restituisce True se la funzione non richiede parametri e viene chiamata senza parametriTrue if the function does not require parameters and is called without any parameters
ParameterTypeParameterType

SemanticsSemantics
ParameterSemanticsParameterSemantics NoNo AllowImplicitAllowImplicit

ConversionConversion
Scelta della modalità con cui la pipeline della query gestisce la sostituzione del tipo di parametro:Choice of how the query pipeline should deal with parameter type substitution:

-ExactMatchOnly- ExactMatchOnly
-AllowImplicitPromotion- AllowImplicitPromotion
-AllowImplicitConversion- AllowImplicitConversion

Nodo parametriParameters Node

Ogni funzione presenta una raccolta di uno o più nodi Parameter.Each function has a collection of one or more Parameter nodes.

Nome attributoAttribute Name Tipo di datiData Type ObbligatorioRequired Valore predefinitoDefault Value DescrizioneDescription
NomeName StringString Yes n/dn/a Nome/identificatore del parametro.Identifier/name of the parameter.
TipoType StringString Yes n/dn/a Tipo EDM del parametro.The EDM type of the parameter.
ModalitàMode ParametroParameter

DirezioneDirection
Yes n/dn/a Direzione del parametro:Direction of parameter:

- in- in
-out- out
-inout- inout
Attributo namespaceNamespace Attribute

Ogni provider dell'archivio dati deve definire uno spazio dei nomi o un gruppo di spazi dei nomi per le informazioni definite nel manifesto.Each data store provider must define a namespace or group of namespaces for information defined in the manifest. Tale spazio dei nomi può essere usato nelle query Entity SQL per risolvere nomi di funzioni e tipi.This namespace can be used in Entity SQL queries to resolve names of functions and types. Ad esempio: SqlServer.For instance: SqlServer. Lo spazio dei nomi deve essere diverso dallo spazio dei nomi canonico, ovvero EDM, definito dai servizi di entità per funzioni standard che devono essere supportate dalle query Entity SQL.That namespace must be different from the canonical namespace, EDM, defined by Entity Services for standard functions to be supported by Entity SQL queries.

Vedere ancheSee Also

Scrittura di un provider di dati Entity FrameworkWriting an Entity Framework Data Provider