Code d'aide de l'API Web : classes de configuration

Article
04/18/2017

Date de publication : janvier 2017

S’applique à : Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Utilisez la hiérarchie de classe de configuration pour spécifier les données de connexion requises pour accéder aux services Web Dynamics 365 à partir de votre application. Vous pouvez fournir ces données de connexion en définissant des valeurs directement dans votre code, éventuellement à partir de l'entrée d'utilisateur, via la classe de base Configuration. Plus généralement, vous fournissez ces informations dans les paramètres stockés dans le fichier de configuration de l'application, via la classe dérivée, FileConfiguration.

Le code source de la hiérarchie de classe de configuration se trouve dans le fichier Configuration.cs de la Bibliothèque d'aide de l'API Web du Kit de développement logiciel (SDK) de CRM La hiérarchie de classe de configuration est conçue pour fonctionner conjointement avec la classe Authentication pour vous permettre d'établir une connexion sécurisée à votre service Dynamics 365. Pour plus d'informations, voir Utiliser la bibliothèque d'aide de l'API Web Microsoft Dynamics 365 (C#).

Données de connexion

La classe Configuration lit et analyse le fichier de configuration de l'application pour obtenir les données de connexion ci-après.

Données de connexion	Déploiements	Description
URL du service	Tous	URL de base du service Dynamics 365
Nom d'utilisateur	Tous	Nom d'utilisateur enregistré dans Dynamics 365
Mot de passe	Tous	Mot de passe de cet utilisateur
Domaine	Tous	Domaine du service Dynamics 365 pour l'authentification Active Directory
ID client	En ligne et IFD uniquement	ID client de l'application tel qu'il a été enregistré auprès d'Azure AD pour Dynamics 365 (en ligne) ou votre client Active Directory pour Dynamics 365 (local) avec Déploiement avec accès via Internet (IFD).
URL de redirection	En ligne et IFD uniquement	URI de rappel pour l'application actuelle.

Pour plus d'informations sur l'obtention d'un ID client et d'une URL de redirection pour une application, voir Guide pas-à-pas : Enregistrer une application Dynamics 365 auprès d'Azure Active Directory à utiliser avec Dynamics 365 (en ligne) et Guide pas-à-pas : Enregistrer une application Dynamics 365 auprès d'Active Directory à utiliser avec Dynamics 365 (local) avec Déploiement avec accès via Internet (IFD).

Paramètres de connexion FileConfiguration

La plupart des exemples de l'API Web de Dynamics 365 utilisent la classe dérivée, FileConfiguration, pour extraire les données de connexion du fichier de configuration de l'application, App.config. Ce fichier contient plusieurs paramètres d'application qui s'appliquent aux différents modes de déploiement de Dynamics 365 Server. Le paramètre connectionString contient l'URL de service et le nom d'utilisateur. En outre, les paramètres ClientId et RedirectUrl sont requis pour les déploiements en ligne ou avec accès via Internet. Les lignes suivantes, extraites du fichier App.config par défaut fourni avec la plupart des exemples de l'API Web, contiennent ces données de connexion comme valeurs d'espace réservé. Vous devez remplacer ces espaces réservés par des valeurs spécifiques à l'utilisateur actuel, à votre serveur Microsoft Dynamics 365 et à votre application cliente.

<connectionStrings>  
  <add name="default"  connectionString="Url=http://myserver/myorg/; Username=name; Password=password; Domain=domain" />
</connectionStrings>  

<appSettings>
  <add key="ClientId" value="e5cf0024-a66a-4f16-85ce-99ba97a24bb2" />
  <add key="RedirectUrl" value="https://localhost/SdkSample" />
</appSettings>

Le contenu complet du fichier de configuration par défaut est disponible dans Liste des fichiers de configuration par défaut.

Hiérarchie et membres de classe

Le tableau suivant indique les membres publics de la hiérarchie de classe de configuration.

Bibliothèque d'aide de l'API Web de Dynamics 365 - Diagramme des classes de configuration

Classe de configuration

Propriétés :

Toutes les propriétés sont mappées directement aux données de connexion correspondantes détaillées dans la section précédente.

Méthodes :

Le constructeur par défaut conserve toutes les propriétés non initialisées (null).

Classe FileConfiguration

Propriétés :

Name est le nom de l'entrée de chaîne de connexion.

PathToConfig est le chemin d'accès complet ou relatif au fichier de configuration de l'application.

Méthodes :

Le constructeur par défaut conserve toutes les propriétés non initialisées (null).

Le constructeur non défini par défaut accepte un paramètre de chaîne unique qui spécifie la chaîne de connexion nommée. Si vous utilisez une valeur de chaîne vide ou nulle, la première entrée de chaîne de connexion est utilisée.

La méthode Load ouvre, lit et analyse le fichier de configuration spécifié. Elle est utilisée par le constructeur non défini par défaut.

Utilisation

Les classes FileConfiguration et Authentication sont conçues pour être utilisées en tandem pour lire les informations de connexion du fichier App.config et établir une connexion sécurisée au service Dynamics 365 cible. Cette option peut être implémentée avec les instructions suivantes.

FileConfiguration config = new FileConfiguration(null);
Authentication auth = new Authentication(config);
httpClient = new HttpClient(auth.ClientHandler, true);

Le constructeur non défini par défaut dans la classe Configuration permet d'utiliser une chaîne de connexion nommée, par exemple :

Configuration config = new FileConfiguration(“TestServer”);

Si un nom de chaîne de connexion nulle ou vide est transmis au constructeur de classe FileConfiguration, la première chaîne de connexion en haut du fichier de configuration est utilisée.

En outre, les exemples du Kit de développement logiciel (SDK) prennent en charge un paramètre de commande d'exécution, représentant le nom de la chaîne de connexion souhaitée, à transmettre au constructeur. Cette option est implémentée par le code suivant :

if (cmdargs.Length > 0)
{
    config = new FileConfiguration(cmdargs[0]);
}
else
{
    config = new FileConfiguration(null);
}

Ordre de recherche de configuration

Que vous utilisiez le fichier de configuration de l'application par défaut ou personnalisé, le paramètre d'application AlternateConfig facultatif peut être fourni dans le fichier pour spécifier un autre fichier de configuration. Si ce fichier existe, ses paramètres de connexion sont utilisés à la place.

<add key="AlternateConfig" value="C:\Temp\crmsample.exe.config"/>

Ce paramètre est souvent utilisé pour fournir un fichier de configuration global à partager entre plusieurs applications, au lieu de modifier le fichier App.config de chaque application. Cela est particulièrement utile pour partager des informations de configuration et d'enregistrement entre plusieurs applications qui passent les phases de développement et de test. Ce n'est que pour la production que vous fournissez des informations de configuration et d'enregistrement uniques pour chaque application.

Liste des fichiers de configuration par défaut

Le fichier App.config, fourni avec la plupart des exemples de l'API Web de Dynamics 365, contient des valeurs d'espace réservé qui doivent être modifiées par le développeur ou l'administrateur du site.

<?xml version="1.0" encoding="utf-8"?>
<configuration>

  <startup>
    <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.5.2" />
  </startup>

  <connectionStrings>
    <clear />

    <!-- When providing a password, make sure to set the app.config file's security so that only you can read it. -->
    <add name="default"   connectionString="Url=http://myserver/myorg/; Username=name; Password=password; Domain=domain" />
    <add name="CrmOnline" connectionString="Url=https://mydomain.crm.dynamics.com/; Username=someone@mydomain.onmicrosoft.com; Password=password" />
  </connectionStrings>  

  <appSettings>
    <!--For information on how to register an app and obtain the ClientId and RedirectUrl
        values see https://msdn.microsoft.com/dynamics/crm/mt149065 -->

    <!--Active Directory application registration. -->
    <!--These are dummy values and should be replaced with your actual app registration values.-->
    <add key="ClientId" value="e5cf0024-a66a-4f16-85ce-99ba97a24bb2" />
    <add key="RedirectUrl" value="https://localhost/SdkSample" />

    <!-- Use an alternate configuration file for connection string and setting values. This optional setting
    enables use of an app.config file shared among multiple applications. If the specified file does
    not exist, this setting is ignored.-->
    <add key="AlternateConfig" value="C:\Temp\crmsample.exe.config"/>
  </appSettings>

 </configuration>

Liste des classes

La source la plus récente pour cette classe est disponible dans le package NuGet Bibliothèque d'aide de l'API Web du Kit de développement logiciel (SDK) de CRM.

using System;
using System.IO;
using System.Security;
using System.Configuration;

namespace Microsoft.Crm.Sdk.Samples.HelperCode
{
    /// <summary>
    /// An application configuration containing user logon, application, and web service information
    /// as required for CRM Web API authentication.
    /// </summary>
    public class Configuration
    {
        #region Properties
        /// <summary>
        /// The root address of the CRM service.
        /// </summary>
        /// <example>https://myorg.crm.dynamics.com</example>
        public string ServiceUrl { get; set; }

        /// <summary>
        /// The redirect address provided when the application was registered in Microsoft Azure
        /// Active Directory or AD FS.
        /// </summary>
        /// <remarks>Required only with a web service configured for OAuth authentication.</remarks>
        /// <seealso cref="https://msdn.microsoft.com/library/dn531010.aspx#bkmk_redirect"/>
        public string RedirectUrl { get; set; }

        /// <summary>
        /// The client ID that was generated when the application was registered in Microsoft Azure
        /// Active Directory or AD FS.
        /// </summary>
        /// <remarks>Required only with a web service configured for OAuth authentication.</remarks>
        public string ClientId { get; set; }

        /// <summary>
        /// The user name of the logged on user or null.
        /// </summary>
        public string Username { get; set; }

        /// <summary>
        ///  The password of the logged on user or null.
        /// </summary>
        public SecureString Password { get; set; }

        /// <summary>
        ///  The domain of the logged on user account or null.
        /// </summary>
        /// <remarks>Required only with a web service configured for Active Directory authentication.</remarks>
        public string Domain { get; set; }

        #endregion Properties

        #region Constructors

        /// <summary>
        /// Constructs a configuration object.
        /// </summary>
        public Configuration() { }

        #endregion Constructors
    }

    /// <summary>
    /// A configuration that is persisted to file storage.
    /// </summary>
    /// <remarks>This implementation defaults to using an app.config file. However, you
    /// can derive a subclass and override the virtual methods to make use of other
    /// file formats.
    /// 
    /// One set of application registration settings and multiple named connection strings are supported.</remarks>
    public class FileConfiguration : Configuration
    {
        #region Properties
        /// <summary>
        /// The full or relative path to the application's configuration file.
        /// </summary>
        /// <remarks>The file name is in the format <appname>.exe.config.</appname></remarks>
        public string PathToConfig { get; set; }

        /// <summary>
        /// The name of the connection.
        /// </summary>
        public string Name { get; set; }

        #endregion Properties

        #region Constructors
        /// <summary>
        /// Constructs a file configuration.
        /// </summary>
        public FileConfiguration()
            : base()
        { }

        /// <summary>
        /// Loads a named connection string and application settings from persistent file storage.
        /// The configuration file must have the same name as the application and be located in the 
        /// run-time folder.
        /// </summary>
        /// <param name="name">The name of the target connection string. An empty or null string value 
        /// results in the first named configuration being used.</param>
        /// <remarks>The app.config file must exist in the run-time folder and have the name
        /// <appname>.exe.config. To specify an app.config file path, use the Load() method.</remarks>
        public FileConfiguration(string name)
            : base()
        {
            var path = System.IO.Path.Combine(Directory.GetCurrentDirectory(), Environment.GetCommandLineArgs()[0]);

            Load(name, String.Concat(path, ".config"));
        }

        #endregion Constructors

        #region Methods
        /// <summary>
        /// Loads server connection information and application settings from persistent file storage.
        /// </summary>
        /// <remarks>A setting named OverrideConfig can optionally be added. If a config file that this setting
        /// refers to exists, that config file is read instead of the config file specified in the path parameter.
        /// This allows for an alternate config file, for example a global config file shared by multiple applications.
        /// </summary>
        /// <param name="connectionName">The name of the connection string in the configuration file to use. 
        /// Each CRM organization can have its own connection string. A value of null or String.Empty results
        /// in the first (top most) connection string being used.</param>
        /// <param name="path">The full or relative pathname of the configuration file.</param>
        public virtual void Load(string connectionName, string path)
        {
            // Check passed parameters.
            if (string.IsNullOrEmpty(path) || !System.IO.File.Exists(path))
                throw new ArgumentException("The specified app.config file path is invalid.", this.ToString());
            else
                PathToConfig = path;

            try
            {
                // Read the app.config file and obtain the app settings.
                System.Configuration.Configuration config = null;
                ExeConfigurationFileMap configFileMap = new ExeConfigurationFileMap();
                configFileMap.ExeConfigFilename = PathToConfig;
                config = ConfigurationManager.OpenMappedExeConfiguration(configFileMap, ConfigurationUserLevel.None);

                var appSettings = config.AppSettings.Settings;

                // If an alternate config file exists, load that configuration instead. Note the test
                // for redirectTo.Equals(path) to avoid an infinite loop.
                if (appSettings["AlternateConfig"] != null)
                {
                    var redirectTo = appSettings["AlternateConfig"].Value;
                    if (redirectTo != null && !redirectTo.Equals(path) && System.IO.File.Exists(redirectTo))
                    {
                        Load(connectionName, redirectTo);
                        return;
                    }
                }

                // Get the connection string.
                ConnectionStringSettings connection;
                if (string.IsNullOrEmpty(connectionName))
                {
                    // No connection string name specified, so use the first one in the file.
                    connection = config.ConnectionStrings.ConnectionStrings[0];
                    Name = connection.Name;
                }
                else
                {
                    connection = config.ConnectionStrings.ConnectionStrings[connectionName];
                    Name = connectionName;
                }

                // Get the connection string parameter values.
                if (connection != null)
                {
                    var parameters = connection.ConnectionString.Split(';');
                    foreach (string parameter in parameters)
                    {
                        var trimmedParameter = parameter.Trim();
                        if (trimmedParameter.StartsWith("Url="))
                            ServiceUrl = parameter.Replace("Url=", String.Empty).TrimStart(' ');

                        if (trimmedParameter.StartsWith("Username="))
                            Username = parameters[1].Replace("Username=", String.Empty).TrimStart(' ');

                        if (trimmedParameter.StartsWith("Password="))
                        {
                            var password = parameters[2].Replace("Password=", String.Empty).TrimStart(' ');

                            Password = new SecureString();
                            foreach (char c in password) Password.AppendChar(c);
                        }
                        if (trimmedParameter.StartsWith("Domain="))
                            Domain = parameter.Replace("Domain=", String.Empty).TrimStart(' ');
                    }
                }
                else
                    throw new Exception("The specified connection string could not be found.");

                // Get the Azure Active Directory application registration settings.
                RedirectUrl = appSettings["RedirectUrl"]?.Value;
                ClientId = appSettings["ClientId"]?.Value;
            }
            catch (InvalidOperationException e)
            {
                throw new Exception("Required setting in app.config does not exist or is of the wrong type.", e);
            }
        }

        /// <summary>
        /// Save the current configuration to persistent file storage.
        /// </summary>
        /// <remarks>Any existing configuration is overwritten.</remarks>
        public virtual void Save()
        {
            throw new NotImplementedException();
        }

        /// <summary>
        /// Add a named connection string to persistent file storage.
        /// </summary>
        /// <remarks>A named connection string from the current configuration is added to an existing
        /// configuration file./remarks>
        public virtual void AddConnection()
        {
            throw new NotImplementedException();
        }

        #endregion Methods
    }
}

Voir aussi

Se familiariser avec l'API Web Microsoft Dynamics 365 (C#)
Démarrer un projet de l'API Web de Dynamics 365 dans Visual Studio (C#)
Utiliser la bibliothèque d'aide de l'API Web Microsoft Dynamics 365 (C#)
Code d'assistance de l'API Web : Classe Authentication
Code d'assistance de l'API Web : Classe CrmHttpResponseException

Microsoft Dynamics 365

Partager via