Share via


使用 Azurite 模擬器進行本機 Azure 儲存體開發

Azurite 開放原始碼模擬器提供免費的本機環境,可用來測試您的 Azure Blod、佇列儲存體,以及資料表儲存體應用程式。 如果您滿意應用程式在本機的運作表現,就可以切換成使用雲端的 Azure 儲存體帳戶。 模擬器提供 Windows、Linux 和 macOS 的跨平台支援。

Azurite 取代 Azure 儲存體模擬器,並繼續更新以支援最新版本的 Azure 儲存體 API。

本影片展示如何安裝和執行 Azure 模擬器。

下列各節也會說明影片中的步驟。 選取任一個索引標籤。

安裝 Azurite

Azurite 會自動提供 Visual Studio 2022。 Azurite 可執行檔將作為 Visual Studio 新發行版本一部分進行更新。 如果您執行的是舊版 Visual Studio,則可使用 Node 套件管理員 (npm)、DockerHub 或複製 Azurite GitHub 存放庫來安裝 Azurite。

執行 Azurite

若要在 Visual Studio 中對大部分專案類型使用 Azurite,您必須先執行 Azurite 可執行檔。 執行可執行檔後,Azurite 便會接聽來自應用程式的連線要求。 如需深入瞭解,請參閱從命令列執行 Azurite

針對 Azure Functions 專案和 ASP.NET 專案,您可選擇將專案設定為自動啟動 Azurite。 此設定會在專案設定期間完成。 即使此專案設動會自動啟動 Azurite,Visual Studio 仍不會公開詳細的 Azurite 設定選項。 若要自訂詳細的 Azurite 設定選項,請先執行 Azurite 可執行檔,然後再啟動 Visual Studio。

如需深入瞭解如何將 Azure Functions 專案和 ASP.NET 專案設定為自動啟動 Azurite,請參閱下列指導:

Azurite 可執行檔位置

下表針對 Windows 電腦上執行的不同版本 Visual Studio 顯示 Azurite 可執行檔位置:

Visual Studio 版本 Azurite 可執行檔位置
Visual Studio Community 2022 C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\IDE\Extensions\Microsoft\Azure Storage Emulator
Visual Studio Professional 2022 C:\Program Files\Microsoft Visual Studio\2022\Professional\Common7\IDE\Extensions\Microsoft\Azure Storage Emulator
Visual Studio Enterprise 2022 C:\Program Files\Microsoft Visual Studio\2022\Enterprise\Common7\IDE\Extensions\Microsoft\Azure Storage Emulator

從命令列執行 Azurite

您可在 Visual Studio 安裝的延伸模組資料夾中找到 Azurite 可執行檔,如 Azurite 可執行檔位置表格中所述。

瀏覽至適當的位置,並啟動 azurite.exe。 執行可執行檔之後,Azurite 會接聽連線。

Azurite command-line output

如需深入瞭解設定 Azurite 可用的命令列選項,請參閱命令列選項

從 Azure Functions 專案執行 Azurite

在 Visual Studio 2022 中建立 Azure Functions 專案。 設定專案選項時,勾選標示為 [將 Azurite 用於執行階段儲存體帳戶] 的方塊。

A screenshot showing how to set Azurite to be the runtime storage account for an Azure Functions project.

建立專案之後,Azurite 就會自動啟動。 Azurite 可執行檔位置會在 Azurite 可執行檔位置表格中詳細說明。 輸出大致如下列螢幕擷取畫面所示:

A screenshot showing output after setting Azurite to be the runtime storage account for an Azure Functions project.

您可以稍後透過修改專案的連線服務相依性以變更此設定選項。

從 ASP.NET 專案執行 Azurite

在 Visual Studio Code 2022 中建立 ASP.NET Core Web 應用程式專案。 然後,開啟 [已連線的服務] 對話方塊,選取 [新增服務相依性],然後選取 [儲存體 Azurite 模擬器]

A screenshot showing how to add Azurite as a dependency to an ASP.NET project.

在 [設定儲存體 Azurite 模擬器] 對話方塊中,將 [連接字串名稱] 欄位設定為 StorageConnectionString,然後選取 [完成]

A screenshot showing how to configure a connection string to use Azurite with an ASP.NET project.

設定完成時,請選取 [關閉],然後 Azurite 便會自動啟動。 Azurite 可執行檔位置會在 Azurite 可執行檔位置表格中詳細說明。 輸出大致如下列螢幕擷取畫面所示:

A screenshot showing output after connecting an ASP.NET project to the Azurite emulator.

您可以稍後透過修改專案的連線服務相依性以變更此設定選項。

命令列選項

本節將詳細說明啟動 Azurite 時可用的命令列參數。

說明

選用 - 使用 -h--help 參數取得命令列說明。

azurite -h
azurite --help

接聽主機

選用 - 根據預設,Azurite 會接聽 127.0.0.1 作為本機伺服器。 使用 --blobHost 參數設定所需的位址。

僅接受本機電腦上的要求:

azurite --blobHost 127.0.0.1

允許遠端要求:

azurite --blobHost 0.0.0.0

警告

允許遠端要求可能會讓您的系統容易遭受外部攻擊。

接聽連接埠設定

選用 - 根據預設,Azurite 會接聽連接埠 10000 上的 Blob 服務。 使用 --blobPort 參數來指定所需的接聽連接埠。

注意

使用自訂連接埠之後,您需要更新 Azure 儲存體工具或 SDK 中的連接字串或對應設定。

自訂 Blob 服務接聽連接埠:

azurite --blobPort 8888

讓系統自動選取可用的連接埠:

azurite --blobPort 0

使用中的連接埠會在 Azurite 啟動期間顯示。

工作區路徑

選用 - Azurite 會在執行期間將資料儲存至本機磁碟。 使用 -l--location 參數將路徑指定為工作區位置。 根據預設,將會使用目前的處理序工作目錄。 請注意小寫的 'l'。

azurite -l c:\azurite
azurite --location c:\azurite

存取記錄檔

選用 - 依預設,存取記錄會顯示在主控台視窗中。 使用 -s--silent 參數停用存取記錄的顯示。

azurite -s
azurite --silent

偵錯記錄

選用 - 偵錯記錄包含每個要求和例外狀況堆疊追蹤的詳細資訊。 透過為 -d--debug 參數提供有效的本機檔案路徑,以啟用偵錯記錄。

azurite -d path/debug.log
azurite --debug path/debug.log

鬆散模式

選用 - 根據預設,Azurite 會套用 strict 模式來封鎖不支援的要求標頭和參數。 使用 -L--loose 參數以停用 strict 模式。 請注意大寫的 'L'。

azurite -L
azurite --loose

版本

選用 - 使用 -v--version 參數顯示已安裝的 Azurite 版本號碼。

azurite -v
azurite --version

憑證組態 (HTTPS)

選用 - 根據預設,Azurite 會使用 HTTP 通訊協定。 您可向 --cert 參數提供隱私權增強郵件 (.pem) 或個人資訊交換 (.pfx) 憑證檔案的路徑,藉此啟用 HTTPS 模式。 需要 HTTPS 才能使用 OAuth 驗證連線到 Azurite。

當針對 PEM 檔案提供 --cert 時,您必須提供對應的 --key 參數。

azurite --cert path/server.pem --key path/key.pem

當針對 PFX 檔案提供 --cert 時,您必須提供對應的 --pwd 參數。

azurite --cert path/server.pfx --pwd pfxpassword
HTTPS 設定

如需產生 PEM 和 PFX 檔案的詳細資訊,請參閱 HTTPS 設定

OAuth 組態

選用 - 使用 --oauth 參數啟用 Azurite 的 OAuth 驗證。

azurite --oauth basic --cert path/server.pem --key path/key.pem

注意

OAuth 需要 HTTPS 端點。 提供 --cert 參數和 --oauth 參數以確定已啟用 HTTPS。

Azurite 藉由為 --oauth 開關指定 basic 參數以支援基本驗證。 Azurite 將會執行基本驗證,例如驗證傳入的持有人權杖、檢查簽發者、對象和到期日。 Azurite 不會檢查權杖簽章或權限。 如需深入瞭解授權,請參閱工具和 SDK 的授權

略過 API 版本檢查

選用 - 啟動時,Azurite 會檢查要求的 API 版本是否有效。 下列命令會略過 API 版本檢查:

azurite --skipApiVersionCheck

停用生產樣式 URL

選擇性。 使用完整網域名稱而不是要求 URI 主機中的 IP 時,Azurite 預設會剖析來自要求 URI 主機的儲存體帳戶名稱。 您可以使用 --disableProductStyleUrl 強制從要求 URI 路徑剖析儲存體帳戶名稱:

azurite --disableProductStyleUrl

記憶體內保存

選擇性。 根據預設,Blob 和佇列中繼資料保存至磁碟,而內容保存至範圍檔案。 表格儲存體會將所有資料保存至磁碟。 您可以停用將資料保存至磁碟,並僅將資料儲存在記憶體內。 在記憶體內保存案例中,若 Azurite 處理序終止,則所有資料都會遺失。 您可使用下列選項覆寫預設保存行為:

azurite --inMemoryPersistence

在啟用以 SQL 為基礎的中繼資料實作 (透過 AZURITE_DB) 或指定 --location 選項時,將會拒絕此設定。

範圍記憶體限制

選擇性。 根據預設,記憶體內範圍存放區 (針對 Blob 和佇列內容) 限制為主機電腦的總記憶體 50%。 使用 os.totalmem() 評估總計。 您可使用下列選項覆寫此限制:

azurite --extentMemoryLimit <megabytes>

此選項指定的值沒有限制,但如果限制超過作業系統提供的可用實體記憶體數量,則可能會使用虛擬記憶體。 高限制最終可能導致記憶體不足錯誤或效能降低。 在未指定 --inMemoryPersistence 時,將拒絕此選項。

如需深入瞭解,請參閱使用記憶體內部儲存體

使用 SDK 和工具連線到 Azurite

您可從 Azure 儲存體 SDK 或工具 (例如 Azure 儲存體總管) 連線到 Azurite。 需要驗證,且 Azurite 支援使用 OAuth、共用金鑰和共用存取簽章 (SAS) 的授權。 Azurite 也支援對公用容器的匿名存取。

如需深入瞭解如何透過 Azure SDK 使用 Azurite,請參閱 Azure SDK

已知的儲存體帳戶和金鑰

Azurite 會接受舊版 Azure 儲存體模擬器使用的相同已知帳戶和金鑰。

  • 帳戶名稱:devstoreaccount1
  • 帳戶金鑰:Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==

自訂儲存體帳戶和金鑰

Azurite 支援自訂的儲存體帳戶名稱和金鑰,方法是用下列格式設定 AZURITE_ACCOUNTS 環境變數:account1:key1[:key2];account2:key1[:key2];...

例如,使用具有一個金鑰的自訂儲存體帳戶:

set AZURITE_ACCOUNTS="account1:key1"
export AZURITE_ACCOUNTS="account1:key1"

注意

帳戶金鑰必須是 base64 編碼字串。

或使用多個儲存體帳戶,每個帳戶都有兩個金鑰:

set AZURITE_ACCOUNTS="account1:key1:key2;account2:key1:key2"
export AZURITE_ACCOUNTS="account1:key1:key2;account2:key1:key2"

Azurite 預設每分鐘會從環境變數重新整理自訂帳戶名稱和金鑰。 透過這項功能,您可以動態輪替帳戶金鑰或新增儲存體帳戶,而不需重新啟動 Azurite。

注意

當您設定自訂的儲存體帳戶時,預設 devstoreaccount1 儲存體帳戶會停用。 如果您要在啟用自訂儲存體帳戶之後繼續使用 devstoreaccount1,則必須將其新增至 AZURITE_ACCOUNTS 環境變數的自訂帳戶和金鑰清單。

帳戶金鑰必須是 base64 編碼字串。

連接字串

從您的應用程式連線到 Azurite 最簡單的方法,就是在應用程式參照捷徑 UseDevelopmentStorage=true 的組態檔中設定連接字串。 以下是 app.config 檔案中的連接字串範例:

<appSettings>
  <add key="StorageConnectionString" value="UseDevelopmentStorage=true" />
</appSettings>
HTTPS 連接字串

您可以將下列連接字串傳遞給 Azure sdk 或工具,例如 Azure CLI 2.0 或儲存體總管。

完整的連接字串為:

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;

若要連線到特定服務,您可使用下列連接字串:

若僅要連線到 Blob 儲存體,連接字串為:

DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=http://127.0.0.1:10000/devstoreaccount1;

HTTPS 連接字串

完整的 HTTPS 連接字串為:

DefaultEndpointsProtocol=https;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=https://127.0.0.1:10000/devstoreaccount1;QueueEndpoint=https://127.0.0.1:10001/devstoreaccount1;TableEndpoint=https://127.0.0.1:10002/devstoreaccount1;

若要連線到特定服務,您可使用下列連接字串:

若只要使用 Blob 服務,HTTPS 連接字串為:

DefaultEndpointsProtocol=https;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=https://127.0.0.1:10000/devstoreaccount1;

如果您使用 dotnet dev-certs 來產生自我簽署的憑證,請使用下列連接字串。

DefaultEndpointsProtocol=https;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=https://localhost:10000/devstoreaccount1;QueueEndpoint=https://localhost:10001/devstoreaccount1;TableEndpoint=https://localhost:10002/devstoreaccount1;

使用自訂儲存體帳戶和金鑰時,請更新連接字串。

如需詳細資訊,請參閱設定 Azure 儲存體連接字串

Azure SDK

若要透過 Azure SDK 連線到 Azurite,請遵循下列步驟:

  • 透過 --oauth 參數啟用 Azurite 的 OAuth 驗證。 如需深入瞭解,請參閱 OAuth 組態
  • 透過 --cert--key/--pwd 選項使用自我簽署憑證來啟用 HTTPS。 如需深入瞭解如何產生憑證,請參閱憑證組態 (HTTPS)HTTPS 設定

憑證就緒時,請使用下列命令列選項啟動 Azurite:

azurite --oauth basic --cert cert-name.pem --key cert-name-key.pem

cert-name.pemcertname-key.pem 取代為憑證和金鑰檔案的名稱。 如果您使用 PFX 憑證,請使用 --pwd 選項,而不是 --key 選項。

若要與 Blob 儲存體資源互動,您可具現化 BlobContainerClientBlobServiceClientBlobClient

下列範例示範如何使用三種不同授權機制來授權 BlobContainerClient 物件:DefaultAzureCredential、連接字串和共用金鑰。 DefaultAzureCredential 提供以持有人權杖為基礎的驗證機制,並使用針對驗證使用的認證類型鏈。 驗證後,此認證提供 OAuth 權杖作為用戶端具現化的一部分。 如需深入瞭解,請參閱 DefaultAzureCredential 類別參考

// With container URL and DefaultAzureCredential
var client = new BlobContainerClient(
    new Uri("https://127.0.0.1:10000/devstoreaccount1/container-name"), new DefaultAzureCredential()
  );

// With connection string
var client = new BlobContainerClient(
    "DefaultEndpointsProtocol=https;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=https://127.0.0.1:10000/devstoreaccount1;", "container-name"
  );

// With account name and key
var client = new BlobContainerClient(
    new Uri("https://127.0.0.1:10000/devstoreaccount1/container-name"),
    new StorageSharedKeyCredential("devstoreaccount1", "Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==")
  );

Microsoft Azure 儲存體總管

您可以使用儲存體總管來查看儲存在 Azurite 中的資料。

使用 HTTP 連線至 Azurite

在儲存體總管中,依照下列步驟連線到 Azurite:

  1. 選取 [管理帳戶] 圖示
  2. 選取 [新增帳戶]
  3. 選取 [連結至本機模擬器]
  4. 選取下一個
  5. 將 [顯示名稱] 欄位編輯為您選擇的名稱
  6. 再次選取 [下一步]
  7. 選取連線
使用 HTTPS 連線至 Azurite

依預設,儲存體總管不會開啟使用自我簽署憑證的 HTTPS 端點。 如果您是使用 HTTPS 執行 Azurite,則可能是使用自我簽署的憑證。 請在儲存體總管中,透過 [編輯] ->[SSL 憑證] ->[匯入憑證] 對話方塊匯入 SSL 憑證。

將憑證匯入儲存體總管
  1. 找到本機電腦上的憑證。
  2. 在儲存體總管中,移至 [編輯] ->[SSL 憑證] ->[匯入憑證] 並匯入您的憑證。

如果您未匯入憑證,將會收到錯誤:

unable to verify the first certificateself signed certificate in chain

透過 HTTPS 連接字串新增 Azurite

請依照下列步驟將 Azurite HTTPS 新增至儲存體總管:

  1. 選取 [切換瀏覽器]
  2. 選取 [本機與已連結]
  3. 以滑鼠右鍵按一下 [儲存體帳戶],然後選取 [連線到 Azure 儲存體]
  4. 選取 [使用連接字串]
  5. 選取 [下一步]。
  6. 在 [顯示名稱] 欄位中輸入值。
  7. 輸入本文件上一節的 HTTPS 連接字串
  8. 選取下一個
  9. 選取連線

工作區結構

初始化 Azurite 時,可能會在工作區位置中建立下列檔案和資料夾。

  • __blobstorage__:此目錄包含 Azurite Blob 服務保存的二進位資料
  • __queuestorage__:此目錄包含 Azurite 佇列服務保存的二進位資料
  • __tablestorage__:此目錄包含 Azurite 資料表服務保存的二進位資料
  • __azurite_db_blob__.json:Azurite Blob 服務中繼資料檔案
  • __azurite_db_blob_extent__.json:Azurite Blob 服務範圍中繼資料檔案
  • __azurite_db_queue__.json:Azurite 佇列服務中繼資料檔案
  • __azurite_db_queue_extent__.json:Azurite 佇列服務範圍中繼資料檔案
  • __azurite_db_table__.json:Azurite 資料表服務中繼資料檔案
  • __azurite_db_table_extent__.jsonAzurite 資料表服務範圍中繼資料檔案

若要清除 Azurite,請刪除上述的檔案和資料夾,然後重新啟動模擬器。

Azure 與 Azure 儲存體之間的差異

Azurite 的本機執行個體與雲端中的 Azure 儲存體帳戶之間有一些功能上的差異。

端點和連接 URL

Azurite 的服務端點與 Azure 儲存體帳戶的端點不同。 本機電腦不會進行網域名稱解析,要求 Azurite 端點必須是本機位址。

當您定址 Azure 儲存體帳戶中的資源時,帳戶名稱會是 URI 主機名稱的一部分。 所定址的資源是 URI 路徑的一部分:

<http|https>://<account-name>.<service-name>.core.windows.net/<resource-path>

下列 URI 是 Azure 儲存體帳戶中的有效 Blob 位址:

https://myaccount.blob.core.windows.net/mycontainer/myblob.txt

IP 樣式 URL

因為本機電腦不會解析網域名稱,所以帳戶名稱是 URI 路徑的一部分,而不是主機名稱。 針對 Azurite 中的資源使用下列 URI 格式:

http://<local-machine-address>:<port>/<account-name>/<resource-path>

下列位址可能會用於存取 Azurite 中的 Blob:

http://127.0.0.1:10000/myaccount/mycontainer/myblob.txt

生產樣式 URL

您可以選擇性地修改主機檔案,以存取具有生產樣式 URL 的帳戶。

首先,將一或多行新增至主機檔案。 例如:

127.0.0.1 account1.blob.localhost
127.0.0.1 account1.queue.localhost
127.0.0.1 account1.table.localhost

接下來,設定環境變數以啟用自訂儲存體帳戶和金鑰:

set AZURITE_ACCOUNTS="account1:key1:key2"

您可以新增更多帳戶。 請參閱本文的自訂儲存體帳戶和金鑰一節。

啟動 Azurite 並使用自訂連接字串來存取您的帳戶。 在下列範例中,連接字串假設使用預設連接埠。

DefaultEndpointsProtocol=http;AccountName=account1;AccountKey=key1;BlobEndpoint=http://account1.blob.localhost:10000;QueueEndpoint=http://account1.queue.localhost:10001;TableEndpoint=http://account1.table.localhost:10002;

請勿以這種方式使用 Azure 儲存體總管來存取預設帳戶。 這會發生錯誤 (bug),儲存體總管一律會在 URL 路徑中新增帳戶名稱,導致失敗。

根據預設,使用 Azurite 搭配生產樣式 URL 時,帳戶名稱應該是完整網域名稱中的主機名稱,例如 http://devstoreaccount1.blob.localhost:10000/container。 若要在 URL 路徑中使用具有帳戶名稱的生產樣式 URL (例如 http://foo.bar.com:10000/devstoreaccount1/container),請務必在啟動 Azurite 時使用 --disableProductStyleUrl 參數。

如果使用 host.docker.internal 作為要求 URI 主機 (例如:http://host.docker.internal:10000/devstoreaccount1/container),Azurite 會從要求 URI 路徑取得帳戶名稱。 不論您在啟動 Azurite 時是否使用 --disableProductStyleUrl 參數,都會發生此行為。

調整和效能

Azurite 不支援大量的連線用戶端。 沒有任何效能保證。 Azurite 適合用於開發和測試目的。

錯誤處理

Azurite 與 Azure 儲存體錯誤處理邏輯一致,但是有一些差異。 例如,錯誤訊息可能會不同,而錯誤狀態代碼則會一致。

RA-GRS

Azurite 支援讀取權限異地備援複寫 (RA-GRS)。 針對儲存體資源,請將 -secondary 附加至帳戶名稱以存取次要位置。 例如,下列位址可能會用於在 Azurite 中使用唯讀的次要位置來存取 Blob:

http://127.0.0.1:10000/devstoreaccount1-secondary/mycontainer/myblob.txt

資料表支援

Azurite 中的資料表支援目前為預覽狀態。 如需詳細資訊,請參閱 Azurite V3 資料表專案。

長期函式的支援需要資料表。

重要

Azurite 對資料表儲存體的支援目前為預覽狀態。 請參閱 Microsoft Azure 預覽版增補使用規定,以了解適用於 Azure 功能 (搶鮮版 (Beta)、預覽版,或尚未正式發行的版本) 的法律條款。

Azurite 是開放原始碼

歡迎為 Azurite 提供貢獻和建議。 移至 Azurite GitHub 專案頁面,或我們正在追蹤的里程碑和工作專案的 GitHub 問題,以瞭解即將推出的功能和錯誤修正。 您也可以在 GitHub 中追蹤詳細的工作項目。

下一步