Introduction
When attempting to install a new version of the Azure Storage Emulator either as a separate installation package or automatically as part of an Azure SDK update, you may run into an error message which states the storage emulator has failed to install. This can occur using the Web Platform Installer (WebPI), NuGet Package Manager or when performing the install manually.
Below is the message received using the WebPI.
Storage Emulator Background (Optional Reading)
The Windows azure storage emulator executable lives under the Microsoft SDKs directory as shown below:
Configuration
If we take a quick look inside the WAStorageEmulator.exe.config file, we can see each of the storage services pointing to local service endpoints.
<StorageEmulatorConfig>
<services>
<service name="Blob" url="http://127.0.0.1:10000/"/>
<service name="Queue" url="http://127.0.0.1:10001/"/>
<service name="Table" url="http://127.0.0.1:10002/"/>
</services>
Database
By default, the storage emulator uses SQL Server Express with the LocalDB execution mode to store its data for each of the storage services.
This configuration can be seen by looking at the DevelopmentStorage config file:
="1.0"
<DevelopmentStorage xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="2009-03-18">
<SQLInstance>(localdb)\v11.0</SQLInstance>
<PageBlobRoot>C:\Users\Carl\AppData\Local\DevelopmentStorage\PageBlobRoot</PageBlobRoot>
<BlockBlobRoot>C:\Users\Carl\AppData\Local\DevelopmentStorage\BlockBlobRoot</BlockBlobRoot>
<LogPath>C:\Users\Carl\AppData\Local\DevelopmentStorage\Logs</LogPath>
<LoggingEnabled>false</LoggingEnabled>
</DevelopmentStorage>
which can be found at the location shown below:
When the development storage emulator starts for the first time, it creates the v11.0 database in LocalDB. This can be verified from the command line as shown below:
If you want to choose another instance of SQL instead of LocalDB, you would need to change the <SQLInstance>**</SQLInstance> property accordingly as shown in the configuration snippet above.
The database files for the storage emulator are located in the logged in user root directory:
The format of the database file name is WAStorageEmulatorDb<Version of storage SDK>.mdf.
So the version of the Azure storage emulator currently installed is 3.3 as shown above.
There will be a database per version of the SDK installed in this directory.
SQL Server Express 'LocalDB' Background (Optional Reading)
Microsoft SQL Server express allows you to take advantage of the same powerful database engine in a version tailored for redistribution and embedding. SQL Server Express includes 10GB of storage per database, easy backup and restore functionality, and compatibility with all editions of SQL Server and Microsoft Azure SQL Database.
LocalDB is a special execution mode of SQL Server Express which runs under the users' security context, targeted at developers.
SQL Server Express LocalDB instances are managed by using the SqlLocalDB.exe utility. LocalDB can be used to work with SQL Server databases. System database files for a database are stored in the user's local AppData folder.
Diagnosis
Inspecting the install logs gives us an indication although subtle as to what is going wrong with the install (cut down for brevity):
. === Logging started: 06-Apr-14 0:02:16 ===
Action start 0:02:16: INSTALL.
Action start 0:02:16: AppSearch.
Action ended 0:02:16: AppSearch. Return value 1.
...
Action start 0:02:16: InstallFinalize.
CAQuietExec: Windows Azure Storage Emulator 3.0.0.0 command line tool
CAQuietExec: Error: No available SQL Instance was found.
CAQuietExec: Error 0xfffffff6: Command line returned an error.
CAQuietExec: Error 0xfffffff6: CAQuietExec Failed
CustomAction RunInitialize returned actual error code 1603
(note this may not be 100% accurate if translation happened inside sandbox)
Action ended 0:02:16: InstallFinalize. Return value 3.
Action ended 0:02:17: INSTALL. Return value 3.
Property(S): UpgradeCode = {CF5CD495-AEDE-42DA-B7CF-A70D398D4E6A}
Property(S): RunInitialize = "C:\Program Files
(x86)\Microsoft SDKs\Windows Azure\Storage Emulator\WAStorageEmulator.exe"
init -forcecreate -autodetect
Property(S): DOTNET4FULL = 4.5.51641
Property(S): LOCALDBINSTALLED = C:\Program Files
(x86)\Microsoft SQL Server\110\LocalDB\Binn\SqlUserInstance.dll
Property(S): SQLEXPRESSVERSION = 11.0.2100.60
Property(S): TARGETDIR = J:\
Property(S): StorageEmulatorMenuFolder =
C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Windows Azure\Storage Emulator\
Property(S): STORAGEEMUDIR = C:\Program Files (x86)\Microsoft SDKs\Windows Azure\Storage Emulator\
Property(S): WixUIRMOption = UseRM
Property(S): ALLUSERS = 1
Property(S): ARPNOMODIFY = 1
Property(S): REINSTALLMODE = amus
Property(S): WindowsAzureMenuFolder =
C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Windows Azure\
Property(S): ProgramMenuFolder = C:\ProgramData\Microsoft\Windows\Start Menu\Programs\
Property(S): WINDOWSAZUREDIR = C:\Program Files (x86)\Microsoft SDKs\Windows Azure\
Property(S): MICROSOFTSDKSDIR = C:\Program Files (x86)\Microsoft SDKs\
Property(S): ProgramFilesFolder = C:\Program Files (x86)\
...
Property(S): ProductToBeRegistered = 1
MSI (s) (6C:2C) [00:02:17:017]: Product: Windows Azure Storage Emulator - v3.0 -- Installation failed.
MSI (s) (6C:2C) [00:02:17:017]: Windows Installer installed the product.
Product Name: Windows Azure Storage Emulator - v3.0. Product Version: 3.0.6848.39.
Product Language: 1033. Manufacturer: Microsoft Corporation. Installation success or error status: 1603.
=== Logging stopped: 06-Apr-14 0:02:17 ===
The error message at first may appear confusing as you most likely do have an available SQL instance. However digging a little deeper into what the installer is attempting to do will help resolve the issue.
Looking back at the error log may have left you confused as you may well have verified that a LocalDB instance does indeed exist.
Taking a look at the 'application' event log however reveals more detail.
Log Name: Application
Source: SQLLocalDB 11.0
Date:
Event ID: 267
Task Category: None
Level: Error
Keywords: Classic
User: N/A
Computer:
Description:
LocalDB instance is corrupted. See the Windows Application event log for error details.
Event Xml:
<Event xmlns="http://schemas.microsoft.com/win/2004/08/events/event">
<System>
<Provider Name="SQLLocalDB 11.0" />
<EventID Qualifiers="35269">267</EventID>
<Level>2</Level>
<Task>0</Task>
<Keywords>0x80000000000000</Keywords>
<TimeCreated SystemTime="2014-05-05T16:44:32.000000000Z" />
<EventRecordID>74923</EventRecordID>
<Channel>Application</Channel>
<Computer></Computer>
<Security />
</System>
<EventData>
</EventData>
</Event>
Log Name: Application
Source: SQLLocalDB 11.0
Date: AM
Event ID: 261
Task Category: None
Level: Error
Keywords: Classic
User: N/A
Computer:
Description:
Cannot access LocalDB instance folder:
%%LOCALAPPDATA%%\Microsoft\Microsoft SQL Server Local DB\Instances\<instance name>.
Event Xml:
<Event xmlns="http://schemas.microsoft.com/win/2004/08/events/event">
<System>
<Provider Name="SQLLocalDB 11.0" />
<EventID Qualifiers="35269">261</EventID>
<Level>2</Level>
<Task>0</Task>
<Keywords>0x80000000000000</Keywords>
<TimeCreated SystemTime="2014-05-05T16:44:32.000000000Z" />
<EventRecordID>74922</EventRecordID>
<Channel>Application</Channel>
<Computer></Computer>
<Security />
</System>
<EventData>
</EventData>
</Event>
Here, we see a more granular level of explanation, informing that the LocalDB instance is corrupt.
When we upgrade versions of the Storage Emulator, it is most likely that the database has undergone some new enhancements. As a result, we need to ensure the database gets updated regardless of its prior existence.
The Storage Emulator database, we mentioned earlier, only gets created on first run of the storage emulator if it doesn't already exist. If we look more closely at the command line tool switches available for the 'Init' command, we observe the -forcreate option. This forces the creation of the SQL database, even if it already exists.
As our error is at the instance level, the storage emulator command line tool using the -forcreate option won't buy us anything. However, if our error message was related to the actual database, it would certainly come into play.
In this case, we can go direct to the database instance, stop it, delete it and re-create it, including the removal of any storage emulator databases that may have been partially created along the way.
Firstly, stop the LocalDB instance from the command line by issuing the stop command as shown below:
Then proceed to issue the delete command: sqllocaldb delete v11.0
It is possible that the WAStorageEmulatorDb* database has been created from a previous attempt of the current upgrade you are trying to undertake. In this case at this point issues a command to delete the storage emulator database from the location shown earlier:
delete C:\Users\<Your user account>\WAStorageEmulatorDb*.*
Proceed to re-create the LocalDB instance by issuing the following command: sqllocaldb create v11.0
After performing the steps outlined, we can re-run the upgrade and get the result we expected first time round.
Quick Reference
WAStorageEmulator [/start] [/stop] [/status] [/clear] [/init] [/help]
Useful Links
Conclusion
When experiencing issues upgrading the storage emulator, the install logs, event log and some understanding of what the storage emulator relies on to run, will help to problem solve installation issues. In our case, it boiled down to a corrupt LocalDB instance which needed a nudge to re create.
We come to expect our upgrade experience to work almost flawlessly these days but it is always worth bearing in mind that an install is just a set of code steps written by someone like you or me using libraries with potential bugs just waiting to crop up, even with Test Driven Development (TDD), Behavior Driven Development (BDD), Integration and smarter software release cycles.
