• An Azure subscription linked to Team Foundation Server or VSTS using the Azure Resource Manager service endpoint.
• An Azure Key Vault containing the secrets.

• In the Azure portal
• By using Azure PowerShell
• By using the Azure CLI

1. Add Azure key vault task and point it to the service principal created along with the key vault that you want to use. A Secrets filter value of ‘*’ will pull the secrets.

2. For us to able to access the secrets we need to configure variable group that’s our next step. Browse to Library-> VariableGroup

5. Now you can select all the secrets that you want to access from the build definition by adding them as shown below.

6. Finally, you can access them in your definitions as parameter. For example, you want to access the DatabaseConnection that’s part of your key vault, you can specify them as $(DatabaseConnection).

• Install Visual Studio 2017 15.3 (or later)

• You must have either the “ASP.NET and web development” or “Azure development” workload installed.

{
   "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
   "contentVersion": "1.0.0.0",
   "parameters": {
       "appName": {
           "type": "string",
           "metadata": {
               "description": "The name of the function app that you wish to create."
           }
       },
       "sku": {
           "type": "string",
           "allowedValues": [
               "Free",
               "Shared",
               "Basic",
               "Standard"
            ],
           "defaultValue": "Standard",
           "metadata": {
               "description": "The pricing tier for the hosting plan."
           }
       },

       "workerSize": {
           "type": "string",
           "allowedValues": [
               "0",
               "1",
               "2"
           ],
           "defaultValue": "0",
           "metadata": {
               "description": "The instance size of the hosting plan (small, medium, or large)."
           }
       },

       "storageAccountType": {
           "type": "string",
           "defaultValue": "Standard_LRS",
           "allowedValues": [
               "Standard_LRS",
               "Standard_GRS",
               "Standard_ZRS",
               "Premium_LRS"
           ],
           "metadata": {
               "description": "Storage Account type"
           }
       }
   },

   "variables": {
       "functionAppName": "[parameters('appName')]",
       "hostingPlanName": "[parameters('appName')]",
       "storageAccountName": "[concat(uniquestring(resourceGroup().id), 'functions')]"
   },

   "resources": [
       {
           "type": "Microsoft.Storage/storageAccounts",
           "name": "[variables('storageAccountName')]",
           "apiVersion": "2015-06-15",
           "location": "[resourceGroup().location]",
           "properties": {
               "accountType": "[parameters('storageAccountType')]"
           }
       },
       {
           "type": "Microsoft.Web/serverfarms",
           "apiVersion": "2015-04-01",
           "name": "[variables('hostingPlanName')]",
           "location": "[resourceGroup().location]",
           "properties": {
               "name": "[variables('hostingPlanName')]",
               "sku": "[parameters('sku')]",
               "workerSize": "[parameters('workerSize')]",
               "hostingEnvironment": "",
               "numberOfWorkers": 1
           }
       },
       {
           "apiVersion": "2015-04-01",
           "type": "Microsoft.Web/sites",
           "name": "[variables('functionAppName')]",
           "location": "[resourceGroup().location]",
           "kind": "functionapp",
           "properties": {
               "name": "[variables('functionAppName')]",
               "serverFarmId": "[resourceId('Microsoft.Web/serverfarms', variables('hostingPlanName'))]",
               "hostingEnvironment": "",
                     "clientAffinityEnabled": false,
                     "alwaysOn": true
          },
           "dependsOn": [
               "[resourceId('Microsoft.Web/serverfarms', variables('hostingPlanName'))]",
               "[resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName'))]"
           ],
           "resources": [

               {
                   "apiVersion": "2016-03-01",
                   "name": "appsettings",
                   "type": "config",
                   "dependsOn": [
                       "[resourceId('Microsoft.Web/sites', variables('functionAppName'))]",
                       "[resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName'))]"
                   ],

                   "properties": {

                       "AzureWebJobsStorage": "[concat('DefaultEndpointsProtocol=https;AccountName=',variables('storageAccountName'),';AccountKey=',listkeys(resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName')), '2015-05-01-preview').key1,';')]",

                       "AzureWebJobsDashboard": "[concat('DefaultEndpointsProtocol=https;AccountName=',variables('storageAccountName'),';AccountKey=',listkeys(resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName')), '2015-05-01-preview').key1,';')]",

                       "FUNCTIONS_EXTENSION_VERSION": "~1"
                   }
               }
                     ]
       }
   ]
}

Param(
[string]$myResourceGroup,
[string]$mySite)
$webApp = Get-AzureRMWebAppSlot -ResourceGroupName $myResourceGroup -Name $mySite -Slot production
$appSettingList = $webApp.SiteConfig.AppSettings
$setting = @{}
ForEach ($kvp in $appSettingList) {
$setting[$kvp.Name] = $kvp.Value
}
$setting['settingName1'] = <"Settingvalue1">
$setting['settingName2'] = <"Settingvalue2">
$setting['settingName3'] = <"Settingvalue3">
Set-AzureRMWebAppSlot -ResourceGroupName $myResourceGroup -Name $mySite -AppSettings $setting -Slot production
Write-Host “Done!”

Before we get in to the solution of how we can handle multiple token issuer, I’m going to bring up some of the fundamentals of how HTTP request/Response is handler to make a lot of sense out of the proposed solution.

Whenever a HTTP request is made, the call goes through the HTTP message handler and returns the HTTP response. HttpMessageHandler abstract class is the base class for message Handler.

I sniped the above picture form here which clearly explains how Message Handlers can be hooked inside the pipeline. As we notice, we can have multiple such custom message handler which we can chain it together. The first handler receives an HTTP request, does some processing, and gives the request to the next handler. At some point, the response is created and goes back up the chain. This pattern is called a delegating handler.

Our solution to go handle multiple token issuers is entirely based on HTTP MessageHandlers. We inherit DelegateHandler class and access the received token, we then will be able to go validate it based on the different issuers.

This technique is also followed basically to hook in to the request response and compress the message , well that’s outside the discussion that we are having here.

Going back straight to the how we implement the message Handler especially with the introduction of OWIN middleware , it would be better for me to first summarize the steps before I include the code ( obviously without code this would be incomplete )

• Install the required Owin nugets (we also need Microsoft.Owin.Security.Jwt for Jwt token validation )
• Override SendAsunc() method, here is where our complete code of validation will reside.
• Switch the validation process based on the different issuers ( In the sample I have include token that is issued by ACS and AAD )
• Set the claim principal post validation.
• That’s it, we are good to go have a look at the code.
• One more thing we should remember is to register the custom Token handler to the webAPIconfig, this come be done simply by adding the following piece of code in the webAPIConfig

   1: config.MessageHandlers.Add(new TokenValidationHandler());

coming to the TokenVaidationHandler class, this is how it goes;

   1: internal class TokenValidationHandler : DelegatingHandler

   2:   {

   3:       //

   4:       // SendAsync checks that incoming requests have a valid access token, and sets the current user identity using that access token.

   5:       //

   6:       protected async override System.Threading.Tasks.Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)

   7:       {

   8:  

   9:           try

  10:           {

  11:               String headerValue = HttpContext.Current.Request.Headers["Authorization"];

  12:               if (headerValue != null)

  13:               {

  14:                   JwtSecurityTokenHandler jwt_tokenhandler = new JwtSecurityTokenHandler();

  15:                   string[] tokenarray;

  16:                   string token;

  17:                   if (headerValue.Contains("Bearer"))

  18:                   {

  19:                       tokenarray = headerValue.Substring("Bearer ".Length).Split(new char[] { '=' }, 2);

  20:                       token = tokenarray[0];

  21:  

  22:                   }

  23:                   else

  24:                   {

  25:  

  26:                       tokenarray = headerValue.Substring("WRAP ".Length).Split(new char[] { '=' }, 2);

  27:                       token = tokenarray[1].Substring(1, tokenarray[1].Length - 2);

  28:  

  29:  

  30:                   }

  31:  

  32:                   string issuer = "";

  33:                   TokenValidationParameters parms = new System.IdentityModel.Tokens.TokenValidationParameters();

  34:                   string aadInstance = "<aadInstance for login,this should have the domain information as well> ";

  35:                   string tenant = "<mydomain>.onmicrosoft.com";

  36:                   string authority = String.Format(CultureInfo.InvariantCulture, aadInstance, tenant);

  37:                   string metadataAddress = "";

  38:  

  39:  

  40:                   if (token.Contains("Issuer"))

  41:                   {

  42:                       // Check that it starts with 'WRAP'

  43:                       if (!headerValue.StartsWith("WRAP "))

  44:                       {

  45:                           return await Task.Factory.StartNew(() =>

  46:                           {

  47:                               return new HttpResponseMessage(HttpStatusCode.Unauthorized)

  48:                               {

  49:                                   Content = new StringContent("Invalid token")

  50:                               };

  51:                           });

  52:                       }

  53:  

  54:                       string[] nameValuePair = headerValue.Substring("WRAP ".Length).Split(new char[] { '=' }, 2);

  55:  

  56:                       if (nameValuePair.Length != 2 ||

  57:                           nameValuePair[0] != "access_token" ||

  58:                           !nameValuePair[1].StartsWith("\"") ||

  59:                           !nameValuePair[1].EndsWith("\""))

  60:                       {

  61:                           throw new ApplicationException("unauthorized");

  62:                       }

  63:  

  64:                   }

  65:                   else

  66:                   {

  67:  

  68:                       JwtSecurityToken secToken = jwt_tokenhandler.ReadToken(token) as JwtSecurityToken;

  69:                       if (secToken != null)

  70:                       {

  71:                           issuer = secToken.Issuer;

  72:                       }

  73:                       if (issuer == "https://<my-acs>.accesscontrol.windows.net/")

  74:                       {

  75:  

  76:  

  77:                           metadataAddress = "https://<my-acs>.accesscontrol.windows.net/FederationMetadata/2007-06/FederationMetadata.xml";

  78:                           List<X509SecurityToken> signingTokens;

  79:                           GetTenantInformation(metadataAddress, out issuer, out signingTokens);

  80:  

  81:                           parms.ValidIssuer = issuer;

  82:                           parms.CertificateValidator = System.IdentityModel.Selectors.X509CertificateValidator.None;

  83:                           parms.IssuerSigningTokens = signingTokens;

  84:                           parms.ValidAudience = "<valid ACS on-boarded  Audience>";

  85:  

  86:  

  87:  

  88:                       }

  89:                       else

  90:                       {

  91:                           string stsDiscoveryEndpoint = string.Format("{0}/.well-known/openid-configuration", authority);

  92:                           // Get tenant information that's used to validate incoming jwt tokens

  93:                           ConfigurationManager<OpenIdConnectConfiguration> configManager = new ConfigurationManager<OpenIdConnectConfiguration>(stsDiscoveryEndpoint);

  94:                           OpenIdConnectConfiguration config = await configManager.GetConfigurationAsync();

  95:                           List<SecurityToken> signingTokens = config.SigningTokens.ToList();

  96:  

  97:                           parms.ValidIssuer = "https://sts.windows.net/<respective guid>/";

  98:                           parms.CertificateValidator = System.IdentityModel.Selectors.X509CertificateValidator.None;

  99:                           parms.IssuerSigningTokens = signingTokens;

 100:                           parms.ValidAudience = "<valid AAD on-boarded Audience>";

 101:                       }

 102:  

 103:                       SecurityToken validatedToken = new JwtSecurityToken();

 104:  

 105:                       var principal = jwt_tokenhandler.ValidateToken(token, parms, out validatedToken);

 106:                       // Set the ClaimsPrincipal on HttpContext.Current if the app is running in web hosted environment.

 107:                       if (HttpContext.Current != null)

 108:                       {

 109:                           HttpContext.Current.User = principal;

 110:                       }

 111:                       System.Threading.Thread.CurrentPrincipal = principal;

 112:                   }

 113:  

 114:                   

 115:               }

 116:               return await base.SendAsync(request, cancellationToken);

 117:  

 118:           }

 119:           catch (Exception ex)

 120:           {

 121:               HttpResponseMessage response = BuildResponseErrorMessage(HttpStatusCode.Unauthorized);

 122:               return response;

 123:  

 124:           }

 125:  

 126:  

 127:       }

For extracting the tenant issuer information form the signing in token we can use the below code which parses the token against the MetadataAddress (for accessing the certificate) and sets the issuer and the signingTokens.

   1: static void GetTenantInformation(string metadataAddress, out string issuer, out List<X509SecurityToken> signingTokens)

   2:  

   3:       {

   4:  

   5:           signingTokens = new List<X509SecurityToken>();

   6:  

   7:           issuer = null;

   8:  

   9: MetadataSerializer serializer = new MetadataSerializer()

  10:  

  11:           {

  12:  

  13: //CertificateValidationMode = X509CertificateValidationMode.None

  14:  

  15:           };

  16:  

  17: MetadataBase metadata = serializer.ReadMetadata(XmlReader.Create(metadataAddress));

  18:  

  19: EntityDescriptor entityDescriptor = (EntityDescriptor)metadata;

  20:  

  21: // get the issuer name 

  22:  

  23: if (!string.IsNullOrWhiteSpace(entityDescriptor.EntityId.Id))

  24:  

  25:           {

  26:  

  27:               issuer = entityDescriptor.EntityId.Id;

  28:  

  29:           }

  30:  

  31: // get the signing certs 

  32:  

  33:           signingTokens = ReadSigningCertsFromMetadata(entityDescriptor);

  34:  

  35:       }

  36:  

In order for us to read the signing Certs from the entityDesciptor from the above code we use the below method

   1: static List<X509SecurityToken> ReadSigningCertsFromMetadata(EntityDescriptor entityDescriptor)

   2:  

   3:       {

   4:  

   5: List<X509SecurityToken> stsSigningTokens = new List<X509SecurityToken>();

   6:  

   7: SecurityTokenServiceDescriptor stsd = entityDescriptor.RoleDescriptors.OfType<SecurityTokenServiceDescriptor>().First();

   8:  

   9: if (stsd != null && stsd.Keys != null)

  10:  

  11:           {

  12:  

  13: IEnumerable<X509RawDataKeyIdentifierClause> x509DataClauses = stsd.Keys.Where(key => key.KeyInfo != null && (key.Use == KeyType.Signing || key.Use == KeyType.Unspecified)).

  14:  

  15:                                                            Select(key => key.KeyInfo.OfType<X509RawDataKeyIdentifierClause>().First());

  16:  

  17:               stsSigningTokens.AddRange(x509DataClauses.Select(clause => new X509SecurityToken(new X509Certificate2(clause.GetX509RawData()))));

  18:  

  19:           }

  20:  

  21: else

  22:  

  23:           {

  24:  

  25: throw new InvalidOperationException("There is no RoleDescriptor of type SecurityTokenServiceType in the metadata");

  26:  

  27:           }

  28:  

  29: return stsSigningTokens;

  30:  

  31:       }

  32:  

The below code is basically to Build the response Message based on the HTTP statusCode.

   1: private HttpResponseMessage BuildResponseErrorMessage(HttpStatusCode statusCode)

   2:  

   3:       {

   4:  

   5: HttpResponseMessage response = new HttpResponseMessage(statusCode);

   6:  

   7: //

   8:  

   9: // The Scheme should be "Bearer", authorization_uri should point to the tenant url and resource_id should point to the audience.

  10:  

  11: //

  12:  

  13: AuthenticationHeaderValue authenticateHeader = new AuthenticationHeaderValue("Bearer", "unathorized");

  14:  

  15:           response.Headers.WwwAuthenticate.Add(authenticateHeader);

  16:  

  17: return response;

  18:  

  19:       }

  20:  

  21:   }

Connecting the above Token Validator code we should be able to handle multiple token issuers in one Message handler. This might be of some use to those who are trying to handle multiple issuers . Please note that this is not a production ready code and the sole purpose of this is to depict how we can hook in Message handler for token validation. This would need further testing based on the varied scenario before its been used.

Happy Coding!

^Ganesh Shankaran

OWIN components allow you to secure your ASP.NET applications with Windows Azure AD, ADFS and any other identity provider supporting WS-Federation.

Microsoft OWIN components has been explained in great detail in the article and  to those who feel OWIN is new can definitely refer to this.  Btw, to those who want to read about _OWIN specification_ I would recommend reading  https://owin.org/  which has all the wealth of information about OWIN[Open Web Interface for .NET ].

Today to secure our ASP .NET web application that is integrated with Visual Studio we follow a simple initialization logic  with a simple code,  we can read about the flow  here.

The default project today when we create from Visual studio has the following piece of code;

 1: public partial class Startup

 2:     {

 3:         // For more information on configuring authentication, please visit https://go.microsoft.com/fwlink/?LinkId=301864

 4:        public void ConfigureAuth(IAppBuilder app)

 5:         {

 6:             app.UseWindowsAzureActiveDirectoryBearerAuthentication(

 7:                 new WindowsAzureActiveDirectoryBearerAuthenticationOptions

 8:                 {

 9:                     Audience = ConfigurationManager.AppSettings["ida:Audience"],

 10:                      Tenant = ConfigurationManager.AppSettings["ida:Tenant"]

 11:                 });

 12:         }

 13:     }

The audience and the Tenant information is pulled from the configuration and that’s it.. All of it is wired. There are is a lot of configuration that has been reduced and I'm sure people who have been working on the identity integration with the earlier approaches will definitely appreciate the work by  Windows Azure Active Directory team, Kudos to them :).

There was a question that came to me during discuss with my friends on how we can enable browser based sign on having to work seamlessly with the OWIN middleware and I though while I answer his question, can quickly post it  here as well, as this might help others who are looking for the same …

Coming straight to the Point, Microsoft.Owin.Security.WsFederation  Nuget does the magic of how we can have browser based sign on.. For us to have this one to our project, we need to add the below snip of code into ConfigureAuth method of the Startup class ;

 1: app.SetDefaultSignInAsAuthenticationType(WsFederationAuthenticationDefaults.AuthenticationType);

 2:            app.UseCookieAuthentication(

 3:                new CookieAuthenticationOptions

 4:                {

 5:                    AuthenticationType =

 6:                       WsFederationAuthenticationDefaults.AuthenticationType

 7:                });

 8:            app.UseWsFederationAuthentication(

 9:                new WsFederationAuthenticationOptions

 10:                {

 11:                     MetadataAddress = "<Federated Metadata>",

 12:                    Wtrealm = "<your realm>"

 13:                });

    This link explains in details of how we can use WsFederationAuthenicationOptions. In short below are the values that we need to set it up to have the passive federation browser based login to work.

Wtrealm:  This is the identifier of your application, as assigned when you configured your app in your authenticating authority (in the Windows Azure portal for Windows Azure AD, in the management console for ADFS).
 
MetadataAddress : This value represents the Windows Azure AD tenant (or ADFS instance) you want to use for authenticating your users. If you are writing line of business apps for your own company, this line will likely never change.

If we are wondering about the CookieAuthentication that is added in the above snip of code, it’s the OWIN Cookie Authentication middleware component (we can be downloaded from Microsoft.Owin.Security.Cookie  nuget) which not only performs the operation of issuing the cookie and validating the cookie on the subsequent request but also the converts  the response and redirect to the login page upon failure. The best part of this middle ware is that it is claim-aware ..

Hope this helps someone who is trying to get the OWIN middleware for enabling browser based sign-on using WsFederation… Happy coding!

Ganesh Shankaran

Software Development Engineer

As load increases on a web application, we will often take a series of steps to help improve site performance. Initially, we might put our web application behind a load balancer and add more web instances to better serve the incoming requests. With Windows Azure Web Sites and Cloud Services, adding more instances is as easy a turning a knob to the number of desired instances. The Windows Azure load balancer automatically adjusts to handle the additional instances.

Our next step might be to add more, or perhaps even larger, application servers to our middle / business logic tier. But as traffic continues to increase, the load on our database typically starts to increase as well. Soon the database may become the performance bottleneck. The database responses can get slower and slower. As pressure increases, the database may begin to throttle or connections may timeout. The end result for our users – errors and a poor experience.

Different Azure Cache Offerings from Microsoft and there supportability

Migration from Azure Shared Caching or AppFabric Caching

Usage Guidelines For a Co-located In-role Cache (ref: link )

 1.    Use diagnostics data to determine the correct percentage of memory to allocate for caching. Include performance counter data on memory and CPU for the virtual machine instances that are running under expected load. The amount of memory available per running role instance is determined by the virtual machine size (VM size) and the memory used by the operating system and other application services running on the role. To understand how to correctly set the Cache Size (%), see Capacity Planning Considerations for In-Role Cache (Azure Cache).

 2.    A co-located topology is not recommended in the following cases:
•   Cache sizes greater than 1.5 GB.   
•   Cache clusters with more than 400 caching transactions per second per role instance   
•   Cache clusters with more than 1.2 MB of bandwidth used for caching operations per second per role instance.

Usage Guidelines for a Dedicated Caching Topology (ref: link )

 The following guidelines apply to the dedicated In-Role Cache topology: 

•    In general, a dedicated InRole Cache role provides the best performance, because it does not share the role's virtual machine with any other application services. It also provides the most flexibility, because you can scale the In-Role Cache role independently. For these reasons, using a dedicated topology is the recommended caching architecture. However, there are situations where a co-located topology works well. For more information, see Guidelines for a Co-located Caching Topology. 
•   The amount of memory available per running role instance is determined by the virtual machine size (VM size) and the memory used by the operating system and other application services running on the role. To understand how to correctly set the Cache Size (%), see Capacity Planning Considerations for In-Role Cache (Azure Cache). 
•    Do not use a dedicated In-Role Cache role for other code or services.  
•   Only one cache cluster is supported for each cloud service.  

What is the recommendation of Microsoft in choosing between the available options? (ref: link )

There are always benefits of one over the other when it comes to selection of Caching methods, for example Azure managed service gives a capacity of 150 GB cache size when compared to Redis cache which is 26 GB.  That being said, Azure Redis Cache gives customers the ability to use a secure, dedicated Redis cache, managed by Microsoft. With this offer, you get to leverage the rich feature set and ecosystem provided by Redis, and reliable hosting and monitoring from Microsoft.

On May 12, 2014, Microsoft announced the availability of the Azure Redis Cache (Preview). Microsoft recommend all new developments use the Azure Redis Cache.  For more information please refer this link

Other features of Azure  Redis Cache include : 
•   Redis is an advanced key-value store, where keys can contain data structures such as strings, hashes, lists, sets and sorted sets. Redis supports a set of atomic operations on these data types. 
•   Transactions, Pub/Sub, Lua scripting, Keys with a limited time-to-live, and configuration settings to make Redis behave like a cache. 
•   Azure Redis Cache (Preview) leverages Redis authentication and also supports SSL connections to Redis.

Tutorial and Guide for Cache: https://azure.microsoft.com/en-us/documentation/services/cache/ 

Sample Demo’s

Now, that’s some facts and basic information one must know while working on Azure Caching. This brings all the information from different msdn articles into one.

For those who have already started using Azure Cache I’m sure you would have seen(I have come across this pretty often)  sometimes that the DataCacheFactory gets into a bad state where many requests will fail even though the server is fine. My next post will have details on handling DataCacheFactory by clearing DataCachefactory connectionPool.

I hope this will help developers who start there Azure Cache journey. 

Ganesh Shankaran

Software Development Engineer

   1: Public Shared Function Read(ByVal path As String) As DataEnvironmentConfigurationElement

   2:     Dim section As DataEnvironmentConfigurationSection = DirectCast(DataEnvironment.GetNonDefaultConfigurationFile(path).GetSection("dataEnvironmentConfiguration"), DataEnvironmentConfigurationSection)

   3:     Return DataEnvironment.GetCurrentEnvironment(section)

   4: End Function

Now, let’s look in to two such scenarios where accessing custom configuration files might lead us to System.InvalidcastException

Scenario 1: We have a configuration file that tries to access the Section information in the code using GetSection but results in the type cast error while it was accessed.
When the type information was checked, everything looked perfect. And the config file being XML format we might think that we can follow any order of elements that are being used in the config file, The faulting config file looked as shown below, 

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

   2: <configuration>

   3: <appSettings>

   4:     <add key="Key1" value="value1"/>

   5:   </appSettings>

   6: <configSections>

   7:     <section name="dataEnvironmentConfiguration" type="CustomConfigurationSample.DataEnvironmentConfigurationSection, CustomConfigurationSample"/>

   8:   </configSections>

   9:   

  10: <dataEnvironmentConfiguration currentDataEnvironment="UT">

  11:     <dataEnvironments>

  12:       <add name="name1" userName="user1" password="pasword1" collection="new value" />

  13:       <add name="name2" userName="user2" password="password2s" collection="new value21" />

  14:       </dataEnvironments>

  15:   </dataEnvironmentConfiguration>

  16: </configuration>

When we make use of this config file, we will get a System.InvalidcastException.
Resolution
There is one catch in the above snip which is the root cause of the issue. While DOM (Data Object model) tries to parse the config section, it looks for the type information mentioned in the ConfigSections element, and there is a specific requirement that, this ConfigSections appears just below the Configuration element. CLR XML DOM parser assumes that the configSections element is the first element in the configuration file.

Here is how it should appear,

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

   2: <configuration>

   3: <configSections>

   4:     <section name="dataEnvironmentConfiguration" type="CustomConfigurationSample.DataEnvironmentConfigurationSection, CustomConfigurationSample"/>

   5:   </configSections>

   6:   <appSettings>

   7:     <add key="Key1" value="value1"/>

   8:   </appSettings>

   9: <dataEnvironmentConfiguration currentDataEnvironment="UT">

  10:     <dataEnvironments>

  11:       <add name="name1" userName="user1" password="pasword1" collection="new value" />

  12:       <add name="name2" userName="user2" password="password2s" collection="new value21" />

  13:       </dataEnvironments>

  14:   </dataEnvironmentConfiguration>

  15: </configuration>

So, when  we the make the necessary changes in the custom config file, the issue gets fixed and we are good to use the config file. You could get more information about this in the MSDN article, https://msdn.microsoft.com/en-us/library/ms228256.aspx

Well, that was simple. But when we miss the basic element order in the config file it becomes a little difficult to locate the fault.
Let’s look at the second  scenario which also throws InvalidtypeCastException, but under different circumstances,

Scenario 2: Here is another scenario where the application throws InvalidtypeCastException and this time it’s while accessing <Sectiongroups>. Let’s look in to the sample that leads to  the exception,
We try to get the section detail of the custom config file, Read( ) function (with the path where we have the custom config as the parameter) does the work for us.

   1: Public Shared Function Read(ByVal path As String) As DataAccessDefinition

   2: Dim c = GetNonDefaultConfigurationFile(path)

   3: Return DirectCast(c.GetSection("DataAccessDefinition/DataAccess1"), DataAccessDefinition) 

   4: End Function

We get the non-custom config file path by using OpenMappedExeConfiguration of the config file,

   1: Private Shared Function GetNonDefaultConfigurationFile(ByVal path As String) As Configuration

   2: Dim ecfm = New ExeConfigurationFileMap()

   3: ecfm.ExeConfigFilename = path

   4: Return ConfigurationManager.OpenMappedExeConfiguration(ecfm, ConfigurationUserLevel.None)

   5: End Function

Handler is implemented as shown below, 

   1: Public Class DataAccessConfigHandler

   2:     Implements IConfigurationSectionHandler

   3:  

   4:     Public Function Create(ByVal parent As Object, ByVal configContext As Object, ByVal section As System.Xml.XmlNode) As Object Implements System.Configuration.IConfigurationSectionHandler.Create

   5:         Dim dataAccess = New DataAccessDefinition

   6:         dataAccess.ConnectionName = section.SelectSingleNode("connectionName").InnerText

   7:         dataAccess.CommandText = section.SelectSingleNode("commandText").InnerText

   8:         dataAccess.CommandType = section.SelectSingleNode("commandType").InnerText

   9:         Return dataAccess

  10:     End Function

  11: End Class

While this handler works fine for a default config file, it results in a System.InvalidCastException when we make use of the custom config file.
Resolution:
As IconfigurationSectionHandler is deprecated [ref: https://msdn.microsoft.com/en-us/library/system.configuration.iconfigurationsectionhandler.aspx], the best way to access the Section group is to follow the following method described below,
The configuration section defines which type is used to de-serialize the XML file, and if you try to cast to an incompatible type you will (as expected) get a casting error.
I was able to get it working by using the suggested method of deriving from ConfigurationSection as IconfigurationSectionHandler is deprecated.
Below is the implementation detail;

   1: Public Class DataAccessConfigHandler

   2:     Inherits ConfigurationSection

   3:  

   4:     Public dataAccess As DataAccessDefinition

   5:  

   6:     Protected Overrides Sub DeserializeSection(ByVal reader As System.Xml.XmlReader)

   7: dataAccess = New DataAccessDefinition

   8:  

   9: While reader.Read()

  10: If reader.NodeType <> XmlNodeType.Element Then

  11:    Continue While

  12: End If

  13: Select Case reader.Name

  14: Case "connectionName"

  15: dataAccess.ConnectionName = reader.ReadElementContentAsString()

  16: Case "commandText"

  17: dataAccess.CommandText = reader.ReadElementContentAsString()

  18: Case "commandType"

  19: dataAccess.CommandType = reader.ReadElementContentAsString()

  20: End Select

  21: End While

  22: End Sub

  23: End Class

Usage example:

   1: Dim h = DirectCast(ConfigurationManager.GetSection("DataAccessDefinition/DataAccess1"), DataAccessConfigHandler)

   2:         Return h.dataAccess

   1: <sectionGroup name="DataAccessDefinition">

   2: <section name="DataAccess1" type="CustomConfigurationSample.DataAccessConfigHandler,CustomConfigurationSample"/>

   3: </sectionGroup>

Please refer to the MSDN article for more details,https://msdn.microsoft.com/en-us/library/2tw134k3.aspx 

 Now this works absolutely fine. Hope this helps while working with configuration files.

Ganesh Shankaran

Software Development Engineer