Az SqlPackage hibáinak és teljesítményének elhárítása

Bizonyos esetekben az SqlPackage-műveletek a vártnál hosszabb időt vesznek igénybe, vagy nem fejeződnek be. Ez a cikk néhány gyakran javasolt taktikát ismertet ezeknek a műveleteknek a hibaelhárítására vagy teljesítményének javítására. A rendelkezésre álló paraméterek és tulajdonságok megismeréséhez ajánlott elolvasni az egyes műveletek dokumentációs oldalát, ez a cikk kiindulópontként szolgál az SqlPackage-műveletek vizsgálatához.

Overall strategy

Általános útmutatóként jobb teljesítmény érhető el az SqlPackage .NET-verziójával a DacFramework.msitelepített .NET-keretrendszerverzió helyett.

Ha nem tudja telepíteni az SqlPackage dotnet eszközt, amely lehetővé teszi sqlpackage parancsok végrehajtását a parancssorból bármelyik könyvtárban:

Töltse le az SqlPackage zip-jének letöltését a .NET 8-on az operációs rendszerhez (Windows, macOS vagy Linux).
Bontsa ki az archívumot a letöltési oldalon leírtak szerint.
Nyisson meg egy parancssort, és módosítsa a könyvtárat (cd) az SqlPackage mappára.

Fontos, hogy az SqlPackage legújabb elérhető verzióját használja, mivel a teljesítménybeli fejlesztések és hibajavítások rendszeresen megjelennek.

Az SqlPackage helyettesítése az importálási/exportálási szolgáltatáshoz

Ha az importálási/exportálási szolgáltatással próbálta importálni vagy exportálni az adatbázist, az SqlPackage használatával ugyanezt a műveletet hajthatja végre az opcionális paraméterek és tulajdonságok nagyobb szabályozásával.

Importálás esetén egy példaparancs a következő:

./SqlPackage /Action:Import /sf:<source-bacpac-file-path> /tsn:<full-target-server-name> /tdn:<a new or empty database> /tu:<target-server-username> /tp:<target-server-password> /df:<log-file>

Exportálás esetén egy példaparancs a következő:

./SqlPackage /Action:Export /tf:<target-bacpac-file-path> /ssn:<full-source-server-name> /sdn:<source-database-name> /su:<source-server-username> /sp:<source-server-password> /df:<log-file>

A felhasználónév és a jelszó helyett többtényezős hitelesítés használható a Microsoft Entra-hitelesítéssel (korábban Azure Active Directory) történő hitelesítéshez többtényezős hitelesítéssel. Cserélje le a felhasználónév és a jelszó paramétereit /ua:true és /tid:"yourdomain.onmicrosoft.com".

Diagnostics

Az SqlPackage hibáinak és váratlan viselkedésének diagnosztizálása diagnosztikai naplókkal és diagnosztikai csomagokkal támogatott. A diagnosztikai naplók elengedhetetlenek a hibaelhárításhoz, és a /DiagnosticsFile:<filename> paraméterrel rendelkező fájlba vannak rögzítve.

A diagnosztikai kimenet részletességi szintjét a /DiagnosticsLevel paraméter vezérli. A Information és a Verbose értékei hasznosak a további részletek eléréséhez.

A teljesítményhez kapcsolódó nyomkövetési adatok az SqlPackage futtatása előtt DACFX_PERF_TRACE=true környezeti változó beállításával naplózhatók. A nyomkövetési adatok növelik a naplókimenetet, ezért csak a teljesítményproblémák diagnosztizálásakor szerepeljen. A környezeti változó PowerShellben való beállításához használja a következő parancsot:

Set-Item -Path Env:DACFX_PERF_TRACE -Value true

Az SqlPackage 162.5 és újabb verzióiban diagnosztikai csomag hozható létre a hibaelhárításhoz. A diagnosztikai csomag tartalmazza az SqlPackage verzióját, a végrehajtott parancsot, a forrás- és céladatbázis-modellekre vonatkozó információkat, valamint a parancs kimenetét. Diagnosztikai csomag létrehozásához használja a /DiagnosticsPackageFile:<filename> paramétert.

Common issues

Timeout errors

Az időtúllépésekkel kapcsolatos problémák esetén az alábbi tulajdonságok használhatók az SqlPackage és az SQL-példány közötti kapcsolat finomhangolásához:

/p:CommandTimeout=: A parancs időtúllépését adja meg másodpercekben a lekérdezés végrehajtásakor. Default: 60
/p:DatabaseLockTimeout=: Az adatbázis zárolási időkorlátját adja meg másodpercben. A -1 a határozatlan idejű várakozáshoz használható, alapértelmezés szerint: 60
/p:LongRunningCommandTimeout=: Meghatározza a hosszú ideig futó parancs időkorlátját másodpercekben. A rendszer a 0 alapértelmezett értéket használja a határozatlan ideig történő várakozáshoz.

Ügyfélerőforrás-felhasználás

Az exportálási és kinyerési parancsok esetében a rendszer a bacpac/dacpac fájlba való írás előtt átadja a táblázatadatokat egy ideiglenes könyvtárnak a puffereléshez. Előfordulhat, hogy ez a tárolási követelmény nagy, és az exportálandó adatok teljes méretéhez viszonyítva van. Adjon meg egy másik ideiglenes könyvtárat a /p:TempDirectoryForTableData=<path>tulajdonsággal.

A sémamodell a memóriában van lefordítva, így nagy adatbázissémák esetén az SqlPackage-t futtató ügyfélszámítógép memóriaigénye jelentős lehet.

Alacsony kiszolgálói erőforrás-felhasználás

Az SqlPackage alapértelmezés szerint 8-ra állítja a kiszolgáló párhuzamosságát. Ha alacsony kiszolgálói erőforrás-felhasználást jegyez fel, a MaxParallelism paraméter értékének növelése javíthatja a teljesítményt.

Access token

A /AccessToken: vagy /at: paraméter használata lehetővé teszi az SqlPackage jogkivonatalapú hitelesítését, azonban a jogkivonat parancsnak való átadása bonyolult lehet. Ha egy hozzáférési jogkivonat-objektumot elemez a PowerShellben, vagy explicit módon adja át a karakterlánc értékét, vagy csomagolja be a hivatkozást a token tulajdonságra $()-be. For example:

$Account = Connect-AzAccount -ServicePrincipal -Tenant $Tenant -Credential $Credential
$AccessToken_Object = (Get-AzAccessToken -Account $Account -Resource "https://database.windows.net/")
$AccessToken = $AccessToken_Object.Token

SqlPackage /at:$AccessToken
# OR
SqlPackage /at:$($AccessToken_Object.Token)

Connection

Ha az SqlPackage nem tud csatlakozni, előfordulhat, hogy a kiszolgáló nem engedélyezi a titkosítást, vagy a konfigurált tanúsítvány nem megbízható hitelesítésszolgáltatótól (például önaláírt tanúsítványtól) lett kiállítva. Az SqlPackage parancsot módosíthatja úgy, hogy titkosítás nélkül csatlakozzon, vagy megbízzon a kiszolgálótanúsítványban. A ajánlott eljárás, a kiszolgálóval való megbízható titkosított kapcsolat létesítése.

Csatlakozás titkosítás nélkül: /SourceEncryptConnection:False vagy /TargetEncryptConnection:False
Megbízható kiszolgálótanúsítvány: /SourceTrustServerCertificate:True vagy /TargetTrustServerCertificate:True

Az SQL-példányhoz való csatlakozáskor az alábbi figyelmeztető üzenetek bármelyike jelenhet meg, ami azt jelzi, hogy a parancssori paraméterek módosításokat igényelhetnek a kiszolgálóhoz való csatlakozáshoz:

The settings for connection encryption or server certificate trust may lead to connection failure if the server is not properly configured.
The connection string provided contains encryption settings which may lead to connection failure if the server is not properly configured.

Az SqlPackage kapcsolatbiztonsági változásairól további információt Az SqlPackage 161kapcsolatbiztonsági fejlesztései című cikkben talál.

Importálási műveleti hiba 2714 korlátozás esetén

Importálási művelet végrehajtásakor a 2714-s hiba jelenhet meg, ha már létezik objektum:

*** Error importing database:Could not import package.
Error SQL72014: Core Microsoft SqlClient Data Provider: Msg 2714, Level 16, State 5, Line 1 There is already an object named 'DF_Department_ModifiedDate_0FF0B724' in the database.
Error SQL72045: Script execution error. The executed script:
ALTER TABLE [HumanResources].[Department]
    ADD CONSTRAINT [DF_Department_ModifiedDate_] DEFAULT ('') FOR [ModifiedDate];

A következő okok és megoldások megkerülik ezt a hibát:

Ellenőrizze, hogy az importálni kívánt cél egy üres adatbázis-e.
Ha az adatbázis olyan korlátozásokkal rendelkezik, amelyek a DEFAULT attribútumot használják (ahol az SQL Server véletlenszerű nevet rendel a kényszerhez) és egy explicit névvel ellátott kényszert, akkor kétszer létrejön egy azonos nevű kényszer. A megnevezett kényszerek (a DEFAULT használata nélkül) vagy az összes rendszer által meghatározott név (a DEFAULT használatával) használatát kell választania.
Kézzel szerkessze a model.xml fájlt, és nevezze át a hibát okozó kényszert egyedi névre. Ezt a lehetőséget csak akkor lehet végrehajtani, ha a Microsoft ügyfélszolgálata utasítja, és fennáll a .bacpac megsérülésének kockázata.

Verem túlcsordulási hiba

A nagy méretű T-SQL szkriptek, amelyek sok beágyazott utasítást tartalmaznak, gyakran okoznak időszakos vagy állandó verem túlcsordulási kivételeket. Ebben az esetben a hibaüzenet tartalmazza a szöveg Stack overflow és a következő verem nyomkövetését:

Microsoft.SqlServer.TransactSql.ScriptDom.TSqlFragmentVisitor.Visit(Microsoft.SqlServer.TransactSql.ScriptDom.BinaryQueryExpression)
Microsoft.SqlServer.TransactSql.ScriptDom.TSqlFragmentVisitor.ExplicitVisit(Microsoft.SqlServer.TransactSql.ScriptDom.BinaryQueryExpression)
Microsoft.SqlServer.TransactSql.ScriptDom.BinaryQueryExpression.Accept(Microsoft.SqlServer.TransactSql.ScriptDom.TSqlFragmentVisitor)
Microsoft.SqlServer.TransactSql.ScriptDom.BinaryQueryExpression.AcceptChildren(Microsoft.SqlServer.TransactSql.ScriptDom.TSqlFragmentVisitor)
Microsoft.SqlServer.TransactSql.ScriptDom.BinaryQueryExpression.Accept(Microsoft.SqlServer.TransactSql.ScriptDom.TSqlFragmentVisitor)
Microsoft.SqlServer.TransactSql.ScriptDom.BinaryQueryExpression.AcceptChildren(Microsoft.SqlServer.TransactSql.ScriptDom.TSqlFragmentVisitor)

Az SqlPackage paramétere minden parancson elérhető, /ThreadMaxStackSize:, amely megadja az SqlPackage folyamatot futtató szál maximális veremméretét. Az alapértelmezett értéket az SqlPackage-t futtató .NET-verzió határozza meg. A nagy paraméterérték beállítása befolyásolhatja az SqlPackage teljesítményét, de az érték növelése megoldhatja a beágyazott utasítások által okozott veremtúlcsordulási hibát. A T-SQL-kód refaktorálása javasolt a verem túlcsordulásból adódó kivételek elkerülése érdekében, amikor csak lehetséges, de ideiglenes megoldásként a /ThreadMaxStackSize: paraméter használható fel.

A /ThreadMaxStackSize: paraméter használatakor ajánlott az ismétlődő műveleteket arra a legalacsonyabb értékre hangolni, amely megoldja a veremtúlcsordulás-kivételt, ha teljesítményromlás észlelhető. A paraméter értéke megabájtban (MB) van megadva, a teszteléshez kerülő megoldásként használt példaértékek közé tartozik a 10 és a 100.

Az importálási műveletekre vonatkozó tippek

A sok indexet tartalmazó nagy táblákat vagy táblákat tartalmazó importálások esetében a /p:RebuildIndexesOfflineForDataPhase=True vagy /p:DisableIndexesForDataPhase=False használata javíthatja a teljesítményt. Ezek a tulajdonságok úgy módosítják az index-újraépítési műveletet, hogy offline állapotban történjen, vagy ne történjen meg. Ezek és egyéb tulajdonságok a SqlPackage importálási művelet finomhangolásához érhetők el.

Exportálási műveleti tippek

Ahhoz, hogy az exportálás tranzakciós konzisztens legyen, győződjön meg arról, hogy az exportálás során nem történik írási tevékenység, vagy az adatbázis tranzakciósan konzisztens másolatából exportál. Az importálás során az idegenkulcs-korlátozásokra vonatkozó hibák azt jelezhetik, hogy az exportálás nem volt tranzakciós konzisztens az exportálási folyamat során beszúrt vagy frissített rekordok miatt.

Az exportálás során a teljesítménycsökkenés gyakori oka a megoldatlan objektumhivatkozások, ami miatt az SqlPackage többször megkísérli feloldani az objektumot. Például egy olyan nézet van definiálva, amely egy táblára hivatkozik, és a tábla már nem létezik az adatbázisban. Ha nem oldott hivatkozások jelennek meg az exportálási naplóban, érdemes lehet kijavítani az adatbázis sémáját az exportálási teljesítmény javítása érdekében.

Olyan esetekben, amikor az operációs rendszer lemezterülete korlátozott, és az exportálás során elfogy, a /p:TempDirectoryForTableData használata lehetővé teszi az adatok pufferelt exportálását egy másik lemezen. A művelethez szükséges terület nagy lehet, és az adatbázis teljes méretéhez viszonyítva van. Ez és más tulajdonságok is elérhetők az SqlPackage Exportálás művelet finomhangolásához.

Az exportálási folyamat során a rendszer tömöríti a táblaadatokat a bacpac-fájlban. A /p:CompressionOption értékének Fast, SuperFastvagy NotCompressed-ra állítása javíthatja az exportálási folyamat sebességét, miközben a kimeneti bacpac-fájl kevésbé van tömörítve.

Az adatbázisséma és -adatok beszerzéséhez a sémaérvényesítés kihagyásával hajtsa végre az Exportálást a /p:VerifyExtraction=Falsetulajdonsággal. Érvénytelen exportálás hozható létre, amely nem importálható.

Azure SQL Database

Az alábbi tippek az Azure SQL Database-beli importálás vagy exportálás Azure-beli virtuális gépről történő futtatására vonatkoznak:

A legjobb teljesítmény érdekében használja az üzletileg kritikus vagy prémium szintű adatbázist.
SSD-tároló használata a virtuális gépen.
Győződjön meg arról, hogy van elég hely a bacpac kibontásához.
Hajtsa végre az SqlPackage parancsot az adatbázissal azonos régióban lévő virtuális gépről.
Gyorsított hálózatkezelés engedélyezése a virtuális gépen.

Az importálási művelettel kapcsolatos további információk a PowerShell-szkriptek használatával kapcsolatban: Lecke # 211: Az SQLPackage importálási folyamatának figyelése.

More resources

Az Azure Database támogatási blogja számos cikket tartalmaz az Azure SQL Database hibaelhárításáról és teljesítményhangolásáról, köztük az SqlPackage-ről szóló cikkeket.

A legrelevánsabb cikkek közé tartoznak a következők:

Visszacsatolás

Hasznos volt ez az oldal?

Last updated on 2025-07-29