Conception de contrats de serviceDesigning Service Contracts

Cette rubrique explique ce que sont les contrats de service, comment ils sont définis, quelles opérations sont disponibles (et les implications des échanges de messages sous-jacents), quels types de données sont utilisés et d'autres aspects qui vous aident à concevoir des opérations qui répondent aux spécifications de votre scénario.This topic describes what service contracts are, how they are defined, what operations are available (and the implications for the underlying message exchanges), what data types are used, and other issues that help you design operations that satisfy the requirements of your scenario.

Création d'un contrat de serviceCreating a Service Contract

Les services exposent un certain nombre d'opérations.Services expose a number of operations. Dans les applications Windows Communication Foundation (WCF), définissez les opérations en créant une méthode et en la marquant OperationContractAttribute avec l’attribut.In Windows Communication Foundation (WCF) applications, define the operations by creating a method and marking it with the OperationContractAttribute attribute. Ensuite, pour créer un contrat de service, groupez vos opérations en les déclarant dans une interface marquée avec l'attribut ServiceContractAttribute ou en les définissant dans une classe marquée avec le même attribut.Then, to create a service contract, group together your operations, either by declaring them within an interface marked with the ServiceContractAttribute attribute, or by defining them in a class marked with the same attribute. (Pour obtenir un exemple de base , consultez Procédure: Définir un contratde service.)(For a basic example, see How to: Define a Service Contract.)

Toutes les méthodes qui n’ont pas OperationContractAttribute d’attribut ne sont pas des opérations de service et ne sont pas exposées par les services WCF.Any methods that do not have a OperationContractAttribute attribute are not service operations and are not exposed by WCF services.

Cette rubrique décrit les points de décision suivants lors de la conception d'un contrat de service :This topic describes the following decision points when designing a service contract:

  • S'il faut utiliser des classes ou des interfaces.Whether to use classes or interfaces.

  • Comment spécifier les types de données que vous souhaitez échanger.How to specify the data types you want to exchange.

  • Les types de modèles d’échange que vous pouvez utiliser.The types of exchange patterns you can use.

  • Si vous pouvez inclure des exigences de sécurité explicites dans le contrat.Whether you can make explicit security requirements part of the contract.

  • Les restrictions d'entrée et de sortie d'opération.The restrictions for operation inputs and outputs.

Classes ou interfacesClasses or Interfaces

Les classes et les interfaces représentent un regroupement de fonctionnalités et, par conséquent, peuvent être utilisées pour définir un contrat de service WCF.Both classes and interfaces represent a grouping of functionality and, therefore, both can be used to define a WCF service contract. Toutefois, il est recommandé d'utiliser des interfaces car elles modèlent directement des contrats de service.However, it is recommended that you use interfaces because they directly model service contracts. Sans implémentation, les interfaces ne font que définir un groupement de méthodes avec certaines signatures.Without an implementation, interfaces do no more than define a grouping of methods with certain signatures. Implémentez une interface de contrat de service et vous avez implémenté un service WCF.Implement a service contract interface and you have implemented a WCF service.

Tous les avantages liées aux interfaces managées s'appliquent aux interfaces de contrat de service :All the benefits of managed interfaces apply to service contract interfaces:

  • Les interfaces de contrat de service peuvent étendre une quantité quelconque d'autres interfaces de contrat de service.Service contract interfaces can extend any number of other service contract interfaces.

  • Une classe unique peut implémenter une quantité quelconque de contrats de service en implémentant ces interfaces de contrat de service.A single class can implement any number of service contracts by implementing those service contract interfaces.

  • Vous pouvez modifier l'implémentation d'un contrat de service en modifiant l'implémentation d'interface, tandis que le contrat de service reste le même.You can modify the implementation of a service contract by changing the interface implementation, while the service contract remains the same.

  • Vous pouvez affecter une version à votre service en implémentant l'ancienne interface et la nouvelle.You can version your service by implementing the old interface and the new one. Les clients anciens se connectent à la version d'origine, tandis que les nouveaux clients peuvent se connecter à la version plus récente.Old clients connect to the original version, while newer clients can connect to the newer version.

Notes

Lorsque vous héritez d'autres interfaces de contrat de service, vous ne pouvez pas substituer de propriétés d'opération, telles que le nom ou l'espace de noms.When inheriting from other service contract interfaces, you cannot override operation properties, such as the name or namespace. Si vous essayez, vous créez une nouvelle opération dans le contrat de service actuel.If you attempt to do so, you create a new operation in the current service contract.

Pour obtenir un exemple d’utilisation d’une interface pour créer un contrat de service, consultez Procédure: Créez un service avec une interfacede contrat.For an example of using an interface to create a service contract, see How to: Create a Service with a Contract Interface.

Toutefois, vous pouvez utiliser une classe pour définir un contrat de service et implémenter ce contrat en même temps.You can, however, use a class to define a service contract and implement that contract at the same time. Les avantages liés à la création de vos services en appliquant ServiceContractAttribute et OperationContractAttribute directement à la classe et aux méthodes sur la classe, respectivement, sont la vitesse et la simplicité.The advantage of creating your services by applying ServiceContractAttribute and OperationContractAttribute directly to the class and the methods on the class, respectively, is speed and simplicity. Les inconvénients sont que les classes managées ne prennent pas en charge l'héritage multiple ; en conséquence, elles peuvent implémenter un seul contrat de service à la fois.The disadvantages are that managed classes do not support multiple inheritance, and as a result they can only implement one service contract at a time. De plus, toute modification de la classe ou des signatures de méthode modifie le contrat public pour ce service, ce qui peut empêcher les clients non modifiés d'utiliser votre service.In addition, any modification to the class or method signatures modifies the public contract for that service, which can prevent unmodified clients from using your service. Pour plus d’informations, consultez implémentation de contrats de service.For more information, see Implementing Service Contracts.

Pour obtenir un exemple qui utilise une classe pour créer un contrat de service et l’implémente en même temps, consultez Procédure: Créez un service avec une classede contrat.For an example that uses a class to create a service contract and implements it at the same time, see How to: Create a Service with a Contract Class.

À ce stade, vous devez comprendre la différence entre le fait de définir votre contrat de service en utilisant une interface et en utilisant une classe.At this point, you should understand the difference between defining your service contract by using an interface and by using a class. L'étape suivante consiste à déterminer les données qui peuvent être passées entre un service et ses clients.The next step is deciding what data can be passed back and forth between a service and its clients.

Paramètres et valeurs de retourParameters and Return Values

Chaque opération a une valeur de retour et un paramètre, même s'il s'agit de void.Each operation has a return value and a parameter, even if these are void. Toutefois, contrairement à une méthode locale, dans laquelle vous pouvez passer des références à des objets d'un objet à un autre, les opérations de service ne passent pas de références à des objets.However, unlike a local method, in which you can pass references to objects from one object to another, service operations do not pass references to objects. Au lieu de cela, elles passent des copies des objets.Instead, they pass copies of the objects.

Cette différence est significative car chaque type utilisé dans un paramètre ou une valeur de retour doit être sérialisable ; autrement dit, il doit être possible de convertir un objet de ce type en un flux d'octets et d'un flux d'octets en un objet.This is significant because each type used in a parameter or return value must be serializable; that is, it must be possible to convert an object of that type into a stream of bytes and from a stream of bytes into an object.

Les types primitifs sont sérialisables par défaut, comme le sont de nombreux types dans le .NET Framework.Primitive types are serializable by default, as are many types in the .NET Framework.

Notes

La valeur des noms de paramètres dans la signature de l'opération fait partie du contrat et respecte la casse.The value of the parameter names in the operation signature are part of the contract and are case sensitive. Si vous souhaitez utiliser le même nom de paramètre localement mais modifier le nom dans les métadonnées publiées, consultez System.ServiceModel.MessageParameterAttribute.If you want to use the same parameter name locally but modify the name in the published metadata, see the System.ServiceModel.MessageParameterAttribute.

Contrats de donnéesData Contracts

Les applications orientées service telles que les applications Windows Communication Foundation (WCF) sont conçues pour interagir avec le plus grand nombre possible d’applications clientes sur les plateformes Microsoft et non-Microsoft.Service-oriented applications like Windows Communication Foundation (WCF) applications are designed to interoperate with the widest possible number of client applications on both Microsoft and non-Microsoft platforms. Pour l'interopérabilité la plus large possible, il est recommandé de marquer vos types avec les attributs DataContractAttribute et DataMemberAttribute afin de créer un contrat de données, qui est la partie du contrat de service qui décrit les données échangées par vos opérations de service.For the widest possible interoperability, it is recommended that you mark your types with the DataContractAttribute and DataMemberAttribute attributes to create a data contract, which is the portion of the service contract that describes the data that your service operations exchange.

Les contrats de données sont des contrats de style opt-in: Aucun type ou membre de données n’est sérialisé, sauf si vous appliquez explicitement l’attribut de contrat de données.Data contracts are opt-in style contracts: No type or data member is serialized unless you explicitly apply the data contract attribute. Les contrats de données ne sont pas liés à l’étendue d’accès du code managé: Les membres de données privés peuvent être sérialisés et envoyés ailleurs pour être accessibles publiquement.Data contracts are unrelated to the access scope of the managed code: Private data members can be serialized and sent elsewhere to be accessed publicly. (Pour obtenir un exemple de base d’un contrat de données, consultez Procédure: Créer un contrat de données de base pour une classeou une structure.) WCF gère la définition des messages SOAP sous-jacents qui activent les fonctionnalités de l’opération ainsi que la sérialisation de vos types de données dans et hors du corps des messages.(For a basic example of a data contract, see How to: Create a Basic Data Contract for a Class or Structure.) WCF handles the definition of the underlying SOAP messages that enable the operation's functionality as well as the serialization of your data types into and out of the body of the messages. Tant que vos types de données sont sérialisables, vous n'avez pas à vous soucier de l'infrastructure d'échange de messages sous-jacente lors de la conception de vos opérations.As long as your data types are serializable, you do not need to think about the underlying message exchange infrastructure when designing your operations.

Bien que l’application WCF classique utilise DataContractAttribute les DataMemberAttribute attributs et pour créer des contrats de données pour les opérations, vous pouvez utiliser d’autres mécanismes de sérialisation.Although the typical WCF application uses the DataContractAttribute and DataMemberAttribute attributes to create data contracts for operations, you can use other serialization mechanisms. Les mécanismes ISerializable, SerializableAttribute et IXmlSerializable standard gèrent tous la sérialisation de vos types de données dans les messages SOAP sous-jacents qui les transportent d'une application à une autre.The standard ISerializable, SerializableAttribute and IXmlSerializable mechanisms all work to handle the serialization of your data types into the underlying SOAP messages that carry them from one application to another. Vous pouvez employer davantage de stratégies de sérialisation si vos types de données requièrent une prise en charge spéciale.You can employ more serialization strategies if your data types require special support. Pour plus d’informations sur les choix de sérialisation des types de données dans les applications WCF, consultez spécification de transfert de données dans les contrats de service.For more information about the choices for serialization of data types in WCF applications, see Specifying Data Transfer in Service Contracts.

Mappage des paramètres et des valeurs de retour aux échanges de messagesMapping Parameters and Return Values to Message Exchanges

Les opérations de service sont prises en charge par un échange sous-jacent de messages SOAP qui transfèrent les données d'application, en plus des données requises par l'application pour prendre en charge certaines fonctionnalités standard liées à la sécurité, aux transaction et aux sessions.Service operations are supported by an underlying exchange of SOAP messages that transfer application data back and forth, in addition to the data required by the application to support certain standard security, transaction, and session-related features. Comme c’est le cas, la signature d’une opération de service dicte un certain modèle d’échange de messages sous-jacent (MEP) qui peut prendre en charge le transfert de données et les fonctionnalités requises par une opération.Because this is the case, the signature of a service operation dictates a certain underlying message exchange pattern (MEP) that can support the data transfer and the features an operation requires. Vous pouvez spécifier trois modèles dans le modèle de programmation WCF: modèles de message demande/réponse, unidirectionnel et duplex.You can specify three patterns in the WCF programming model: request/reply, one-way, and duplex message patterns.

Demande/réponseRequest/Reply

Un modèle de demande/réponse est un modèle dans lequel un expéditeur de demande (une application cliente) reçoit une réponse avec laquelle la demande est mise en corrélation.A request/reply pattern is one in which a request sender (a client application) receives a reply with which the request is correlated. Il s'agit du modèle d'échange de messages par défaut, car il prend en charge une opération dans laquelle un ou plusieurs paramètres sont passés à l'opération et une valeur de retour est repassée à l'appelant.This is the default MEP because it supports an operation in which one or more parameters are passed to the operation and a return value is passed back to the caller. Par exemple, l'extrait de code C# suivant illustre une opération de service simple qui prend une chaîne et retourne une chaîne.For example, the following C# code example shows a basic service operation that takes one string and returns a string.

[OperationContractAttribute]  
string Hello(string greeting);  

L'exemple suivant illustre le code Visual Basic équivalent.The following is the equivalent Visual Basic code.

<OperationContractAttribute()>  
Function Hello (ByVal greeting As String) As String  

Cette signature d'opération dicte la forme de l'échange de messages sous-jacent.This operation signature dictates the form of underlying message exchange. Si aucune corrélation n’existait, WCF ne peut pas déterminer pour quelle opération la valeur de retour est prévue.If no correlation existed, WCF cannot determine for which operation the return value is intended.

Notez que, sauf si vous spécifiez un modèle de message sous-jacent différent void ,Nothing même les opérations de service qui retournent (dans Visual Basic) sont des échanges de messages de demande/réponse.Note that unless you specify a different underlying message pattern, even service operations that return void (Nothing in Visual Basic) are request/reply message exchanges. Le résultat de votre opération est qu'à moins qu'un client n'appelle l'opération de façon asynchrone, le client cesse le traitement jusqu'à ce que le message de retour soit reçu, bien que ce message soit vide dans le cas normal.The result for your operation is that unless a client invokes the operation asynchronously, the client stops processing until the return message is received, even though that message is empty in the normal case. L'exemple de code C# suivant illustre une opération qui n'est retournée que lorsque le client a reçu un message vide dans la réponse.The following C# code example shows an operation that does not return until the client has received an empty message in response.

[OperationContractAttribute]  
void Hello(string greeting);  

L'exemple suivant illustre le code Visual Basic équivalent.The following is the equivalent Visual Basic code.

<OperationContractAttribute()>  
Sub Hello (ByVal greeting As String)  

L'exemple précédent peut ralentir les performances et la réactivité du client si l'exécution de l'opération prend beaucoup de temps, mais les opérations demande/réponse présentent des avantages même lorsqu'elles retournent void.The preceding example can slow client performance and responsiveness if the operation takes a long time to perform, but there are advantages to request/reply operations even when they return void. Le plus évident est que des erreurs SOAP peuvent être retournées dans le message de réponse, ce qui indique qu'une certaine condition d'erreur liée au service s'est produite, lors de la communication ou lors du traitement.The most obvious one is that SOAP faults can be returned in the response message, which indicates that some service-related error condition has occurred, whether in communication or processing. Les erreurs SOAP spécifiées dans un contrat de service sont passées à l'application cliente en tant qu'objets FaultException<TDetail>, où le paramètre de type est le type spécifié dans le contrat de service.SOAP faults that are specified in a service contract are passed to the client application as a FaultException<TDetail> object, where the type parameter is the type specified in the service contract. Cela facilite la notification des clients concernant les conditions d’erreur dans les services WCF.This makes notifying clients about error conditions in WCF services easy. Pour plus d’informations sur les exceptions, les erreurs SOAP et la gestion des erreurs, consultez spécification et gestion des erreurs dans les contrats et les services.For more information about exceptions, SOAP faults, and error handling, see Specifying and Handling Faults in Contracts and Services. Pour voir un exemple de service de demande/réponse et de client, consultez Procédure: Créez un contratde demande-réponse.To see an example of a request/reply service and client, see How to: Create a Request-Reply Contract. Pour plus d’informations sur les problèmes liés au modèle demande-réponse, consultez services demande-réponse.For more information about issues with the request-reply pattern, see Request-Reply Services.

UnidirectionnelOne-way

Si le client d’une application de service WCF ne doit pas attendre que l’opération se termine et qu’il ne traite pas les erreurs SOAP, l’opération peut spécifier un modèle de message unidirectionnel.If the client of a WCF service application should not wait for the operation to complete and does not process SOAP faults, the operation can specify a one-way message pattern. Une opération unidirectionnelle est une opération dans laquelle un client appelle une opération et poursuit le traitement après que WCF a écrit le message sur le réseau.A one-way operation is one in which a client invokes an operation and continues processing after WCF writes the message to the network. En général, cela signifie qu’à moins que le volume des données envoyées dans le message sortant ne soit extrêmement important, le client continue de s’exécuter presque immédiatement (à moins qu’une erreur ne soit survenue pendant l’envoi des données).Typically this means that unless the data being sent in the outbound message is extremely large the client continues running almost immediately (unless there is an error sending the data). Ce type de modèle d'échange de messages prend en charge un comportement semblable aux événements d'un client à une application de service.This type of message exchange pattern supports event-like behavior from a client to a service application.

Un échange de messages dans lequel un message est envoyé et aucun message n'est reçu ne peut pas prendre en charge une opération de service qui spécifie une valeur de retour autre que void ; dans ce cas, une exception InvalidOperationException est levée.A message exchange in which one message is sent and none are received cannot support a service operation that specifies a return value other than void; in this case an InvalidOperationException exception is thrown.

L'absence de message de retour signifie également qu'il ne peut y avoir aucune erreur SOAP retournée pour signaler une erreur lors du traitement ou de la communication.No return message also means that there can be no SOAP fault returned to indicate any errors in processing or communication. (La communication d’informations sur les erreurs lorsque les opérations sont unidirectionnelles requiert un modèle d’échange de messages duplex.)(Communicating error information when operations are one-way operations requires a duplex message exchange pattern.)

Pour spécifier un échange de messages unidirectionnel pour une opération qui retourne void, affectez à la propriété IsOneWay la valeur true, comme dans l'exemple de code C# suivant.To specify a one-way message exchange for an operation that returns void, set the IsOneWay property to true, as in the following C# code example.

[OperationContractAttribute(IsOneWay=true)]  
void Hello(string greeting);  

L'exemple suivant illustre le code Visual Basic équivalent.The following is the equivalent Visual Basic code.

<OperationContractAttribute(IsOneWay := True)>  
Sub Hello (ByVal greeting As String)  

Cette méthode est identique à l'exemple de demande/réponse précédent, mais le fait d'affecter à la propriété IsOneWay la valeur true signifie que bien que la méthode soit identique, l'opération de service n'envoie pas de message de retour et les clients retournent immédiatement une fois le message sortant transmis à la couche du canal.This method is identical to the preceding request/reply example, but setting the IsOneWay property to true means that although the method is identical, the service operation does not send a return message and clients return immediately once the outbound message has been handed to the channel layer. Pour voir un exemple, consultez Comment : Créez un contratunidirectionnel.For an example, see How to: Create a One-Way Contract. Pour plus d’informations sur le modèle unidirectionnel, consultez services à sensunique.For more information about the one-way pattern, see One-Way Services.

DuplexDuplex

Un modèle duplex se caractérise par la capacité qu’ont le service et le client à s’envoyer des messages l’un à l’autre, que le mode de messagerie utilisé soit unidirectionnel ou demande/réponse.A duplex pattern is characterized by the ability of both the service and the client to send messages to each other independently whether using one-way or request/reply messaging. Cette forme de communication bidirectionnelle est utile pour les services qui doivent communiquer directement avec le client ou pour fournir une expérience asynchrone à l'un des côtés d'un échange de messages, y compris un comportement semblables aux événements.This form of two-way communication is useful for services that must communicate directly to the client or for providing an asynchronous experience to either side of a message exchange, including event-like behavior.

Le modèle duplex est légèrement plus complexe que le modèle demande/réponse ou unidirectionnel à cause du mécanisme supplémentaire nécessaire pour la communication avec le client.The duplex pattern is slightly more complex than the request/reply or one-way patterns because of the additional mechanism for communicating with the client.

Pour concevoir un contrat duplex, vous devez également concevoir un contrat de rappel et assigner le type de ce contrat de rappel à la propriété CallbackContract de l'attribut ServiceContractAttribute qui marque votre contrat de service.To design a duplex contract, you must also design a callback contract and assign the type of that callback contract to the CallbackContract property of the ServiceContractAttribute attribute that marks your service contract.

Pour implémenter un modèle duplex, vous devez créer une deuxième interface qui contient les déclarations de méthode appelées sur le client.To implement a duplex pattern, you must create a second interface that contains the method declarations that are called on the client.

Pour obtenir un exemple de création d’un service et d’un client qui accède à ce service , consultez Procédure: Créer un contrat duplex et Comment: Accédez aux services avec un contratduplex.For an example of creating a service, and a client that accesses that service, see How to: Create a Duplex Contract and How to: Access Services with a Duplex Contract. Pour obtenir un exemple fonctionnel, consultez duplex.For a working sample, see Duplex. Pour plus d’informations sur les problèmes liés à l’utilisation de contrats duplex, consultez services duplex.For more information about issues using duplex contracts, see Duplex Services.

Attention

Lorsqu'un service reçoit un message duplex, il consultez l'élément ReplyTo dans ce message entrant afin de déterminer où envoyer la réponse.When a service receives a duplex message, it looks at the ReplyTo element in that incoming message to determine where to send the reply. Si le canal utilisé pour recevoir le message n'est pas sécurisé, un client non fiable peut envoyer un message malveillant avec l'élément ReplyTo d'un ordinateur cible, ce qui peut provoquer un déni de service de cet ordinateur cible.If the channel that is used to receive the message is not secured, then an untrusted client could send a malicious message with a target machine's ReplyTo, leading to a denial of service (DOS) of that target machine.

Paramètres Out et RefOut and Ref Parameters

Dans la plupart des cas, vous in pouvez utiliserByVal des paramètres (dans out Visual Basic ref ) etByRef des paramètres (dans Visual Basic).In most cases, you can use in parameters (ByVal in Visual Basic) and out and ref parameters (ByRef in Visual Basic). Les paramètres out et ref indiquant tous deux que les données sont retournées à partir d'une opération, une signature d'opération telle que la suivante spécifie qu'une opération demande/réponse est requise bien que la signature d'opération retourne void.Because both out and ref parameters indicate that data is returned from an operation, an operation signature such as the following specifies that a request/reply operation is required even though the operation signature returns void.

[ServiceContractAttribute]  
public interface IMyContract  
{  
  [OperationContractAttribute]  
  public void PopulateData(ref CustomDataType data);  
}  

L'exemple suivant illustre le code Visual Basic équivalent.The following is the equivalent Visual Basic code.

<ServiceContractAttribute()> _  
Public Interface IMyContract  
  <OperationContractAttribute()> _  
  Public Sub PopulateData(ByRef data As CustomDataType)  
End Interface  

Les seules exceptions sont les cas dans lesquels votre signature a une structure particulière.The only exceptions are those cases in which your signature has a particular structure. Par exemple, vous pouvez utiliser la liaison NetMsmqBinding pour communiquer avec les clients uniquement si la méthode utilisée pour déclarer une opération retourne void ; il ne peut y avoir aucune valeur de sortie, qu’il s’agisse d’une valeur de retour ou d’un paramètre ref ou out.For example, you can use the NetMsmqBinding binding to communicate with clients only if the method used to declare an operation returns void; there can be no output value, whether it is a return value, ref, or out parameter.

De plus, l'utilisation de paramètres out ou ref requiert que l'opération contienne un message de réponse sous-jacent afin de retourner l'objet modifié.In addition, using out or ref parameters requires that the operation have an underlying response message to carry back the modified object. Si votre opération est unidirectionnelle, une exception InvalidOperationException est levée au moment de l'exécution.If your operation is a one-way operation, an InvalidOperationException exception is thrown at runtime.

Spécifier le niveau de protection des messages sur le contratSpecify Message Protection Level on the Contract

Lorsque vous concevez votre contrat, vous devez également décider du niveau de protection des messages des services qui implémentent votre contrat.When designing your contract, you must also decide the message protection level of services that implement your contract. Cela est nécessaire uniquement si la sécurité de message est appliquée à la liaison dans le point de terminaison du contrat.This is necessary only if message security is applied to the binding in the contract's endpoint. Si la sécurité est désactivée pour la liaison (autrement dit, si la liaison fournie par le système affecte au System.ServiceModel.SecurityMode la valeur SecurityMode.None), vous n’avez pas à choisir le niveau de protection des messages pour le contrat.If the binding has security turned off (that is, if the system-provided binding sets the System.ServiceModel.SecurityMode to the value SecurityMode.None) then you do not have to decide on the message protection level for the contract. Dans la plupart des cas, les liaisons fournies par le système avec la sécurité au niveau du message appliquée fournissent un niveau de protection suffisant et il n’est pas nécessaire de considérer le niveau de protection sur la base de chaque opération ou de chaque message.In most cases, system-provided bindings with message-level security applied provide a sufficient protection level and you do not have to consider the protection level for each operation or for each message.

Le niveau de protection est une valeur qui spécifie si les messages (ou parties de messages) qui prennent en charge un service sont signés, signés et chiffrés, ou envoyés sans signature ou chiffrement.The protection level is a value that specifies whether the messages (or message parts) that support a service are signed, signed and encrypted, or sent without signatures or encryption. Le niveau de protection peut être défini sur différentes étendues: Au niveau du service, pour une opération particulière, pour un message dans cette opération ou une partie de message.The protection level can be set at various scopes: At the service level, for a particular operation, for a message within that operation, or a message part. Les valeurs définies à une portée deviennent la valeur par défaut pour les plus petites portées, sauf substitution explicite.Values set at one scope become the default value for smaller scopes unless explicitly overridden. Si une configuration de liaison est incapable de fournir le niveau de protection minimum requis pour le contrat, une exception est levée.If a binding configuration cannot provide the required minimum protection level for the contract, an exception is thrown. Et lorsque aucune valeur de niveau de protection n’est définie explicitement sur le contrat, la configuration de liaison contrôle le niveau de protection pour tous les messages si la liaison a la sécurité de message.And when no protection level values are explicitly set on the contract, the binding configuration controls the protection level for all messages if the binding has message security. Il s’agit du comportement par défaut.This is the default behavior.

Important

L'affectation explicite à plusieurs portées d'un contrat un niveau de protection inférieur au niveau complet de ProtectionLevel.EncryptAndSign est en général une décision qui implique un compromis entre le degré de sécurité et les performances.Deciding whether to explicitly set various scopes of a contract to less than the full protection level of ProtectionLevel.EncryptAndSign is generally a decision that trades some degree of security for increased performance. Dans ces cas-là, vos décisions doivent dépendre de vos opérations et de la valeur des données qu'elles échangent.In these cases, your decisions must revolve around your operations and the value of the data they exchange. Pour plus d’informations, consultez Sécurisation des services.For more information, see Securing Services.

Par exemple, l'exemple de code suivant ne définit pas la propriété ProtectionLevel ou ProtectionLevel sur le contrat.For example, the following code example does not set either the ProtectionLevel or the ProtectionLevel property on the contract.

[ServiceContract]  
public interface ISampleService  
{  
  [OperationContractAttribute]  
  public string GetString();  
  
  [OperationContractAttribute]  
  public int GetInt();    
}  

L'exemple suivant illustre le code Visual Basic équivalent.The following is the equivalent Visual Basic code.

<ServiceContractAttribute()> _  
Public Interface ISampleService  
  
  <OperationContractAttribute()> _  
  Public Function GetString()As String  
  
  <OperationContractAttribute()> _  
  Public Function GetData() As Integer  
  
End Interface  

Lors de l'interaction avec une implémentation ISampleService dans un point de terminaison avec un WSHttpBinding par défaut (le System.ServiceModel.SecurityModepar défaut, qui est Message), tous les messages sont chiffrés et signés puisqu'il s'agit du niveau de protection par défaut.When interacting with an ISampleService implementation in an endpoint with a default WSHttpBinding (the default System.ServiceModel.SecurityMode, which is Message), all messages are encrypted and signed because this is the default protection level. Toutefois, lorsqu’un service ISampleService est utilisé avec un BasicHttpBinding par défaut (le SecurityModepar défaut, qui est None), tous les messages sont envoyés comme du texte puisqu’il n’y a aucune sécurité pour cette liaison, et le niveau de protection est donc ignoré (autrement dit, les messages ne sont ni chiffrés ni signés).However, when an ISampleService service is used with a default BasicHttpBinding (the default SecurityMode, which is None), all messages are sent as text because there is no security for this binding and so the protection level is ignored (that is, the messages are neither encrypted nor signed). Si le SecurityMode était changé en Message, ces messages seraient chiffrés et signés (car ce serait maintenant le niveau de protection par défaut de la liaison).If the SecurityMode was changed to Message, then these messages would be encrypted and signed (because that would now be the binding's default protection level).

Si vous souhaitez spécifier ou ajuster explicitement les exigences en matière de protection pour votre contrat, affectez à la propriété ProtectionLevel (ou à l’une des propriétés ProtectionLevel à une plus petite portée) le niveau requis par votre contrat de service.If you want to explicitly specify or adjust the protection requirements for your contract, set the ProtectionLevel property (or any of the ProtectionLevel properties at a smaller scope) to the level your service contract requires. Dans ce cas, l’utilisation d’un paramètre explicite requiert que la liaison prenne en charge ce paramètre au minimum pour la portée utilisée.In this case, using an explicit setting requires the binding to support that setting at a minimum for the scope used. Par exemple, l'exemple de code suivant spécifie explicitement une valeur ProtectionLevel, pour l'opération GetGuid.For example, the following code example specifies one ProtectionLevel value explicitly, for the GetGuid operation.

[ServiceContract]  
public interface IExplicitProtectionLevelSampleService  
{  
  [OperationContractAttribute]  
  public string GetString();  
  
  [OperationContractAttribute(ProtectionLevel=ProtectionLevel.None)]  
  public int GetInt();    
  [OperationContractAttribute(ProtectionLevel=ProtectionLevel.EncryptAndSign)]  
  public int GetGuid();    
}  

L'exemple suivant illustre le code Visual Basic équivalent.The following is the equivalent Visual Basic code.

<ServiceContract()> _   
Public Interface IExplicitProtectionLevelSampleService   
    <OperationContract()> _   
    Public Function GetString() As String   
    End Function   
  
    <OperationContract(ProtectionLevel := ProtectionLevel.None)> _   
    Public Function GetInt() As Integer   
    End Function   
  
    <OperationContractAttribute(ProtectionLevel := ProtectionLevel.EncryptAndSign)> _   
    Public Function GetGuid() As Integer   
    End Function   
  
End Interface  

Un service qui implémente ce contrat IExplicitProtectionLevelSampleService et qui a un point de terminaison qui utilise le WSHttpBinding par défaut (le System.ServiceModel.SecurityModepar défaut, qui est Message) a le comportement suivant :A service that implements this IExplicitProtectionLevelSampleService contract and has an endpoint that uses the default WSHttpBinding (the default System.ServiceModel.SecurityMode, which is Message) has the following behavior:

  • Les messages d'opération GetString sont chiffrés et signés.The GetString operation messages are encrypted and signed.

  • Les messages d'opération GetInt sont envoyés comme texte non chiffré et non signé (autrement dit, en texte clair).The GetInt operation messages are sent as unencrypted and unsigned (that is, plain) text.

  • L'opération GetGuidSystem.Guid est retournée dans un message qui est chiffré et signé.The GetGuid operation System.Guid is returned in a message that is encrypted and signed.

Pour plus d’informations sur les niveaux de protection et leur utilisation, consultez Présentation du niveau de protection.For more information about protection levels and how to use them, see Understanding Protection Level. Pour plus d’informations sur la sécurité, consultez Sécurisation des services.For more information about security, see Securing Services.

Autres exigences de signature d’opérationOther Operation Signature Requirements

Certaines fonctionnalités d’application requièrent un type particulier de signature d’opération.Some application features require a particular kind of operation signature. Par exemple, la liaison NetMsmqBinding prend en charge les services et clients fiables, dans lesquels une application peut redémarrer au milieu de la communication et reprendre là où elle s’est interrompue sans entraîner la perte de messages.For example, the NetMsmqBinding binding supports durable services and clients, in which an application can restart in the middle of communication and pick up where it left off without missing any messages. (Pour plus d’informations, consultez files d’attente dans WCF.) Toutefois, les opérations fiables doivent prendre un seul paramètre in et n'avoir aucune valeur de retour.(For more information, see Queues in WCF.) However, durable operations must take only one in parameter and have no return value.

Un autre exemple est l'utilisation de types Stream dans les opérations.Another example is the use of Stream types in operations. Étant donné que le paramètre Stream inclut le corps du message entier, si une entrée ou une sortie (autrement dit, un paramètre ref, un paramètre out ou une valeur de retour) est de type Stream, il doit s'agir de la seule entrée ou sortie spécifiée dans votre opération.Because the Stream parameter includes the entire message body, if an input or an output (that is, ref parameter, out parameter, or return value) is of type Stream, then it must be the only input or output specified in your operation. De plus, le paramètre ou type de retour doit être Stream, System.ServiceModel.Channels.Message ou System.Xml.Serialization.IXmlSerializable.In addition, the parameter or return type must be either Stream, System.ServiceModel.Channels.Message, or System.Xml.Serialization.IXmlSerializable. Pour plus d’informations sur les flux, consultez données volumineuses et diffusion en continu.For more information about streams, see Large Data and Streaming.

Noms, espaces de noms et obscurcissementNames, Namespaces, and Obfuscation

Les noms et les espaces de noms des types .NET dans la définition de contrats et les opérations sont significatifs lorsque les contrats sont convertis en WSDL et lorsque les messages de contrat sont créés et envoyés.The names and namespaces of the .NET types in the definition of contracts and operations are significant when contracts are converted into WSDL and when contract messages are created and sent. Par conséquent, il est vivement recommandé que les noms et les espaces de noms du contrat de service soient définis explicitement à l'aide des propriétés Name et Namespace de tous les attributs de contrat de prise en charge tels que ServiceContractAttribute, OperationContractAttribute, DataContractAttribute, DataMemberAttribute et d'autres attributs de contrat.Therefore, it is strongly recommended that service contract names and namespaces are explicitly set using the Name and Namespace properties of all supporting contract attributes such as the ServiceContractAttribute, OperationContractAttribute, DataContractAttribute, DataMemberAttribute, and other contract attributes.

Il en résulte notamment que si les noms et les espaces de noms ne sont pas définis explicitement, l’utilisation de l’obfuscation IL sur l’assembly altère les noms et les espaces de noms des types de contrat, WSDL est modifié et les échanges sur le câble échouent généralement.One result of this is that if the names and namespaces are not explicitly set, the use of IL obfuscation on the assembly alters the contract type names and namespaces and results in modified WSDL and wire exchanges that typically fail. Si vous ne définissez pas explicitement les noms et les espaces de noms des contrats mais prévoyez d’utiliser l’obfuscation, utilisez les attributs ObfuscationAttribute et ObfuscateAssemblyAttribute pour empêcher la modification des noms et des espaces de noms des types de contrat.If you do not set the contract names and namespaces explicitly but do intend to use obfuscation, use the ObfuscationAttribute and ObfuscateAssemblyAttribute attributes to prevent the modification of the contract type names and namespaces.

Voir aussiSee also