Felsöka Azure Cosmos DB-emulatorn

Artikel
11/20/2024

Azure Cosmos DB-emulatorn tillhandahåller en miljö som emulerar molntjänsten för utveckling. Använd tipsen i den här artikeln för att felsöka problem som kan uppstå när du installerar eller använder emulatorn.

Checklista för felsökning

Här är en lista över vanliga felsökningssteg att följa om Azure Cosmos DB-emulatorn inte fungerar som förväntat.

Återställa data

Om du har installerat en ny version av emulatorn och det uppstår fel kontrollerar du att du återställer data. Om du vill återställa data öppnar du snabbmenyn för Azure Cosmos DB-emulatorn från systemfältet och väljer sedan Återställ data.

Om återställning av data inte åtgärdar felen kan du:

Avinstallera emulatorn.
Avinstallera äldre versioner av emulatorn (om de finns).
%ProgramFiles%\Azure Cosmos DB Emulator Ta bort mappen.
Installera om emulatorn.

Om återställningen av data inte fungerar går du till platsen %LOCALAPPDATA%\CosmosDBEmulator och tar sedan bort mappen.

Granska skadade Windows-prestandaräknare

Om Azure Cosmos DB-emulatorn slutar svara samlar du in dumpfilerna %LOCALAPPDATA%\CrashDumps från mappen, komprimerar filerna och öppnar sedan ett supportärende i Azure Portal.
Om Microsoft.Azure.Cosmos.ComputeServiceStartupEntryPoint.exe slutar svara kan den här kraschen indikera att prestandaräknarna är skadade. Kör följande kommando för att kontrollera räknarstatusen:
```
lodctr /R
```

Diagnostisera anslutningsproblem

Om du upplever ett anslutningsproblem samlar du in spårningsfiler, komprimerar filerna och öppnar sedan ett supportärende i Azure Portal.
Om du får meddelandet "Tjänsten är inte tillgänglig" kanske emulatorn inte initierar nätverksstacken. Kontrollera om du har Pulse Secure Client eller Juniper Networks Client installerat eftersom deras nätverksfilterdrivrutiner kan orsaka problemet. Du kan också prova att avinstallera andra nätverksfilterdrivrutiner för att åtgärda problemet. Du kan också starta emulatorn med hjälp /DisableRIO av för att växla emulatorns nätverkskommunikation till vanliga Winsock.
Om du får ett anslutningsfel som "Forbidden", "message":"Request is being made with a forbidden encryption in transit protocol or cipher. Check account SSL/TLS minimum allowed protocol setting..."kan det här felmeddelandet indikera globala ändringar i operativsystemet (till exempel Insider Preview Build 20170) eller ändringar i webbläsarinställningarna som aktiverar TLS 1.3 som standardprotokoll. Ett liknande felmeddelande, till exempel "Microsoft.Azure.Documents.DocumentClientException: Begäran görs med en förbjuden kryptering i transitprotokollet eller chiffer. Kontrollera kontoinställningen SSL/TLS minsta tillåtna protokoll" kan genereras om du använder SDK:n för att köra en begäran mot Azure Cosmos DB-emulatorn. Det här felet kan också inträffa eftersom Azure Cosmos DB-emulatorn endast stöder TLS 1.2-protokollet. Den rekommenderade lösningen är att ange TLS 1.2 som standard.

Till exempel:
1. I IIS-hanteraren går du till Webbplatser>standardwebbplatser.
2. Leta upp webbplatsbindningar för port 8081 och redigera dem för att inaktivera TLS 1.3. Du kan också uppdatera inställningarna för webbläsaren med hjälp av alternativet Inställningar .
  
  Kommentar
  
  Om datorn försätts i viloläge eller kör os-uppdateringar medan emulatorn körs kan felmeddelandet "Tjänsten är inte tillgänglig för närvarande" visas.
3. Om du vill återställa emulatordata högerklickar du på ikonen som visas i Meddelandefältet i Windows och väljer sedan Återställ data.

Samla in spårningsfiler

Om du vill samla in felsökningsspårningar kör du följande kommandon som administratör i ett kommandotolkfönster:

Navigera till sökvägen där emulatorn är installerad:
```
cd /d "%ProgramFiles%\Azure Cosmos DB Emulator"
```
Stäng av emulatorn och titta på systemfältet för att se till att programmet stängs av:
```
Microsoft.Azure.Cosmos.Emulator.exe /shutdown
```
Kommentar

Det kan ta en minut för processen att slutföras. Du kan också välja Avsluta i användargränssnittet för Azure Cosmos DB-emulatorn.

Börja logga genom att köra följande kommando:

Microsoft.Azure.Cosmos.Emulator.exe /startwprtraces

Starta emulatorn:
```
Microsoft.Azure.Cosmos.Emulator.exe
```
Återskapa problemet. Om datautforskaren inte fungerar måste du bara vänta några sekunder på att webbläsaren ska läsas in för att kunna identifiera felet.

Stoppa loggning:

Microsoft.Azure.Cosmos.Emulator.exe /stopwprtraces

Navigera till %ProgramFiles%\Azure Cosmos DB Emulator sökvägen och leta upp filen docdbemulator_000001.etl .
Öppna ett supportärende i Azure Portal och inkludera .etl-filen tillsammans med alla steg som krävs för att återskapa problemet.

Installera certifikat för klientprogram

Ibland kan du behöva ta det exporterade emulatorcertifikatet och använda det med ett klientprogram. Den exakta processen varierar beroende på SDK.

Exportera TLS/SLL-certifikat

Exportera emulatorcertifikatet för att använda emulatorns slutpunkt från språk och körningsmiljöer som inte integreras med Windows Certificate Store. Du kan exportera certifikatet med Hjälp av Windows Certificate Manager eller PowerShell när du har kört emulatorn för första gången.

Hämta certifikatet med hjälp av det egna namnet DocumentDbEmulatorCertificate och lagra certifikatet i en gränssnittsvariabel med namnet $cert.
```
$cert = Get-ChildItem Cert:\LocalMachine\My | where{$_.FriendlyName -eq 'DocumentDbEmulatorCertificate'}
```
Använd Export-Certificate för att exportera certifikatet till en tillfällig fil i din hemmapp.
```
$params = @{
    Cert = $cert
    Type = "CERT"
    FilePath = "$home/tmp-cert.cer"
    NoClobber = $true
}
Export-Certificate @params
```
Kommentar

I Windows är startmappen vanligtvis C:\Users\[username]\, förutsatt att hemenheten är C:.
Använd certutil för att konvertera certifikatet till en Base-64-kodad X.509-certifikatfil .
```
certutil -encode $home/tmp-cert.cer $home/cosmosdbcert.cer
```
Ta bort den tillfälliga filen.
```
Remove-Item $home/tmp-cert.cer
```

Importera certifikat för Java-program

När du kör Java-program eller MongoDB-program som använder en Java-baserad klient är det enklare att installera certifikatet i Java-standardcertifikatarkivet än att skicka parametrarna -Djavax.net.ssl.trustStore=<keystore> -Djavax.net.ssl.trustStorePassword="<password>" . Det inkluderade Java Demo-programmet (https://localhost:8081/_explorer/index.html) beror till exempel på standardcertifikatarkivet.

Följ anvisningarna i Skapa, exportera och importera TLS/SSL-certifikat för att importera X.509-certifikatet till java-standardcertifikatarkivet. Kom ihåg att du arbetar i katalogen %JAVA_HOME% när du kör keytool. När certifikatet har importerats till certifikatarkivet kan klienter för SQL och Azure Cosmos DB:s API för MongoDB ansluta till Azure Cosmos DB-emulatorn.

Du kan också köra följande bash skript för att importera certifikatet:

#!/bin/bash

# If the emulator was started with /AllowNetworkAccess, replace the following with the actual IP address of it:
EMULATOR_HOST=localhost
EMULATOR_PORT=8081
EMULATOR_CERT_PATH=/tmp/cosmos_emulator.cert
openssl s_client -connect ${EMULATOR_HOST}:${EMULATOR_PORT} </dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > $EMULATOR_CERT_PATH
# Delete the cert if it already exists
sudo $JAVA_HOME/bin/keytool -cacerts -delete -alias cosmos_emulator
# Import the cert
sudo $JAVA_HOME/bin/keytool -cacerts -importcert -alias cosmos_emulator -file $EMULATOR_CERT_PATH

CosmosDBEmulatorCertificate När TLS/SSL-certifikatet har installerats bör programmet kunna ansluta till och använda den lokala Azure Cosmos DB-emulatorn.

Om du har problem kan du läsa Felsöka SSL/TLS-anslutningar. I de flesta fall kanske certifikatet inte installeras i arkivet %JAVA_HOME%/jre/lib/security/cacerts . Om det till exempel finns fler än en installerad version av Java kan ditt program använda ett annat certifikatarkiv än det du uppdaterade.

Importera certifikat för Python-program

När du ansluter till emulatorn från Python-program inaktiveras TLS-verifiering. Python SDK för Azure Cosmos DB for NoSQL försöker som standard inte använda TLS/SSL-certifikatet när det ansluter till den lokala emulatorn. Mer information finns i Azure Cosmos DB for NoSQL-klientbibliotek för Python.

Om du vill använda TLS-validering följer du exemplen i TLS/SSL-omslutning för socketobjekt.

Importera certifikat för Node.js program

När du ansluter till emulatorn från Node.js SDK:er inaktiveras TLS-verifiering. Som standard försöker Node.js SDK (version 1.10.1 eller senare) för API:et för NoSQL inte använda TLS/SSL-certifikatet när det ansluter till den lokala emulatorn.

Om du vill använda TLS-validering följer du exemplen i Node.js dokumentationen.

Rotera certifikat

Du kan framtvinga regenerering av emulatorcertifikaten genom att öppna emulatorn med /ResetDataPath argumentet . Den här åtgärden rensar ut alla data som lagras lokalt av emulatorn. Mer information om kommandoradsargument finns i Kommandoradsargument för Windows-emulatorn.

Dricks

Du kan också välja Återställ data från Snabbmenyn för Azure Cosmos DB-emulatorn i Windows-systemfältet.

Om du har installerat certifikaten i Java-certifikatarkivet eller använt dem någon annanstans måste du importera dem igen med hjälp av de aktuella certifikaten. Programmet kan inte ansluta till den lokala emulatorn förrän du har uppdaterat certifikaten.

Dela via