Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
La libreria .NET Data-tier Application Framework (DacFx) fornisce punti di estendibilità che è possibile utilizzare per modificare il comportamento delle azioni di compilazione e distribuzione per i progetti di database.
- Compilazione (BuildContributor): Questo tipo di estensione viene eseguito quando il progetto SQL viene compilato dopo la convalida completa del modello di progetto. Il collaboratore alla compilazione può accedere al modello completato, oltre a tutte le proprietà dell'attività di compilazione e a qualsiasi argomento personalizzato.
- Deploy (DeploymentPlanModifier): Questo tipo di estensione viene eseguito quando il progetto SQL viene distribuito, come parte della pipeline di distribuzione, dopo la generazione del piano di distribuzione, ma prima dell'esecuzione del piano di distribuzione. È possibile utilizzare DeploymentPlanModifier per modificare il piano di distribuzione aggiungendo o rimuovendo passaggi. I collaboratori alla distribuzione possono accedere al piano di distribuzione, ai risultati del confronto e ai modelli di origine e destinazione.
- Deploy (DeploymentPlanExecutor): Questo tipo di estensione viene eseguito quando il piano di distribuzione viene eseguito e fornisce accesso in sola lettura al piano di distribuzione. DeploymentPlanExecutor esegue azioni in base al piano di distribuzione.
Scenari di estendibilità di esempio
È possibile implementare i collaboratori alla compilazione o distribuzione per consentire gli scenari di esempio seguenti:
- Generare la documentazione dello schema durante una compilazione del progetto: per supportare questo scenario, implementare un elemento BuildContributor ed eseguire l'override del metodo OnExecute per generare la documentazione dello schema. È possibile creare un file targets che definisce gli argomenti predefiniti che controllano se l'estensione viene eseguita e per specificare il nome del file di output.
- Generare un report delle differenze quando un progetto SQL viene distribuito: per supportare questo scenario, implementare DeploymentPlanExecutor che genera il file XML quando viene distribuito il progetto SQL.
- Modificare il piano di distribuzione per modificare quando viene effettuato lo spostamento dei dati: per supportare questo scenario, implementare DeploymentPlanModifier ed eseguire l'iterazione del piano di distribuzione. Per ogni SqlTableMigrationStep nel piano, esaminate il risultato del confronto per determinare se la fase deve essere eseguita o ignorata.
- Copiare i file nel dacpac generato quando viene distribuito un progetto SQL: per supportare questo scenario, implementare un collaboratore alla distribuzione ed eseguire l'override del metodo OnEstablishDeploymentConfiguration per specificare quali file sono contrassegnati come DeploymentExtensionConfiguration dal sistema del progetto. Questi file devono essere copiati nella cartella di output e aggiunti all'interno del dacpac generato. È anche possibile modificare il collaboratore per unire più file in un nuovo file copiato nella cartella di output e aggiunto al manifesto di distribuzione. Durante la distribuzione, è possibile implementare il metodo OnApplyDeploymentConfiguration per estrarre questi file da dacpac e prepararli per l'utilizzo nel metodo OnExecute.
Un collaboratore può accettare input in fase di esecuzione come coppie di argomenti nome/valore. Questi argomenti consentono agli utenti finali in fase di compilazione o distribuzione di personalizzare il comportamento del collaboratore. Ad esempio, è possibile consentire agli utenti di specificare il nome di un file di input o di output o di controllare la selezione di oggetti del modello.
Contributori all'implementazione
Il processo di distribuzione per i progetti SQL supporta l'estendibilità tramite collaboratori alla distribuzione, che accedono al piano di distribuzione e possono modificarlo (DeploymentPlanModifier) o implementare un'azione basata sul piano (DeploymentPlanExecutor). I collaboratori alla distribuzione possono accedere al piano di distribuzione, ai risultati del confronto e ai modelli di origine e destinazione. Con DeploymentPlanModifier è possibile usare i collaboratori alla distribuzione per aggiungere o rimuovere passaggi dal piano di distribuzione o per modificare i passaggi nel piano di distribuzione. DeploymentPlanModifiers sono i contributori di distribuzione più frequentemente usati.
I collaboratori alla distribuzione sono riutilizzabili tramite la parametrizzazione e possono essere usati in più progetti. Oltre agli esempi archiviati per DacExtensions, i membri della community hanno creato e condiviso i propri collaboratori di distribuzione riutilizzabili come progetti open source.
Integrazione di SqlPackage
SqlPackage è un'utilità della riga di comando che può essere usata per creare e distribuire progetti SQL. Se usato con SqlPackage, i collaboratori alla distribuzione personalizzano il processo di pubblicazione e possono essere specificati con le proprietà nell'azione di pubblicazione, ad esempio /p:AdditionalDeploymentContributors. I collaboratori alla distribuzione devono trovarsi in un percorso accessibile a SqlPackage, ad esempio la stessa cartella dell'eseguibile sqlPackage o in una cartella specificata nella proprietà /p:AdditionalDeploymentContributorPaths. Per altre informazioni sull'azione di pubblicazione e sulle proprietà che è possibile usare per specificare i collaboratori alla distribuzione, vedere Pubblicazione di SqlPackage.
I collaboratori alla distribuzione devono essere compilati con la stessa versione principale della libreria DacFx di SqlPackage in questi scenari:
- Uso della versione .NET Framework di SqlPackage, che richiede una versione principale corrispondente al collaboratore alla distribuzione.
- Quando SqlPackage viene aggiornato con definizioni api della libreria DacFx modificate, che possono passare dalla versione alla versione. Le modifiche di rilievo sono limitate agli aggiornamenti delle versioni principali.
Se un collaboratore alla distribuzione non è compilato con una versione compatibile di DacFx, l'operazione SqlPackage avrà esito negativo quando si tenta di caricare l'estensione in fase di esecuzione. Quando un collaboratore alla distribuzione non viene caricato in SqlPackage, verrà visualizzato un messaggio di errore simile al seguente:
Could not load extensions from file 'D:\a\_work\....dll' because the assembly has dependency to older versions of DacFx. For more information check https://aka.ms/sqlprojects-extensions
Error SQL0: Required contributor with id 'MyCompany.MyExtension' could not be loaded.
System.Management.Automation.RemoteException
Contributor initialization error.
Quando si integrano i collaboratori alla distribuzione con SqlPackage nelle pipeline di automazione, è consigliabile gestire la versione di SqlPackage installata nell'agente di compilazione. La gestione dell'installazione di SqlPackage consente di assicurarsi che corrisponda alla versione della libreria DacFx usata per compilare i collaboratori alla distribuzione. Per una maggiore flessibilità, usare lo strumento dotnet Microsoft.SqlPackage anziché .NET Framework SqlPackage. Per altre informazioni su come installare SqlPackage nell'agente di compilazione dall'interno del flusso di lavoro se l'ambiente non può essere modificato, vedere l'articolo SqlPackage nelle pipeline di sviluppo .