Release Notes for AppFabric 1.1
This document provides a list of highlighted changes and known issues with Microsoft AppFabric 1.1 for Windows Server (AppFabric 1.1).
Highlighted Changes with this Release
The following list contains some of the more significant differences from the previous release of AppFabric 1.0. This does not include new features, which are summarized in the What's New in AppFabric 1.1? information.
Installation path change
Microsoft AppFabric 1.1 for Windows Server now installs to a default path of .\Program Files\AppFabric 1.1 for Windows Server. You also have the option to customize the installation path.
AppFabric Windows PowerShell modules are no longer system modules
In the previous release, Windows PowerShell modules were system modules. One result was that they were loaded automatically when you ran Windows PowerShell Modules from Administrator Tools. This is no longer the case. You now must directly load the modules using the Import-Module command. The modules are located in the PowershellModules directory in the installation path. For AppFabric Caching, you have the alternative option to launch the Caching Administration Windows PowerShell link from the start menu.
Caching assemblies are no longer registered in the Global Assembly Cache
In the previous release, the AppFabric Caching assemblies were registered in the Global Assembly Cache (GAC). With the release of AppFabric 1.1, the caching assemblies are located in the installation directory (defaults to .\Program Files\AppFabric 1.1 for Windows Server). When deploying cache client applications, you can deploy these assemblies locally with your application.
Note that for automated installations, you have the option of using the /gac option to register the assemblies in the GAC. If this is done, you should not also develop caching solutions for Windows Azure on the same machine.
Known Issues with Setup and Configuration
Some hosting and persistence settings must be reconfigured after upgrade
If you upgrade from Windows Server AppFabric 1.0 to AppFabric 1.1, there are some hosting and persistence settings that must be reconfigured. These settings apply if you had previously installed the Hosting Services feature. During the upgrade, any custom service accounts for Monitoring and Persistence gets changed back to LocalService. In addition, the persistence store must be reconfigured to prevent failures with instance tracking. You can reconfigure these settings using the Configuration Wizard. Additionally, the .NET 4.0 web.config file is backed up before installation and restored after. Because of this, you should not make any changes to the configuration or those changes could be lost.
Upgrade from AppFabric 1.1 CTP to AppFabric 1.1 RTW is not supported
If you previously installed the CTP of AppFabric 1.1, you must uninstall that version before installing the current release of AppFabric 1.1. An upgrade path is not available.
Workgroup identities must be reconfigured after upgrading the Caching Service
The AppFabric Caching Service can be run as a workgroup account. However, after upgrading AppFabric 1.0 to AppFabric 1.1, the AppFabric Caching account is reset to NETWORK SERVICE. After upgrading, you must use Windows PowerShell configuration commands or the Configuration Wizard to reset the account back to the workgroup account.
Downgrade path from AppFabric 1.1 to Windows Server AppFabric 1.0 is not supported
After upgrading Windows Server AppFabric 1.0 to AppFabric 1.1, it is not possible to downgrade back to Windows Server AppFabric 1.0. The setup technologies used with each release are incompatible. The only solution is to uninstall AppFabric 1.1 and reinstall and reconfigure the Windows Server AppFabric 1.0 release. Record all configuration settings before uninstalling.
.NET Framework 3.5 required on Windows Server 2008 and Windows Vista for the Caching Service
Before installing the AppFabric Caching Service on Windows Server 2008 or Windows Vista, you must first manually install the .NET Framework 3.5. If this is not installed, the following error appears during setup: "An error occurred while downloading the file http://saturn.installshield.com/is/prerequisites/microsoft .net framework 3.5 sp1.prq".
Automated installation requires manual permission changes for the AppFabric Caching Service account
If you use automated installation to install the AppFabric Caching Service, you must manually grant the AppFabric Caching Service account the "Logon as service" permission. This only applies to service accounts which are not NETWORK SERVICE. You must do this before performing the automated installation.
Windows PowerShell is required for Cache Client feature on Windows Vista
On Windows Vista, setup fails to install the Cache Client feature if you have not installed Windows PowerShell 2.0. You can install Windows PowerShell from the following link: http://go.microsoft.com/fwlink/?LinkId=192992
Prerequisites for executing setup from a network share
When Code Access Security (CAS) settings disallow the execution of code from intranet shares, AppFabric setup will simply crash because it will not be able to execute any code, including the code that displays error messages. For that reason, platform validation logic cannot be used to enforce the proper CAS settings. The solution for this issue is to allow the execution of code from intranet shares. The user will have to ensure that the CAS policy includes the local intranet permissions and setup.exe executes in full trust, as shown in the following examples:
The following command adds the MyOther.exe assembly to the full trust list for the computer policy:
caspol -machine -addfulltrust MyOther.exe
The following command adds a child code group that gives the share \\netserver\netshare local intranet permissions:
caspol -machine -addgroup 1. -url \\netserver\netshare\* LocalIntranet
For more information on configuring the .NET Framework, see .NET Framework Configuration Tool (Mscorcfg.msc) (http://go.microsoft.com/fwlink/?LinkId=181958).
For more information on configuring CAS, see Code Access Security Policy Tool (Caspol.exe) (http://go.microsoft.com/fwlink/?LinkId=181960).
After AppFabric upgrade and computer reboot, some services have to be restarted
The AppFabric Workflow Management service and the Event Collection service fail to restart immediately after the upgrade. Restart these services manually in the Service Control Manager after upgrading AppFabric.
After AppFabric upgrade, the Caching Service fails to start if the cache cluster ran as a workgroup identity
When an AppFabric 1.0 cache cluster uses a workgroup identity, the credentials for that workgroup are not persisted during an upgrade to AppFabric 1.1. As a result, the Caching Service cannot start until the credentials have been reconfigured. This can be done using the AppFabric Configuration Wizard.
Uninstalling previous versions of AppFabric
To uninstall AppFabric, click Start, click All Programs, click AppFabric for Windows Server, click Add or remove Features, and then run through the AppFabric setup wizard.
Uninstalling AppFabric can cause applications configured to use AppFabric features to be non-functional
When you use Windows Server AppFabric, you may configure a server, site, or application to use AppFabric-specific features. This can cause your applications to be non-functional after you uninstall Windows Server AppFabric. As a result, after you uninstall AppFabric, you may need to clean your application configuration. This can involve locating and cleaning the applicationHost.config file and the Web.config files for each scope.
You can also use the AppFabric Uninstall Cleanup Utility that is available on the AppFabric download center for an automated solution.
For more information, see Clean Application and Clustering Configuration After Uninstalling AppFabric (http://go.microsoft.com/fwlink/?LinkId=190412).
Uninstall AppFabric before upgrading Vista or Windows Server 2008 to Windows 7 or Windows Server 2008 R2
If AppFabric is installed on Vista or Windows 2008, and the operating system is to be upgraded to Windows 7 or Windows Server 2008 R2, AppFabric needs to be uninstalled before the upgrade and reinstalled after completing the upgrade.
Before upgrading the OS
Record which AppFabric components are installed.
Record any changes to settings made to the Windows Server AppFabric installation. For example, note changes to the following:
membership of AS_Administrators and AS_Observers Windows groups
AppFabric Windows services like Event Collection Service, Workflow Management Service, and AppFabric Caching Service
- configuration file
After recording the changes, uninstall AppFabric, then upgrade the OS, and then reinstall AppFabric.
Reapply settings to the new AppFabric install on the upgraded OS.
If you perform an operating system upgrade without uninstalling AppFabric beforehand, then after the upgrade you need to uninstall AppFabric, and then remove the following registry entry:
Encrypted configuration data can cause AppFabric configuration to fail
AppFabric Hosting Services cmdlets can read encrypted configuration sections, but cannot write to them. This can result in AppFabric configuration failing if during the configuration process (either through the use of the AppFabric configuration wizard or directly through the use of a PowerShell cmdlet), a cmdlet attempts to write to a section in the Web.config file whose data is entered in an <EncryptedData> section. You will see the following error: “Configuration section encryption is not supported.” (error code 555). This indicates that the configuration section that AppFabric setup was attempting to write to has been encrypted. To resolve this issue, unencrypt the section and run setup again.
Use domain accounts to configure AppFabric on a domain controller
The AppFabric Configuration Wizard can fail on a domain controller if you use non-domain accounts. Per-service accounts for the Event Collection service and Workflow Management service cannot be added to the AS_Administrators group or the AS_Observers group on a domain controller. The reason is that NT Service SIDs are longer than those supported by the Active Directory. When you attempt to initialize a store, this can result in an error that a Windows security principal is invalid.
To resolve this issue, use domain accounts to configure AppFabric on a domain controller. To do so, collocate the Active Directory Directory Service role with the Application Server role as follows:
Run the Event Collection service and Workflow Management service under domain accounts, rather than per-service accounts.
Add the domain accounts used for the services to the group (AS_*) that will be used to connect to the associated monitoring or persistence database.
Add the Event Collection service account to the perflog user group manually. This enables the Event Collection service to be able to read from or write to the Event Tracing for Windows (ETW) session.
Whenever you pass any Windows principal to any AppFabric Hosting Services cmdlet, such as Initialize-ASMonitoringSqlDatabase or Initialize-ASPersistenceSqlDatabase, use an account in either built-in users or domain accounts. Do not use an account in local user/groups.
Promoting a computer to a Domain Controller requires reconfiguring AppFabric
If you promote a workgroup or standalone computer that has AppFabric installed and configured on it to a domain controller, the AppFabric configuration will become invalid, and you will have to rerun the configuration wizard, using different security identities. Do so as follows:
In the Service Control Manager, set the service identity for the Cache Service to "NT Authority\Network Service".
Re-run the configuration wizard, re-entering the configuration information and specifying domain users or groups for the security identities.
Add the service accounts to the domain groups (for example, AS_Administrators and AS_Observers) that will be used to connect to the databases.
The\inetpub\wwwroot folder must be manually created when IIS is disabled
If you install the IIS Manager with IIS disabled, you must create the \inetpub\wwwroot folder after the AppFabric Installation Wizard is run. Otherwise, the default Web site will be mapped to a non-existing folder. This is true for the Standard, Enterprise, Datacenter, and Foundations editions. For AppFabric installations on these editions, create this folder manually.
Support for server-level configuration of 32-bit applications on a 64-bit Operating System is limited
There are limitations in the ability to edit the configuration of a 32-bit application on a server that uses a 64-bit operating system. On a 64-bit server, if you use the AppFabric IIS Manager Extensions and Windows PowerShell cmdlets for AppFabric to make default configuration settings at the server (root) level for a 32-bit application, the runtime will not use those configuration settings.
The IIS Manager Extensions and AppFabric cmdlets make these configuration settings in the machine.config and web.config files in the <drive>:\Windows\Microsoft.NET\Framework64\<build>\config folder. These settings are not made in the Framework folder that is used for 32-bit applications, and as a result, the runtime will not use the configuration settings when running the application. On a 64-bit server, IIS Manager can only be launched in 64-bit mode and Windows PowerShell cmdlets for AppFabric can only be used from a 64-bit process. The runtime does not have an issue, because it determines whether to use 32-bit or 64-bit configuration settings based upon whether the application pool is 32-bit or 64-bit. The following server-level default configuration settings are affected by this issue:
Event Collection service
Workflow Management service
AppFabric default connection string
endToEndTracing configuration under <Diagnostics> (related to the monitoring level).
You can avoid this issue by making default settings for a 32-bit application on a 64-bit server at the site or application level, not the server level. This issue does not occur with default configuration settings at the site or application level. You can also make default settings at the server level manually in the machine.config and web.config files, although you can encounter issues when you do so because of the presence of configuration settings in both the Framework64 and Framework folders.
Windows PowerShell cmdlets for AppFabric are not supported on WOW64
On a server that is running 64-bit Windows, Windows PowerShell cmdlets for AppFabric can only be executed in a 64-bit process. If you must run an AppFabric cmdlet in a 32-bit process, you can write your AppFabric cmdlet script against 64-bit Windows PowerShell, and for the portion of the script that must be run from a 32-bit process, launch a 32-bit process from the 64-bit script. You can also launch a 64-bit process from a 32-bit process, and then launch your 64-bit script from that 64-bit process.
AppFabric configuration and enumeration functionality is limited in a shared-content scenario
This occurs when an application that is hosted on an IIS server has a physical directory on a remote File server, and the IIS logon user does not have access to the physical directory. In this case, the logon user will not be able to see all the services and their configuration data. This limitation applies to both the AppFabric IIS Manager extensions and the AppFabric cmdlets.
This will occur if the following two settings are made. First, in the Advanced Settings dialog box for an application hosted on the IIS server, you set the physical path for the application to a physical directory on a File server, and you set the credentials to a user other than the logged-on user. Second, in the Security tab of the Properties dialog box for the folder on the File server, you only grant access permissions to the user other than the logged-on user, but not to the logged-on user.
AppFabric installation will fail if the serviceAutoStartProviders element is missing from the %systemroot%\system32\inetsrv\config\ApplicationHost.config file.
You can resolve this issue by adding the serviceAutoStartProviders element to the system.applicationHost element of the ApplicationHost.config file.
Setup.exe and Microsoft.ApplicationServer.Configuration.exe require administrator privileges
Two executables require running with adminitrator privileges.
Setup.exe: Writes to the file system, registry entries, and modifies system configuration settings.
Microsoft.ApplicationServer.Configuration.exe: Performs registry operations and invokes PowerShell commands to configure product features.
Microsoft CCR and DSS Runtime 2008 R3.MSI is automatically installed with setup
The Microsoft CCR and DSS Runtime 2008 R3.MSI package is automatically installed as a part of the AppFabric 1.1 setup. This is a separate product that supports the features of AppFabric 1.1. Note that it is missing an upgrade table and it does not get automatically uninstalled if you uninstall AppFabric 1.1.
Known Issues with Tooling Features
AppFabric 1.1 is not supported in safe mode
AppFabric 1.1 is not supported in safe mode. When running in safe mode, the AppFabric 1.1 services do not automatically start. Any attempt to start these services manually will fail with an error message similar to the following: "This Service cannot be started in Safe Mode."
PowerShell and Dashboard do not show instances that have not persisted yet
Workflow instances that have not persisted yet are not returned by the Get-ASAppServiceInstance cmdlet or displayed on the AppFabric dashboard.
Issues when using custom WCF bindings and behaviors
If your services use custom behaviors or bindings, you will not be able to configure these settings in AppFabric directly. This is because AppFabric uses MWA configuration API (native to IIS) to read/write configuration. If you want to be able to configure them, you will need to convert these custom element sections to MWA-compatible schemas and place that schema in %SystemRoot%\System32\inetsrv\config\schema. MWA will automatically pick up this schema and parse the custom section in configuration correctly. You can then edit these configuration sections using IIS’s native configuration editor (IIS Configuration Editor) that ships inside of IIS Manager, not the AppFabric Configuration Editor.
Applications from both .NET 2 Framework and .NET 4 Framework are not recommended in the same website
AppFabric tools provide first-class support for configuring .NET 4 framework applications, and do not explicitly provide tool support for .NET 2 framework applications. Therefore, mixing .NET 2 and .NET 4 applications within the same website may create issues such as mismatched configurations which could break your applications. We recommend that you not mix .NET 2 and .NET 4 applications and instead put them in different websites so you can manage them more successfully in AppFabric.
Starting and stopping of the default application must be done at the application level
Starting and stopping of applications is not enabled at the site level.
Workflow services require the NET.PIPE Protocol
The Workflow Management Service (WMS) requires the net.pipe protocol to control workflow instances. To use net.pipe, you must add the net.pipe binding on the web site hosting workflow services, and enable the net.pipe protocol on the application hosting workflow services. Do not change these settings if any instances of the service have persisted, as the wrong binding may be stored in the database.
To add the net.pipe binding to a website
Open IIS Manager and select the website.
In the Actions pane, click Edit Bindings.
Select net.pipe, and set the Binding Information to an asterisk (*).
To enable the net.pipe protocol on an application
Open IIS Manager and select the application.
In the Actions pane, click Advanced Settings.
In the Enabled Protocols box, update the value to include
net.pipe. Separate protocols with a comma. For example, the value should be http,net.pipe.
Net.pipe warning missing for site level in IIS Manager
When you configure applications or services at the site level in IIS Manager, a warning should be displayed when the Workflow Persistence tab or the Workflow Host Management tab is selected in order to remind the user to enable net.pipe on the individual applications. The warning would indicate that persistence or the instance control may not function correctly if net.pipe is not enabled for the individual applications at the site level. This warning is displayed correctly at the server level; however, the warning is missing at the site level.
Enabling Auto-Start for an application requires resetting IIS
If you launch IIS Manager, and you set AutoStart to Enabled for an application, you will see an error indicating that the configuration .xml file is not well-formed. This error will go away if you execute the iisreset command at a command prompt.
Known Issues with Caching Features
Caching service firewall considerations
After you uninstall the caching features from a distributed cache server, the AppFabric setup program will disable the AppFabric Server: AppFabric Caching Service firewall rule group, removing it as an exception. Upon installation, the setup program creates this group and adds rules to it. However, if you enable the Remote Service Management firewall rule group upon setup, the setup program will not disable it upon uninstallation. You will have to disable Remote Service Management manually on each node of the cluster, if you choose to do so. After any of the caching features of AppFabric has been uninstalled, review your firewall configuration.
Registering a remote cache host from a configured cache host fails
When using the Register-CacheHost command to configure a remote cache host, you may get the following error even if those ports are available on the remote machine:
Register-CacheHost : ErrorCode<PortAlreadyInUseError>:SubStatus<ES0001>:TCP port 22233 is already in use. This can happen when you run this command from a cache host that is already configured to use the same ports. The solution is to run this command from a machine that is not already configured as a cache host. For example, you could use a machine that only has the Caching Administration feature installed.
Windows PowerShell Modules shortcut will not load the Distributed Cache module when only Cache Administration is installed and .NET Framework 4 is not installed
The Windows PowerShell Modules shortcut in the Start menu normally loads the Distributed Cache module. However, it will not do so when .NET Framework 4 is not installed and only Cache Administration is installed. You can load the module by doing the following:
Open the Windows PowerShell Modules shortcut in the Start menu.
Load the Distributed Cache module by using the Import-Module cmdlet.
Run Cache Administration PowerShell cmdlets.
“Total Write Operations” performance counter differences between cache and host levels
The performance counter “Total Write Operations” can be added for both the “AppFabric Caching:Cache” and the “AppFabric Caching:Host” counter categories. When the default cache is used by client applications, the total number of writes on the host may differ from the total number of writes across all caches on the host. This happens due to internal creation of regions in the default cache.
Configuring the network share (XML) cache cluster configuration requires the Administrator membership on the target machine
When configuring the cache cluster to use a network share to store cache cluster configuration settings, the user performing the configuration must be an Administrator on the machine with the network share.
Network share (XML) cache cluster configuration requires Full Control or Co-owner permissions
When using a network share to manage the cache cluster configuration settings, you must have Full Control or Co-owner permissions on the share. If you are using the net share command, specify "full" as in the following example:
net share sharename /grant:user,FULL
Case sensitivity of region names, key names, and cache names
Region and key names are always case-sensitive. The case-sensitivity of cache names is dependent on how the configuration information is stored.
XML - The cache name is case-sensitive.
SQL Server - The cache name is case-sensitive if the SQL Server database uses a case-sensitive collation. The cache name is case-insensitive if the SQL Server database uses a case-insensitive collation.
Starting the AppFabric Caching Service prior to service configuration
When the AppFabric Caching Service is started manually prior to configuration, it creates a single-host cache cluster with “localhost” as the only cache host. Instead of relying on this default behavior, you should always use the AppFabric Configuration Wizard to configure AppFabric Caching Services prior to starting them from Windows PowerShell with the
Creating new caches on a throttled server can cause the server to crash
When a server is in a throttled state, available memory is less than 4% or available memory on the system goes below the paged out memory for the process. In this state, creating new AppFabric caches can cause the server to fail. In most cases, proper capacity planning should avoid this scenario for a server.
Changes to the AppFabric Caching Service identity requires manual permission changes
If you change the service account for the AppFabric Caching Service using the Services administrative tool, you must also make several permission changes to enable the service to run correctly. This can be done in one of two ways.
Use Windows PowerShell commands to unregister and remove the cache host and then re-add and re-register the same cache host. This can be done with the following commands: Unregister-CacheHost, Remove-CacheHost, Register-CacheHost, and Add-CacheHost. For details, see Automated Installation and Configuration (AppFabric 1.1 Caching).
Or, add read-only permissions for the service account on the AppFabric Caching Service configuration file, DistributedCacheService.exe.config, which is located in the ".\Program Files\AppFabric 1.1 for Windows Server" directory. If the cluster configuration settings are stored in a shared network folder, then you must also give the new account read permissions on that share. If the cluster configuration settings use SQL Server, then you must give the account the public server role, the db_datareader database role, the db_datawriter database role, and the Execute database permission.
Character limitations for cache server names
Cache server names are limited to the letters 'a' - 'Z', the numbers 0 - 9, and hyphens. Using other characters in cache server names can result in the following error when registering the cache host with the
Register-CacheHost command: "Invalid URI: The hostname could not be parsed".
Unable to install the AppFabric Caching Service on a domain controller
The caching features of AppFabric do not install correctly on a domain controller. Attempting to install or configure the AppFabric Caching Service on a domain controller is not supported.