Training
Module
Use Azure Storage with .NET Aspire - Training
In this module, you'll learn about the integrations built into .NET Aspire that make it simple to store files, data, and messages in Azure Storage accounts.
This browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
The Microsoft Azure Storage Emulator is a tool that emulates the Azure Blob, Queue, and Table services for local development purposes. You can test your application against the storage services locally without creating an Azure subscription or incurring any costs. When you're satisfied with how your application is working in the emulator, switch to using an Azure storage account in the cloud.
Important
The Azure Storage Emulator is now deprecated. Microsoft recommends that you use the Azurite emulator for local development with Azure Storage. Azurite supersedes the Azure Storage Emulator. Azurite will continue to be updated to support the latest versions of Azure Storage APIs. For more information, see Use the Azurite emulator for local Azure Storage development.
The Storage Emulator is available as part of the Microsoft Azure SDK. You can also install the Storage Emulator by using the standalone installer (direct download). To install the Storage Emulator, you must have administrative privileges on your computer.
The Storage Emulator currently runs only on Windows. For emulation on Linux, use the Azurite emulator.
Note
Data created in one version of the Storage Emulator is not guaranteed to be accessible when using a different version. If you need to persist your data for the long term, we recommended that you store that data in an Azure storage account, rather than in the Storage Emulator.
The Storage Emulator depends on specific versions of the OData libraries. Replacing the OData DLLs used by the Storage Emulator with other versions is unsupported, and may cause unexpected behavior. However, any version of OData supported by the storage service may be used to send requests to the emulator.
The Storage Emulator uses a local Microsoft SQL Server 2012 Express LocalDB instance to emulate Azure storage services. You can choose to configure the Storage Emulator to access a local instance of SQL Server instead of the LocalDB instance. See the Start and initialize the Storage Emulator section later in this article to learn more.
The Storage Emulator connects to SQL Server or LocalDB using Windows authentication.
Some differences in functionality exist between the Storage Emulator and Azure storage services. For more information about these differences, see the Differences between the Storage Emulator and Azure Storage section later in this article.
To start the Azure Storage Emulator:
Azure Storage Emulator
.When the Storage Emulator starts, a Command Prompt window will appear. You can use this console window to start and stop the Storage Emulator. You can also clear data, get status, and initialize the emulator from the command prompt. For more information, see the Storage Emulator command-line tool reference section later in this article.
Note
The Azure Storage Emulator may not start correctly if another storage emulator, such as Azurite, is running on the system.
When the emulator is running, you'll see an icon in the Windows taskbar notification area.
When you close the Storage Emulator Command Prompt window, the Storage Emulator will continue to run. To bring up the Storage Emulator console window again, follow the preceding steps as if starting the Storage Emulator.
The first time you run the Storage Emulator, the local storage environment is initialized for you. The initialization process creates a database in LocalDB and reserves HTTP ports for each local storage service.
The Storage Emulator is installed by default to C:\Program Files (x86)\Microsoft SDKs\Azure\Storage Emulator
.
Tip
You can use the Microsoft Azure Storage Explorer to work with local Storage Emulator resources. Look for "(Emulator - Default Ports) (Key)" under "Local & Attached" in the Storage Explorer resources tree after you've installed and started the Storage Emulator.
You can use the storage Emulator command-line tool to initialize the Storage Emulator to point to a SQL database instance other than the default LocalDB instance:
Open the Storage Emulator console window as described in the Start and initialize the Storage Emulator section.
In the console window, type the following command, where <SQLServerInstance>
is the name of the SQL Server instance. To use LocalDB, specify (localdb)\MSSQLLocalDb
as the SQL Server instance.
AzureStorageEmulator.exe init /server <SQLServerInstance>
You can also use the following command, which directs the emulator to use the default SQL Server instance:
AzureStorageEmulator.exe init /server .
Or, you can use the following command, which initializes the database to the default LocalDB instance:
AzureStorageEmulator.exe init /forceCreate
For more information about these commands, see Storage Emulator command-line tool reference.
Tip
You can use the Microsoft SQL Server Management Studio (SSMS) to manage your SQL Server instances, including the LocalDB installation. In the SMSS Connect to Server dialog, specify (localdb)\MSSQLLocalDb
in the Server name: field to connect to the LocalDB instance.
Once you've installed and started the Storage Emulator, you can test your code against it. Every request you make against the Storage Emulator must be authorized, unless it's an anonymous request. You can authorize requests against the Storage Emulator using Shared Key authentication or with a shared access signature (SAS).
The emulator supports a single fixed account and a well-known authentication key for Shared Key authentication. This account and key are the only Shared Key credentials permitted for use with the emulator. They are:
Account name: devstoreaccount1
Account key: Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==
Note
The authentication key supported by the emulator is intended only for testing the functionality of your client authentication code. It does not serve any security purpose. You cannot use your production storage account and key with the emulator. You should not use the development account with production data.
The emulator supports connection via HTTP only. However, HTTPS is the recommended protocol for accessing resources in a production Azure storage account.
The easiest way to connect to the emulator from your application is to configure a connection string in your application's configuration file that references the shortcut UseDevelopmentStorage=true
. The shortcut is equivalent to the full connection string for the emulator, which specifies the account name, the account key, and the emulator endpoints for each of the Azure Storage services:
DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;
AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;
BlobEndpoint=http://127.0.0.1:10000/devstoreaccount1;
QueueEndpoint=http://127.0.0.1:10001/devstoreaccount1;
TableEndpoint=http://127.0.0.1:10002/devstoreaccount1;
The following .NET code snippet shows how you can use the shortcut from a method that takes a connection string. For example, the BlobContainerClient(String, String) constructor takes a connection string.
BlobContainerClient blobContainerClient = new BlobContainerClient("UseDevelopmentStorage=true", "sample-container");
blobContainerClient.CreateIfNotExists();
Make sure that the emulator is running before calling the code in the snippet.
For more information on connection strings, see Configure Azure Storage connection strings.
Note
We recommend that you use the Azure Az PowerShell module to interact with Azure. To get started, see Install Azure PowerShell. To learn how to migrate to the Az PowerShell module, see Migrate Azure PowerShell from AzureRM to Az.
Some Azure storage client libraries, such as the Xamarin library, only support authentication with a shared access signature (SAS) token. You can create the SAS token using Storage Explorer or another application that supports Shared Key authentication.
You can also generate a SAS token by using Azure PowerShell. The following example generates a SAS token with full permissions to a blob container:
CONTAINER_NAME
with a name of your choosing:$context = New-AzStorageContext -Local
New-AzStorageContainer CONTAINER_NAME -Permission Off -Context $context
$now = Get-Date
New-AzStorageContainerSASToken -Name CONTAINER_NAME -Permission rwdl -ExpiryTime $now.AddDays(1.0) -Context $context -FullUri
The resulting shared access signature URI for the new container should be similar to:
http://127.0.0.1:10000/devstoreaccount1/sascontainer?sv=2012-02-12&se=2015-07-08T00%3A12%3A08Z&sr=c&sp=wl&sig=t%2BbzU9%2B7ry4okULN9S0wst/8MCUhTjrHyV9rDNLSe8g%3Dsss
The shared access signature created with this example is valid for one day. The signature grants full access (read, write, delete, list) to blobs within the container.
For more information on shared access signatures, see Grant limited access to Azure Storage resources using shared access signatures (SAS).
The service endpoints for the Storage Emulator are different from the endpoints for an Azure storage account. The local computer doesn't do domain name resolution, requiring the Storage Emulator endpoints to be local addresses.
When you address a resource in an Azure storage account, you use the following scheme. The account name is part of the URI host name, and the resource being addressed is part of the URI path:
<http|https>://<account-name>.<service-name>.core.windows.net/<resource-path>
For example, the following URI is a valid address for a blob in an Azure storage account:
https://myaccount.blob.core.windows.net/mycontainer/myblob.txt
Because the local computer doesn't do domain name resolution, the account name is part of the URI path instead of the host name. Use the following URI format for a resource in the Storage Emulator:
http://<local-machine-address>:<port>/<account-name>/<resource-path>
For example, the following address might be used for accessing a blob in the Storage Emulator:
http://127.0.0.1:10000/myaccount/mycontainer/myblob.txt
The service endpoints for the Storage Emulator are:
http://127.0.0.1:10000/<account-name>/<resource-path>
http://127.0.0.1:10001/<account-name>/<resource-path>
http://127.0.0.1:10002/<account-name>/<resource-path>
Beginning with version 3.1, the Storage Emulator supports read-access geo-redundant replication (RA-GRS). You can access the secondary location by appending -secondary to the account name. For example, the following address might be used for accessing a blob using the read-only secondary in the Storage Emulator:
http://127.0.0.1:10000/myaccount-secondary/mycontainer/myblob.txt
Note
For programmatic access to the secondary with the Storage Emulator, use the Storage Client Library for .NET version 3.2 or later. See the Microsoft Azure Storage Client Library for .NET for details.
Starting in version 3.0, a console window is displayed when you start the Storage Emulator. Use the command line in the console window to start and stop the emulator. You can also query for status and do other operations from the command line.
Note
If you have the Microsoft Azure Compute Emulator installed, a system tray icon appears when you launch the Storage Emulator. Right-click on the icon to reveal a menu that provides a graphical way to start and stop the Storage Emulator.
AzureStorageEmulator.exe [start] [stop] [status] [clear] [init] [help]
To view the list of options, type /help
at the command prompt.
Option | Description | Command | Arguments |
---|---|---|---|
Start | Starts up the Storage Emulator. | AzureStorageEmulator.exe start [-inprocess] |
-Reprocess: Start the emulator in the current process instead of creating a new process. |
Stop | Stops the Storage Emulator. | AzureStorageEmulator.exe stop |
|
Status | Prints the status of the Storage Emulator. | AzureStorageEmulator.exe status |
|
Clear | Clears the data in all services specified on the command line. | AzureStorageEmulator.exe clear [blob] [table] [queue] [all] |
blob: Clears blob data. queue: Clears queue data. table: Clears table data. all: Clears all data in all services. |
Init | Does one-time initialization to set up the emulator. | AzureStorageEmulator.exe init [-server serverName] [-sqlinstance instanceName] [-forcecreate|-skipcreate] [-reserveports|-unreserveports] [-inprocess] |
-server serverName\instanceName: Specifies the server hosting the SQL instance. -sqlinstance instanceName: Specifies the name of the SQL instance to be used in the default server instance. -forcecreate: Forces creation of the SQL database, even if it already exists. -skipcreate: Skips creation of the SQL database. This takes precedence over -forcecreate. -reserveports: Attempts to reserve the HTTP ports associated with the services. -unreserveports: Attempts to remove reservations for the HTTP ports associated with the services. This takes precedence over -reserveports. -inprocess: Performs initialization in the current process instead of spawning a new process. The current process must be launched with elevated permissions if changing port reservations. |
Because the Storage Emulator is a local emulated environment, there are differences between using the emulator and an Azure storage account in the cloud:
LastSyncTime
response element as the current time according to the underlying SQL database.The following differences apply to Blob storage in the emulator:
The following differences apply to Table storage in the emulator:
Edm.Guid
or Edm.Binary
support only the Equal (eq)
and NotEqual (ne)
comparison operators in query filter strings.There are no differences specific to Queue storage in the emulator.
DataServiceVersion
header in some responses where the service was not.init
: -reserveports
(requires elevation), -unreserveports
(requires elevation), -skipcreate
.Get Blob Service Stats
, Get Queue Service Stats
, and Get Table Service Stats
APIs are supported for the account secondary and will always return the value of the LastSyncTime response element as the current time according to the underlying SQL database. For programmatic access to the secondary with the Storage Emulator, use the Storage Client Library for .NET version 3.2 or later. See the Microsoft Azure Storage Client Library for .NET Reference for details.Training
Module
Use Azure Storage with .NET Aspire - Training
In this module, you'll learn about the integrations built into .NET Aspire that make it simple to store files, data, and messages in Azure Storage accounts.