Código auxiliar de API da Web: Classes de configuração

Publicado: janeiro de 2017

Aplicável a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Use a hierarquia de classes de configuração para especificar os dados de conexão necessários para acessar os serviços Web do Dynamics 365 do seu aplicativo. Você pode fornecer esses dados de conexão ao configurar valores diretamente em seu código, possivelmente de entrada de usuário, usando a classe base Configuration. Geralmente, você fornece essas informações em configurações armazenadas no arquivo de configuração do seu aplicativo, usando a classe derivada FileConfiguration.

O código fonte da hierarquia de classes de configuração está localizado no arquivo Configuration.cs na Biblioteca Auxiliar da API Web do SDK do CRM A hierarquia de classes de configuração foi projetada para funcionar em conjunto com a classe Authentication para permitir que você estabeleça uma conexão segura com o seu serviço do Dynamics 365. Para obter mais informações, consulte Use a Microsoft Dynamics 365 Biblioteca Auxiliar da API Web (C#).

Dados de conexão

A classe Configuration lê e analisa o arquivo de configuração do aplicativo para obter os dados de conexão a seguir.

Para obter mais informações sobre como obter uma ID de cliente e a URL de redirecionamento para um aplicativo, veja Passo a passo: Registrar o aplicativo Dynamics 365 com Ative Directory do Azure para uso com o Dynamics 365 (online) e Passo a passo: Registrar o aplicativo Dynamics 365 com Ative Directory para uso com o Dynamics 365 (local) usando Implantação para a Internet (IFD).

Configurações de conexão de FileConfiguration

A maioria dos exemplos da API Web do Dynamics 365 usa a classe derivada FileConfiguration para extrair os dados de conexão do arquivo de configuração do aplicativo, App.config. O arquivo possui várias configurações de aplicativo que se aplicam a diferentes modos de implantação do Dynamics 365. A configuração connectionStringcontém a URL do serviço e o nome do usuário. Adicionalmente, as configurações ClientId e RedirectUrl são necessárias para as implantações online e as implantações para a Internet (IFDs). As linhas a seguir, retiradas do arquivo App.config padrão, fornecido com a maioria dos exemplos da API Web, contêm esses dados de conexão como valores de espaço reservado. Você deve substituir esses espaços reservados por valores específicos o usuário atual, do seu servidor do Dynamics 365 e do seu aplicativo 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>

O conteúdo completo do arquivo de configuração padrão é fornecido em Listagem padrão do arquivo de configuração.

Hierarquia de classes e membros

A tabela a seguir mostra os membros públicos da hierarquia de classes de configuração.

Uso

As classes FileConfiguration e Authentication foram projetadas para serem usadas em tandem para ler as informações da conexão no arquivo App.config e então estabelecer uma conexão segura com o serviço de destino do Dynamics 365. Isso pode ser implementado com as instruções a seguir.

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

O construtor não padrão na classe Configuration permite o uso de uma cadeia de conexão nomeada, por exemplo:

Configuration config = new FileConfiguration(“TestServer”);

Se um nome de cadeia de conexão null ou vazio for passado para o construtor de classe sãoFileConfiguration, a primeira cadeia de conexão da parte de cima do arquivo de configuração será usada.

Além disso, os exemplos do SDK dão suporte a um parâmetro de comando em tempo de execução, que representa o nome da cadeia de conexão desejada a ser passada para o construtor. Essa opção é implementada pelo seguinte código:

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

Ordem de pesquisa de configuração

Se você estiver usando o arquivo de configuração do aplicativo padrão ou personalizado, a configuração opcional do aplicativo AlternateConfig poderá ser fornecida no arquivo para especificar um arquivo de configuração alternativo. Se esse arquivo existir, suas configurações de conexão serão usadas.

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

Um uso comum dessa configuração é fornecer um arquivo de configuração global a ser compartilhado entre vários aplicativos, em vez da edição do arquivo App.config de cada aplicativo. Isso é especialmente útil para compartilhar informações de configuração e de registro entre vários aplicativos que estejam se movendo entre os estágios de desenvolvimento e de teste. Então, somente para produção você forneceria informações exclusivas de configuração e de registro para cada aplicativo.

Listagem padrão do arquivo de configuração

O arquivo App.config, fornecido com a maioria dos exemplos da API Web do Dynamics 365 contém valores de conexão de espaço reservado que devem ser editados pelo desenvolvedor ou pelo administrador do 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>

Listagem de classes

A origem mais atual dessa classe se encontra no pacote NuGet Biblioteca Auxiliar da API Web do SDK do 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
    }
}

Confira Também

Introdução à API Web do Microsoft Dynamics 365 (C#)
Iniciar um projeto de API Web do Dynamics 365 no Visual Studio (C#)
Use a Microsoft Dynamics 365 Biblioteca Auxiliar da API Web (C#)
Código auxiliar de API da Web: classe de autenticação
Código auxiliar de API da Web: classe CrmHttpResponseException

Microsoft Dynamics 365

© 2017 Microsoft. Todos os direitos reservados. Direitos autorais