SqlPackage

  • Articolo

SqlPackage è un'utilità della riga di comando che automatizza le attività di sviluppo di database seguenti esponendo alcune delle API di DacFx (Data-Tier Application Framework) pubbliche:

  • Versione: restituisce il numero di build dell'applicazione SqlPackage.

  • Estrazione: crea un file dell'applicazione livello dati (con estensione dacpac) contenente lo schema o lo schema e i dati utente da un database SQL connesso.

  • Publish: aggiorna in modo incrementale uno schema di database affinché corrisponda allo schema di un file di origine con estensione dacpac. Se il database non esiste nel server, l'operazione di pubblicazione lo crea. In caso contrario, verrà aggiornato un database esistente.

  • Esportazione: esporta un database SQL connesso, inclusi lo schema del database e i dati utente, in un file BACPAC (con estensione bacpac).

  • Importazione: importa lo schema e i dati della tabella da un file BACPAC in un nuovo database utente.

  • DeployReport: crea un report XML che rappresenta le modifiche che verrà eseguita da un'azione di pubblicazione.

  • DriftReport: crea un report XML che rappresenta le modifiche applicate a un database registrato dall'ultima registrazione.

  • Script: crea uno script di aggiornamento incrementale Transact-SQL che aggiorna lo schema di una destinazione affinché corrisponda allo schema di un'origine.

Lo strumento da riga di comando SqlPackage consente di specificare queste azioni insieme a parametri e proprietà specifiche dell'azione.

Scaricare la versione più recente. Per informazioni dettagliate sulla versione più recente, vedere le note sulla versione.

Nota

Anche se Microsoft Entra ID è il nuovo nome per Azure Active Directory (Azure AD), per evitare l'interruzione degli ambienti esistenti, Azure AD rimane ancora in alcuni elementi codificati, ad esempio campi dell'interfaccia utente, provider di connessioni, codici di errore e cmdlet. In questo articolo i due nomi sono intercambiabili.

Sintassi della riga di comando

SqlPackage avvia le azioni specificate usando i parametri, le proprietà e le variabili SQLCMD specificati nella riga di comando.

SqlPackage {parameters} {properties} {SQLCMD variables}

Codici di uscita

I comandi SqlPackage restituiscono i codici di uscita seguenti:

  • 0 = esito positivo
  • diverso da zero = errore

Esempio di utilizzo

Altri esempi sono disponibili nelle pagine delle singole azioni.

Creazione di un file con estensione dacpac dello schema di database corrente:

SqlPackage /TargetFile:"C:\sqlpackageoutput\output_current_version.dacpac" /Action:Extract /SourceServerName:"." /SourceDatabaseName:"Contoso.Database"

Parametri

Alcuni parametri vengono condivisi tra le azioni SqlPackage. Di seguito è riportata una tabella che riepiloga i parametri, per altre informazioni, fare clic nelle pagine di azione specifiche.

Parametro Forma breve Extract Pubblicazione Export Importa DeployReport DriftReport Script
/AccessToken: /at x x x x x x x
/ClientId: /cid x
/DeployScriptPath: /dsp x x
/DeployReportPath: /drp x x
/Diagnostics: /d x x x x x x x
/DiagnosticsFile: /df x x x x x x x
/MaxParallelism: /mp x x x x x x x
/OutputPath: /op x x x
/OverwriteFiles: /of x x x x x x
/Profile: /pr x x x
/Properties: /p x x x x x x
/Quiet: /q x x x x x x x
/Secret: /secr x
/SourceConnectionString: /scs x x x x x
/SourceDatabaseName: /sdn x x x x x
/SourceEncryptConnection: /sec x x x x x
/SourceFile: /sf x x x x
/SourcePassword: /sp x x x x x
/SourceServerName: /ssn x x x x x
/SourceTimeout: /st x x x x x
/SourceTrustServerCertificate: /stsc x x x x x
/SourceUser: /su x x x x x
/TargetConnectionString: /tcs x x x x
/TargetDatabaseName: /tdn x x x x x
/TargetEncryptConnection: /tec x x x x x
/TargetFile: /tf x x x x
/TargetPassword: /tp x x x x x
/TargetServerName: /tsn x x x x x
/TargetTimeout: /tt x x x x x
/TargetTrustServerCertificate: /ttsc x x x x x
/TargetUser: /tu x x x x x
/TenantId: /tid x x x x x x x
/UniversalAuthentication: /ua x x x x x x x
/Variables: /v x x

Proprietà

Le azioni SqlPackage supportano un numero elevato di proprietà per modificare il comportamento predefinito di un'azione. Per altre informazioni, fare clic sulle pagine di azione specifiche.

Comandi di utilità

Versione

Visualizza la versione di sqlpackage come numero di build. Può essere usato nei prompt interattivi e nelle pipeline automatizzate.

SqlPackage /Version

Icona ?

È possibile visualizzare le informazioni sull'utilizzo di SqlPackage usando /? o /help:True.

SqlPackage /?

Per informazioni sui parametri e sulle proprietà specifici di una determinata azione, usare il parametro della Guida oltre al parametro dell'azione.

SqlPackage /Action:Publish /?

Autenticazione

SqlPackage esegue l'autenticazione usando metodi disponibili in SqlClient. La configurazione del tipo di autenticazione può essere eseguita tramite i parametri stringa di connessione per ogni azione SqlPackage (/SourceConnectionString e /TargetConnectionString) o tramite singoli parametri per le proprietà di connessione. In un stringa di connessione sono supportati i metodi di autenticazione seguenti:

  • Autenticazione di SQL Server
  • Autenticazione di Active Directory (Windows)
  • Autenticazione Microsoft Entra
    • Nome utente e password
    • Autenticazione integrata
    • Autenticazione universale
    • Identità gestita
    • Entità servizio

Identità gestita

Nota

Microsoft Entra ID era precedentemente noto come Azure Active Directory (Azure AD).

Negli ambienti automatizzati, l'identità gestita di Microsoft Entra è il metodo di autenticazione consigliato. Questo metodo non richiede il passaggio di credenziali a SqlPackage in fase di esecuzione. Quando l'identità gestita è configurata per l'ambiente in cui viene eseguita l'azione SqlPackage, l'azione SqlPackage può usare tale identità per l'autenticazione in Azure SQL. Per altre informazioni sulla configurazione di un'identità gestita per l'ambiente, vedere la documentazione sull'identità gestita.

Un esempio stringa di connessione l'uso dell'identità gestita assegnata dal sistema è:

Server=sampleserver.database.windows.net; Authentication=Active Directory Managed Identity; Database=sampledatabase;

Variabili di ambiente

Pool di connessioni

Connessione pooling può essere abilitato per tutte le connessioni effettuate da SqlPackage impostando la CONNECTION_POOLING_ENABLED variabile di ambiente su True. Questa impostazione è consigliata per le operazioni con le connessioni con nome utente e password di Microsoft Entra per evitare la limitazione da parte di Microsoft Authentication Library (MSAL).

File temporanei

Durante le operazioni di SqlPackage, i dati della tabella vengono scritti in file temporanei prima della compressione o dopo la decompressione. Per i database di grandi dimensioni, questi file temporanei possono richiedere una quantità significativa di spazio su disco, ma è possibile specificarne la posizione. Le operazioni di esportazione ed estrazione includono una proprietà facoltativa da specificare /p:TempDirectoryForTableData per eseguire l'override del valore predefinito di SqlPackage.

L'API .NET GetTempPath viene usata per determinare il valore predefinito all'interno di SqlPackage.

Per Windows, le variabili di ambiente seguenti vengono controllate nell'ordine seguente e viene usato il primo percorso esistente:

  1. Percorso specificato dalla variabile di TMP ambiente.
  2. Percorso specificato dalla variabile di TEMP ambiente.
  3. Percorso specificato dalla variabile di USERPROFILE ambiente.
  4. Directory di Windows.

Per Linux e macOS, se il percorso non è specificato nella TMPDIR variabile di ambiente, viene usato il percorso /tmp/ predefinito.

SqlPackage e utenti di database

Gli utenti di database indipendenti sono inclusi nelle operazioni SqlPackage. Tuttavia, la parte della password della definizione viene impostata su una stringa generata in modo casuale da SqlPackage, il valore esistente non viene trasferito. È consigliabile reimpostare la password del nuovo utente in un valore sicuro dopo l'importazione di un .bacpac oggetto o la distribuzione di un oggetto .dacpac. In un ambiente automatizzato i valori delle password possono essere recuperati da un archivio chiavi sicuro, ad esempio Azure Key Vault, in un passaggio successivo all'esecuzione di SqlPackage.

Raccolta dati di utilizzo

SqlPackage contiene funzionalità abilitate per Internet che possono raccogliere e inviare dati di diagnostica e utilizzo anonimi delle funzionalità a Microsoft.

SqlPackage può raccogliere informazioni standard su computer, uso e prestazioni che possono essere trasmesse a Microsoft e analizzate per migliorare la qualità, la sicurezza e l'affidabilità di SqlPackage.

SqlPackage non raccoglie informazioni personali o specifiche dell'utente. Per semplificare l'approssimazione di un singolo utente a scopo di diagnostica, SqlPackage genera un GUID casuale per ogni computer in cui viene eseguito e usa tale valore per tutti gli eventi inviati.

Per informazioni dettagliate, vedere l'Informativa sulla privacy di Microsoft e Supplemento alla privacy di SQL Server.

Disabilitare la creazione di report di telemetria

Per disabilitare la raccolta e la creazione di report di telemetria, aggiornare la variabile DACFX_TELEMETRY_OPTOUT di ambiente a true o 1.

Supporto tecnico

La libreria DacFx e lo strumento dell'interfaccia della riga di comando SqlPackage hanno adottato i criteri del ciclo di vita moderni Microsoft. Tutti gli aggiornamenti, le correzioni e le nuove funzionalità di sicurezza vengono rilasciati solo nella versione più recente della versione principale. La gestione delle installazioni dacFx o SqlPackage nella versione corrente consente di assicurarsi di ricevere tutte le correzioni di bug applicabili in modo tempestivo.

Ottenere assistenza con SqlPackage, inviare richieste di funzionalità e segnalare i problemi nel repository GitHub di DacFx.

Offerte di SQL supportate

SqlPackage e DacFx supportano tutte le versioni SQL supportate al momento della versione SqlPackage/DacFx. Ad esempio, una versione di SqlPackage il 14 gennaio 2022 supporta tutte le versioni supportate di SQL nel 14 gennaio 2022. Per altre informazioni sui criteri di supporto per SQL, vedere i criteri di supporto per SQL.

Passaggi successivi