======================================== Release Information Microsoft Project Code Named "Velocity" for Community Technology Preview 2 (October 2008) ======================================== This file contains late-breaking or other important information that supplements the product documentation. Read this file completely before installing this software. This file includes the following sections: *"Velocity" Introduction *Basic Installation Deliverables *"Velocity" Terminology *Installation Prerequisites *Basic Installation Steps *Other References *Known Issues *Crash Dump Diagnostics ------------------------------- "Velocity" Introduction ------------------------------- Microsoft project code named "Velocity" provides a highly scalable in-memory application cache for all kinds of data. By using cache, application performance can improve significantly by avoiding unnecessary calls to the data source. Distributed cache enables your application to match increasing demand with increasing throughput using a cache cluster that manages the complexities of load balancing automatically. When you use "Velocity," you can retrieve data by using keys or other identifiers, named "tags." "Velocity" supports optimistic and pessimistic concurrency models, high availability, and a variety of cache configurations. “Velocity” includes an ASP.NET session provider object enabling storage of ASP.NET session objects in the distributed cache without having to write to databases, which increases the performance and scalability of ASP.NET applications. For community technology preview 2 (CTP2), Microsoft project code named "Velocity" offers several new enhancements that include a high availability feature, performance improvements, PowerShell integration, and new configuration storage options. There is also a new 64-bit version of "Velocity" specifically customized for x64-based computers. ------------------------------- Basic Installation Deliverables ------------------------------- The "Velocity" installation program installs the following on your designated cache server or development workstation: * The “Velocity” cache host service, running as Microsoft project code named "Velocity." * The PowerShell-based cache administration command-line tool. * The “Velocity” API DLL files used for developing cache-enabled applications. * The “Velocity” documentation help (.chm) file. ---------------------------- “Velocity” Terminology ---------------------------- Cluster configuration storage location: There are three options available for storing cluster configuration settings: in XML, in a SQL Server Compact data file, or in a SQL Server 2005 or later database. You can choose the option that best meets the needs of your application and infrastructure. Cache Server and Cache Host: "Velocity" runs on one or more servers in the form of a Windows service, called the cache host service. Each server that runs the cache host service is referred to as a cache server, but you can install it on servers that perform other functions too, such as a Web or application server. In customer technology preview 2 (CTP2), each cache server has a single instance of the cache host service. Cache Cluster: The cache cluster is a collection of one or more instances of the cache host service working together to store and distribute data. ------------------------------------------------------------ Prerequisites: Preparing for the Cache Host Service Installation ------------------------------------------------------------ 1. Install .NET Framework version 3.5. 2. Install PowerShell version 1.0. 3. Prepare the cluster configuration storage location corresponding to the option you choose for storing your cluster configuration settings. *For the XML or SQL Server Compact-based option: Create a shared folder for the cluster configuration share. All cache hosts in the cluster must be granted read and write permissions to the folder's sharing and security settings. Assign permissions to the domain computer accounts of the corresponding cache servers and avoid use of the Everyone identity. *For the SQL Server-based option: Create a database for the cluster configuration settings. The installation program installs tables for managing the settings. Grant the cache servers logon permissions to the database server, and read and write permissions to the database. Because connection strings are stored in clear text in the cache host configuration files, it is recommended to use integrated security for securing the database. The security identity running the installation program needs logon permissions to the database server and db_owner permissions to the database. ------------------------------------------ Basic Installation Steps: Installing the Cache Host Service ------------------------------------------ 1. Click Next at the Welcome screen. 2. Upon acceptance of the EULA, click "I accept...", and then Next. 3. Click Install after choosing the installation location. 4. Complete the Cache Host Configuration Form: a. Provider Dropdown: Choose the format in which you would like to store your cluster configuration settings. For more information, see the CTP2 documentation topic: Administration Guide\ Configuration\Selecting Configuration Options. b. Configuration Storage Location network path (or SQL Server database connection string): *For the XML or SQL Server Compact-based option, specify the network path where the cluster configuration files should be located. All cache hosts need read and write access to this location. NOTE: Type the server path (for example, \\ServerName) before clicking the Browse button to start browsing from the context of a server. *For the SQL Server-based option, specify the connection string to the database. For example, when you use integrated security to connect to the database named ClusterConfigurationDB on a server named SQLServer1, the connection string looks like this: Server=SQLServer1;Database=ClusterConfigurationDB;Trusted_Connection=true. 5. Click the Test Connection button to verify the path or connection string. 6. Click Yes if you want to create a new cluster (if asked). 7. Complete the Cache Host Configuration Form: a. Cluster Name: Specify the name of the cache cluster that this cache host will join. The name must be one word, with no spaces or special characters. b. Cluster Size: Specify the number of cache hosts that are planned to be members of the cache cluster, including this one. c. Cache Port Number: Specify the network port that the cache host will use for transmitting cache data. This should be different from the Cluster Port Number. The default value is 22233. d. Cluster Port Number: Specify the network port that the cache host will use for transmitting the cluster heartbeat. This should be different from the Cache Port Number. The default value is 22234. e. Max Server Memory: Specify the maximum amount of memory that the cache host service can allocate when it starts and while it runs. The default value is based on 50% of the available memory on this server. f. Click "Save & Close". 8. Click Finish to complete your installation. When the installation is complete, you can begin developing “Velocity” applications and interacting with the cluster using the PowerShell-based cache administration tool. ------------------------------- Other References ------------------------------- 1. The “Velocity” documentation provided with this installation provides detailed information about the “Velocity” product. The documentation may also be downloaded independent of the installation. 2. Refer to the “Velocity” blog as a reference for late-breaking information about the “Velocity” product and which might include additional information and product details. The "Velocity" blog URL is http://blogs.msdn.com/velocity/default.aspx ------------------------------- Known Issues ------------------------------- Please refer to the “Velocity” blog for late-breaking known issues. 1. Upgrading to "Velocity" CTP2 from CTP1 is not supported. Before installing "Velocity" CTP2 on any cache hosts that have "Velocity" CTP1 present, perform the following prerequisites: a. Uninstall "Velocity" CTP1. b. Remove application-specific firewall exceptions for "Velocity" CTP1. c. Remove all permissions granted to the Everyone security identity. 2. During installation, firewall exceptions are created for File and Printing services and Remote Administration. After installation, these exceptions are not removed, and the firewall is not returned to its initial state. 3. For XML-based cluster configurations, the same configuration storage location cannot be used by more than one cluster. Create a new directory when installing a new cluster. 4. The PowerShell Start-CacheCluster command may not always result in a running cache cluster. Retry or start them manually from Windows Service Manager. Identify the cache hosts that have not started by using the PowerShell Get-CacheHost command. 5. The cache cluster needs to be stopped using the PowerShell Stop-CacheCluster command in order for the cluster to recognize that a new cache host has been designated as a lead host. 6. If the cache host service stops on a lead host while the cluster is running, the cache cluster needs to be restarted using the PowerShell Restart-CacheCluster command in order for the lead host to re-join the cluster. 7. Stopping a non-lead cache host while the cache client is in the middle of a read operation with that cache host may result in a cache client exception. 8. The PowerShell Start-CacheCluster command may not work the first time it is used if the same cache host is used to store the cluster configuration settings. Subsequent start attempts are not an issue. This issue is only applicable to cache hosts running the Windows Server 2003 operating system when selecting the XML-based or SQL Server Compact-based cluster configuration option. 9. Performance of the cache cluster may degrade when caches are present with high availability enabled. 10. The GetAnyEnumerator method may return duplicate entries. 11. The CacheFactory object on the cache client needs to be re-instantiated if the corresponding cache is recreated with the same name. Other caches and clients will continue to operate normally. 12. The Everyone identity should only be used as a last resort when troubleshooting issues with access to the cluster configuration storage location. Grant permissions to the domain computer accounts of the cache hosts. 13. Using cluster configuration storage locations from "Velocity" CTP1 installations is not supported. When installing a CTP2 cluster, delete the contents of the path or specify a new path when selecting the XML-based or SQL Server Compact-based cluster configuration option. 14. The class library documentation for the System.Data.Caching.AdminApi and System.Data.Caching.Commands namespaces is missing descriptions for all members. 15. When using XML-based cluster configuration, you can change cluster configuration settings (XML attributes) in the ClusterConfig.xml file, but adding or removing named caches and cache hosts by inserting or removing XML elements is not supported. To add or remove named caches or cache hosts, use the PowerShell cache administration tool and the "Velocity" installer. For more information about the PowerShell cache administration commands, see Cache Administration with PowerShell (Velocity) in the product documentation. 16. When selecting an XML-based or SQL Server Compact-based cluster configuration, the operating system that is used for the cluster configuration storage location may limit the number of concurrent connections to the shared folder. In such cases, it is not supported to have the number of cache hosts in the cluster exceed that limit. Microsoft Windows XP, Microsoft Windows Server 2003, and the 32-bit version of Microsoft Windows Vista do not allow more than 10 concurrent connections to a shared network folder. We do not recommend that you use these operating systems to store the cluster configuration settings for large clusters. 17. On Microsoft Windows Vista and Microsoft Windows Server 2008 operating systems, you must right-click the "Velocity" PowerShell shortcut and select Run as administrator for the cache administration tool to work correctly. 18. In order for the PowerShell-based cache administration tool to function correctly, the user account running PowerShell needs Administrator permissions on all cache servers in the cluster. 19. The large cache cluster size is not supported for the release. Do not select large for the cache cluster size during installation. ------------------------------- Crash Dump Diagnostics ------------------------------- Crash dump diagnostics for Microsoft Debugging Tools for Windows (windbg) are only available when using the XML-based cluster configuration. To diagnose crashes of the "Velocity" application, you need to do two things: install Microsoft Debugging Tools for Windows and specify the crashDumpProperties element in the ClusterConfig.xml. In order for the changes to take effect after changes are made to the configuration file, restart the cache cluster by using the PowerShell Restart-CacheCluster command. In the advancedProperties element of the ClusterConfig.xml file, add the element: The overWriteDumpFile specifies whether or not new dump files overwrite older ones. Individual minDumpType options can be specified according to the list below, or multiple options can be specified with the OR of these options. For example, a miniDumpType value of 0x26 specifies to use MiniDumpNormal and MiniDumpWithFullMemory and MiniDumpWithHandleData and MiniDumpWithUnloadedModules. MiniDumpNormal = 0x00000000 MiniDumpWithDataSegs = 0x00000001 MiniDumpWithFullMemory = 0x00000002 MiniDumpWithHandleData = 0x00000004 MiniDumpFilterMemory = 0x00000008 MiniDumpScanMemory = 0x00000010 MiniDumpWithUnloadedModules = 0x00000020 MiniDumpWithIndirectlyReferencedMemory = 0x00000040 MiniDumpFilterModulePaths = 0x00000080 MiniDumpWithProcessThreadData = 0x00000100 MiniDumpWithPrivateReadWriteMemory = 0x00000200 MiniDumpWithoutOptionalData = 0x00000400 MiniDumpWithFullMemoryInfo = 0x00000800 MiniDumpWithThreadInfo = 0x00001000 MiniDumpWithCodeSegs = 0x00002000 MiniDumpWithoutManagedState = 0x00004000 When a crash occurs, the crash dump file is saved on the corresponding cache host in the location specified by the log element, a child of the dcacheConfig element, in the DistributedCache.exe.config cache host configuration file.