Étape 3 : Implémenter la connexion pour l’adaptateur Echo

Durée d’exécution : 45 minutes

Dans cette étape, vous implémentez la fonctionnalité de connexion de l’adaptateur Echo. En fonction du Kit de développement logiciel (SDK) de l’adaptateur LOB WCF, vous devez implémenter la classe et les interfaces abstraites suivantes lors de la connexion au système cible.

• Microsoft.ServiceModel.Channels.Common.ConnectionUri

• Microsoft.ServiceModel.Channels.Common.IConnection

• Microsoft.ServiceModel.Channels.Common.IConnectionFactory

  Au lieu de dériver de la classe et des interfaces abstraites ci-dessus, l’Assistant Développement d’adaptateur génère automatiquement les trois classes dérivées, EchoAdapterConnectionUri, EchoAdapterConnectionUri et EchoAdapterConnectionFactory. En plus de créer les classes, chacun a une méthode par défaut qui lève une exception spécifique. System.NotImplementedException Cette instruction rappelle au développeur d’implémenter chaque classe. Lorsque la classe est implémentée, cette instruction de levée d’exception doit être supprimée.

  Dans la section suivante, vous mettez à jour ces trois classes pour mieux comprendre comment gérer une connexion, la structure d’URI et comment récupérer par programmation différents éléments d’URI, puis utiliser ces éléments dans l’adaptateur.

Conditions préalables

Avant de commencer cette étape, vous devez avoir terminé l’étape 2 : catégoriser les propriétés de l’adaptateur et de la connexion. Et vous devriez avoir une compréhension claire des classes Microsoft.ServiceModel.Channels.Common.IConnection, Microsoft.ServiceModel.Channels.Common.IConnectionFactory et Microsoft.ServiceModel.Channels.Common.ConnectionUri.

Connection-Related Classes

L'Assistant de développement d'adaptateurs génère trois classes dérivées : EchoAdapterConnection, EchoAdapterConnectionUri et EchoAdapterConnectionFactory. Voici une brève vue d’ensemble des méthodes associées à chacun d’eux.

EchoAdapterConnection

Selon la complexité de votre adaptateur, vous devrez peut-être implémenter toutes les cinq méthodes suivantes. Pour l’adaptateur Echo, la plupart ne sont pas pris en charge, car l’exemple d’adaptateur Echo n’implique aucun système cible.

Méthode	Description
public void Close(TimeSpan timeout)	Ferme la connexion au système cible. L’adaptateur Echo utilise cette méthode pour ajouter uniquement des événements de trace à l’écouteur de trace.
public bool IsValid(TimeSpan timeout)	Retourne une valeur indiquant si la connexion est toujours valide. Non pris en charge par l’adaptateur Echo.
public void Open(TimeSpan timeout)	Ouvre la connexion au système cible. N/A pour l’adaptateur Echo. Toutefois, l’exemple montre comment utiliser un élément URI appelé enableAuthentication pour exiger que les utilisateurs fournissent un nom d’utilisateur.
public void ClearContext()	Efface le contexte de la connexion. Cette méthode est appelée lorsque la connexion est rétablie dans le pool de connexions. Non pris en charge par l’adaptateur Echo.
public void Abort()	Abandonne la connexion au système cible. Non pris en charge par l’adaptateur Echo.

EchoAdapterConnectionFactory

L'usine de création de connexion est chargée de créer la connexion. Par défaut, vous devez modifier cette classe uniquement lors de la connexion à un système cible. Bien que l’adaptateur Echo n’implique aucun système cible, il vous montre comment utiliser un élément d’URI personnalisé appelé enableAuthentication si votre connexion nécessite une authentification utilisateur.

Remarque

L’enableAuthentication n’est pas un mot clé, il s’agit simplement d’un nom de variable. Par conséquent, vous pouvez choisir n’importe quel nom pour celui-ci.

EchoAdapterConnectionUri

Cela représente une chaîne de connexion au système cible.

Méthode	Description
URI d’URI de remplacement public	Obtient et définit l’URI. Autorisé à générer la chaîne URI et configurer pour analyser la chaîne URI.
public EchoAdapterConnectionUri()	Initialise une nouvelle instance de la classe ConnectionUri.
chaîne de substitution publique SampleUriString	Renvoie EchoAdapter.SCHEME + " ://{hostname}/{application} ?enableAuthentication={True|False}". Cette chaîne de retour s’affiche en tant qu’exemple dans l’outil Add Adapter Service Reference Plug-in, comme illustré dans la figure suivante.

URI de connexion de l’adaptateur Echo

L’exemple d’URI de connexion de l’adaptateur Echo est décrit comme suit : EchoAapter.SCHEME ://{hostname}/{application} ?enableAuthentication={true|false}

Étant donné que EchoAapter.SCHEME est echov2, l’URI de connexion est :

echo2://lobhostname/lobapplication?enableAuthentication={true|false}

Vous pouvez lire l’URI de connexion précédent lors de l’activation deAuthentication=false comme suit :

À l’aide du schéma de transport echov2, accédez à un ordinateur nommé lobhostname, où une application nommée lobapplication qui ne nécessite aucune authentification attend votre connexion.

Ou, quand enableAuthentication=true, lisez la connexion comme suit :

À l’aide du schéma de transport echov2, accédez à un ordinateur nommé lobhostname, où une application nommée lobapplication s’attend à ce que l’authentification attend votre connexion. Pour l’adaptateur Echo, seul un nom d’utilisateur est requis.

Avec un URI défini, vous pouvez l’utiliser par programmation et l’analyser pour la connectivité et la configuration. Si la connexion nécessite des données sensibles telles qu’un nom d’utilisateur et un mot de passe, ne contiennent pas ces informations dans l’URI. Au lieu de cela, ajoutez ces informations dans l’objet System.ServiceModel.Description.ClientCredentials . L’exemple de code que vous ajoutez vous montre comment procéder.

Dans le code suivant, l’adaptateur Echo construit l’URI de deux façons pour vous montrer comment l’adaptateur peut utiliser différents éléments d’URI pour modifier la fonctionnalité d’adaptateur.

echo2 ://lobhostname/lobapplication ?enableAuthentication=[true|false]

echo2://lobhostname/lobapplication?enableAuthentication=[true|false]&echoInUpperCase=true

Récupération de l’élément URI

Vous pouvez interpréter chaque élément URI dans l’URI de l’adaptateur Echo echo2://lobhostname/lobapplication?enableAuthentication=false&echoInUpperCase=false. Les valeurs d’élément URI et les méthodes associées sont répertoriées dans le tableau suivant :

Valeur de l’élément URI	Méthode
lobhostname	System.Uri.Host%2A pour récupérer le nom d’hôte
Lobapplication	System.Uri.AbsolutePath%2A pour récupérer le nom de l’application cible
activerAuthentification=false	GetQueryStringValue(« enableAuthentication ») Utilisez cet élément URI pour valider les informations d’identification de l’utilisateur Remarque : GetQueryStringValue est une méthode statique définie dans le Microsoft.ServiceModel.Channels.Common.ConnectionUri
echoInUpperValue=false	GetQueryStringValue(« echoInUpperValue ») Utilisez cet élément URI pour convertir la chaîne entrante en majuscules.

Élément URI EnableAuthentication

Votre système cible vous oblige souvent à fournir des informations d’identification client pour établir une connexion au système cible. Comme mentionné, l’adaptateur Echo n’implique aucun système cible. Bien qu’il s’agit d’un exemple, il montre comment utiliser un élément URI personnalisé appelé enableAuthentication pour fournir les informations d’identification.

 public class EchoAdapterConnection : IConnection   
{  
….  
   public void Open(TimeSpan timeout)  
  {  
    // only validate the credentials if EnableAuthentication  
    // connection property value is true  
    if (this.ConnectionFactory.ConnectionUri.EnableAuthentication)  
    {  
        // this adapter expects a value in username  
        if (this.connectionFactory.ClientCredentials != null &&  
            string.IsNullOrEmpty(this.connectionFactory.ClientCredentials.UserName.UserName))  
        {  
            throw new CredentialsException("Username is expected.");  
        }  
  }  
}  

Le code vérifie si enableAuthentication a la valeur true et si un nom d’utilisateur n’est pas fourni ; si un nom d’utilisateur n’est pas fourni, il lève une exception, interceptée par l’outil Add Adapter Service Reference Plug-in, comme indiqué ci-dessous :

Pour fournir le nom d’utilisateur, vous pouvez l’entrer dans la boîte de dialogue Configurer l’adaptateur dans l’outil Add Adapter Service Reference Plug-in, comme illustré dans la figure suivante :

EchoInUpperCase URI élément

L’élément URI EchoInUpperCase peut être référencé comme un indicateur booléen. Si l’indicateur est true, l’adaptateur convertit la chaîne d’entrée de l’opération EchoStrings en majuscules.

Pour modifier la valeur par défaut de l’élément URI echoInUpperCase, utilisez l’onglet Propriétés de l’URI de l’adaptateur Configurer dans le plug-in Add Adapter Service Reference, comme indiqué ci-dessous.

Mise à jour d’EchoAdapterConnection

Vous implémentez la méthode IsValid, Open et Close de la classe EchoAdapterConnection.

Pour mettre à jour la classe EchoAdapterConnection

1. Dans l’Explorateur de solutions, double-cliquez sur le fichier EchoAdapterConnection.cs .

2. Dans l’éditeur Visual Studio, cliquez avec le bouton droit n’importe où dans l’éditeur, dans le menu contextuel, pointez sur Plan, puis cliquez sur Arrêter le plan.

3. Dans l’éditeur Visual Studio, recherchez la méthode IsValid . Dans la méthode IsValid , remplacez l’implémentation existante par celle ci-dessous :

   return true;  
   

4. Dans l’éditeur Visual Studio, recherchez la méthode Open . Dans la méthode Open , remplacez l’implémentation existante par l’implémentation suivante. Cela vous montre comment utiliser l’élément EnableAuthentication URI pour vous assurer que le nom d’utilisateur est fourni :

   // only validate the credentials if EnableAuthentication  
   // connection property value is true  
   if (this.ConnectionFactory.ConnectionUri.EnableAuthentication)  
   {  
       // this adapter expects a value in username  
       // it just logs the credentials in the trace file  
       if (this.connectionFactory.ClientCredentials != null &&  
           string.IsNullOrEmpty(this.connectionFactory.ClientCredentials.UserName.UserName))  
       {  
           throw new CredentialsException("Username is expected.");  
       }  
       // got the username, log it in trace file  
       EchoAdapterUtilities.Trace.Trace(System.Diagnostics.TraceEventType.Information, "EchoAdapterConnection::Open", "Username is " + this.connectionFactory.ClientCredentials.UserName.UserName);  
   }  
   EchoAdapterUtilities.Trace.Trace(System.Diagnostics.TraceEventType.Information, "EchoAdapterConnection::Open", "Connection successfully established!");  
   

5. Dans l’éditeur Visual Studio, recherchez la méthode Close . À l’intérieur de la méthode Close , ajoutez l’instruction unique suivante :

   EchoAdapterUtilities.Trace.Trace(System.Diagnostics.TraceEventType.Information, "EchoAdapterConnection::Close", "Connection successfully closed!");  
   

Mise à jour de EchoAdapterConnectionFactory

Vous implémentez le constructeur EchoAdapterConnectionFactory et ajoutez deux propriétés appelées ClientCredentials et ConnectionUri.

Pour mettre à jour la classe EchoAdapterConnectionFactory

1. Dans l’Explorateur de solutions, double-cliquez sur le fichier EchoAdapterConnectionFactory.cs .

2. Dans l’éditeur Visual Studio, cliquez avec le bouton droit n’importe où dans l’éditeur, dans le menu contextuel, pointez sur Plan, puis cliquez sur Arrêter le plan.

3. Dans l’éditeur Visual Studio, recherchez la région Champs privés . Ajoutez l'énoncé suivant :

   private EchoAdapterConnectionUri connectionUri;  
   

   Votre liste de champs privés doit correspondre à ce qui suit :

   // Stores the client credentials  
   private ClientCredentials clientCredentials;  
   // Stores the adapter class  
   private EchoAdapter adapter;  
   private EchoAdapterConnectionUri connectionUri;  
   

4. Dans l’éditeur Visual Studio, recherchez la méthode EchoAdapterConnectionFactory . Dans la méthode du constructeur EchoAdapterConnectionFactory , avant « } », ajoutez l’instruction unique suivante comme dernière instruction.

   this.connectionUri = connectionUri as EchoAdapterConnectionUri;  
   

   L’implémentation de la méthode EchoAdapterConnectionFactory doit correspondre à ce qui suit :

   /// <summary>  
   /// Initializes a new instance of the EchoAdapterConnectionFactory class  
   /// </summary>  
   public EchoAdapterConnectionFactory(ConnectionUri connectionUri  
       , ClientCredentials clientCredentials  
       , EchoAdapter adapter)  
   {  
       this.clientCredentials = clientCredentials;  
       this.adapter = adapter;  
       //added  
       this.connectionUri = connectionUri as EchoAdapterConnectionUri;  
   }  
   

5. Dans l’éditeur Visual Studio, recherchez la région Propriétés publiques . Ajoutez le code suivant :

   /// <summary>  
   /// Returns the client credentials  
   /// </summary>  
   public ClientCredentials ClientCredentials  
   {  
       get  
       {  
           return this.clientCredentials;  
       }  
   }  
   
   /// <summary>  
   /// Returns the Connection Uri for this adapter  
   /// </summary>  
   public EchoAdapterConnectionUri ConnectionUri  
   {  
       get  
       {  
           return this.connectionUri;  
       }  
   }  
   

Mise à jour de EchoAdapterConnectionUri

Vous implémentez le constructeur par défaut EchoAdapterConnectionUri, le constructeur surchargé EchoAdapterConnectionUri(URI) et la propriété URI de remplacement public.

Pour mettre à jour la classe EchoAdapterConnectionUri

1. Dans l’Explorateur de solutions, double-cliquez sur le fichier EchoAdapterConnectionUri.cs .

2. Dans l’éditeur Visual Studio, cliquez avec le bouton droit n’importe où dans l’éditeur, dans le menu contextuel, pointez sur Plan, puis cliquez sur Arrêter le plan.

3. Dans l’éditeur Visual Studio, recherchez la région constructeurs . Dans le constructeur par défaut EchoAdapterConnectionUri(), ajoutez l’instruction suivante :

   Uri = new Uri("echov2://lobhostname/lobapplication?enableauthentication=False");  
   

4. Dans l'éditeur Visual Studio, à l'intérieur du constructeur surchargé EchoAdapterConnectionUri(Uri uri), ajoutez l'instruction suivante :

   Uri = uri;  
   

   Votre implémentation de la méthode EchoAdapterConnectionUri(URI) doit correspondre à ce qui suit :

   public EchoAdapterConnectionUri(Uri uri)  
       : base()  
   {  
       Uri = uri;  
   }  
   

5. Dans l’éditeur Visual Studio, à l’intérieur de la méthode public override Uri Uri, remplacez le contenu existant par la logique suivante. Get génère l’URI avec echoInUpperCase ou sans celui-ci. L'ensemble analyse l'URI pour récupérer le nom de l'hôte, le nom de la base de données et les valeurs de requête.

   get  
   {  
       // Build the uri  
       if (String.IsNullOrEmpty(this.hostname)) throw new InvalidUriException("Invalid target system host name.");  
       if (String.IsNullOrEmpty(this.application)) throw new InvalidUriException("Invalid target system data source name.");  
       if (EchoInUpperCase)  
       {  
           // build the uri with echoInUpperCase= query string  
           return new Uri(EchoAdapter.SCHEME + "://" + Hostname + "/" + Application + "?" + "enableAuthentication=" + EnableAuthentication + "&" + "echoInUpperCase=" + echoInUpperCase);  
       }  
       else  
       {  
           // build the uri without echoInUpperCase= query string  
           return new Uri(EchoAdapter.SCHEME + "://" + Hostname + "/" + Application + "?" + "enableAuthentication=" + EnableAuthentication);  
       }  
   }  
   set  
   {  
       // Parse the uri  
       String[] enableAuthValue = GetQueryStringValue(value, "enableAuthentication");  
       if (enableAuthValue.Length > 0) this.enableAuthentication = Boolean.Parse(enableAuthValue[0]);  
       String[] echoInUpperValue = GetQueryStringValue(value, "echoInUpperCase");  
       if (echoInUpperValue.Length > 0) this.echoInUpperCase = Boolean.Parse(echoInUpperValue[0]);  
   
       this.hostname = value.Host;  
       String[] applicationValue = value.AbsolutePath.Split('/');  
       if (applicationValue.Length > 1) this.Application = applicationValue[1];  
   }  
   

6. Dans Visual Studio, dans le menu Fichier , cliquez sur Enregistrer tout.

7. Dans le menu Générer, cliquez sur Générer la solution. Vous devez compiler le projet avec succès. Si ce n’est pas le cas, vérifiez que vous avez suivi chaque étape ci-dessus.

Remarque

Vous avez enregistré votre travail. Vous pouvez fermer Visual Studio en toute sécurité pour l’instant ou passer à l’étape suivante : Implémenter le gestionnaire de navigation des métadonnées pour l’adaptateur Echo.

Qu’est-ce que j’ai fait ?

Vous avez implémenté la connexion pour l’adaptateur Echo. Vous avez appris les composants de connexion du SDK de l’adaptateur LOB WCF, la structure de base de l’URI de connexion, l’analyse programmatique des éléments d’URI et la façon dont vous pouvez utiliser l’élément URI pour modifier la fonctionnalité d’adaptateur.

Étapes suivantes

Vous implémentez la navigation, la recherche et la résolution des métadonnées et l’échange de messages sortants. Enfin, vous générez et déployez l’adaptateur.

Voir aussi

Étape 4 : Implémenter le gestionnaire de navigation des métadonnées pour l’adaptateur Echo
Tutoriel 1 : Développer l’adaptateur Echo