Codice helper API Web: classi di configurazione

Data di pubblicazione: gennaio 2017

Si applica a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Utilizzare la gerarchia delle classi di configurazione per specificare i dati di connessione necessari per l'accesso a servizi Web di Dynamics 365 dall'applicazione. Puoi fornire i dati di connessione impostando i valori direttamente nel codice, possibilmente per input dell'utente, utilizzando la classe base Configuration. In genere, queste informazioni vengono fornite nelle impostazioni archiviate nel file di configurazione dell'applicazione, utilizzando la classe derivata FileConfiguration.

Il codice sorgente della gerarchia delle classi di configurazione si trova nel file Configuration.cs nella Libreria helper API Web CRM SDK La gerarchia delle classi di configurazione è progettata per essere utilizzata insieme alla classe Authentication per consentirti di determinare una connessione sicura al servizio Dynamics 365. Per ulteriori informazioni, vedere Utilizzare la libreria helper API Web di Microsoft Dynamics 365 (C#).

Dati di connessione

La classe Configuration legge e analizza il file di configurazione dell'applicazione per recuperare i dati seguenti di connessione.

Per ulteriori informazioni su come ottenere un ID client e un URL di reindirizzamento per un'applicazione, vedi Procedura dettagliata: registrare un'app Dynamics 365 con Azure Active Directory per l'utilizzo con Dynamics 365 (online) e Procedura dettagliata: registrare un'app Dynamics 365 con Active Directory per l'utilizzo con Dynamics 365 (locale) tramite Distribuzione con connessione Internet.

Impostazioni di connessione FileConfiguration

La maggior parte degli esempi di API Web Dynamics 365 utilizzano la classe derivata FileConfiguration per estrarre i dati di connessione dal file di configurazione dell'applicazione App.config. Questo file ha diverse impostazioni dell'applicazione che si applicano alle varie modalità di distribuzione di Dynamics 365 Server. L'impostazione connectionString contiene l'URL del servizio e il nome utente. Inoltre, le impostazioni ClientId e RedirectUrl sono necessarie per le distribuzioni con connessione Internet (IFD) o online. Nelle righe seguenti, estrapolate dal file App.config predefinito fornito con la maggior parte degli esempi di API Web, sono contenuti i dati di connessione come valori di segnaposto. È necessario sostituire questi segnaposto con i valori specifici dell'utente corrente, del server Dynamics 365 e dell'applicazione client.

<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>

Il contenuto completo del file di configurazione predefinito viene fornito in Elenco dei file di configurazione predefiniti.

Gerarchia delle classi e membri

Nella tabella seguente vengono elencati i membri pubblici della gerarchia delle classi di configurazione.

Uso

Le classi FileConfiguration e Authentication sono progettate per essere utilizzate in tandem per leggere le informazioni di connessione in App.config e quindi per stabilire una connessione sicura al servizio Dynamics 365 di destinazione. Può essere implementata con le istruzioni seguenti.

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

Il costruttore non predefinito nella classe Configuration abilita l'utilizzo di una stringa di connessione denominata, ad esempio:

Configuration config = new FileConfiguration(“TestServer”);

Se viene passato un nome null o vuoto per la stringa di connessione al costruttore della classe FileConfiguration, viene utilizzata la prima stringa di connessione a partire dall'inizio del file di configurazione.

Inoltre, gli esempi SDK supportano un parametro di comando di runtime, rappresentante il nome della stringa di connessione desiderata, da passare al costruttore. Questa opzione è implementata dal codice seguente:

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

Ordine di ricerca di configurazione

Se si utilizza un file di configurazione dell'applicazione personalizzato o predefinito, l'impostazione dell'applicazione AlternateConfig facoltativa può essere fornita nel file per specificare un file di configurazione alternativo. Se il file esiste, le relative impostazioni di connessione verranno utilizzate.

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

Un uso comune di questa impostazione è di fornire un file di configurazione globale per la condivisione tra più applicazioni, anziché modificare il file App.config di ogni applicazione. Questa funzionalità si rivela particolarmente utile per la condivisione delle informazioni di registrazione e configurazione tra più applicazioni durante le varie fasi di test e sviluppo. Pertanto solo per la produzione fornisci informazioni univoche di registrazione e configurazione per ogni applicazione.

Elenco dei file di configurazione predefiniti

Il file App.config, fornito con la maggior parte degli esempi di API Web Dynamics 365, contengono valori di connessione di segnaposto che devono essere modificati dallo sviluppatore o dall'amministratore del sito.

<?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>

Elenco delle classi

L'origine più aggiornata per la classe è disponibile nella Libreria helper API Web CRM SDK nel pacchetto di NuGet.

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
    }
}

Vedere anche

Informazioni generali sull'API Web Microsoft Dynamics 365 (C#)
Avviare un progetto API Web di Dynamics 365 in Visual Studio (C#)
Utilizzare la libreria helper API Web di Microsoft Dynamics 365 (C#)
Codice helper API Web: classe di autenticazione
Codice helper API Web: CrmHttpResponseException class

Microsoft Dynamics 365

© 2017 Microsoft. Tutti i diritti sono riservati. Copyright