Sdílet prostřednictvím

Rozšiřitelnost projektů SQL

Knihovna .NET Data-tier Application Framework (DacFx) poskytuje body rozšiřitelnosti, které můžete použít k úpravě chování akcí sestavení a nasazení pro databázové projekty.

  • Sestavení (BuildContributor): Tento typ rozšíření se spustí při sestavení projektu SQL po úplném ověření modelu projektu. Přispěvatel sestavení má kromě všech vlastností úlohy sestavení a všech vlastních argumentů přístup k dokončeného modelu.
  • Nasazení (DeploymentPlanModifier): Tento typ rozšíření se spustí při nasazení projektu SQL v rámci kanálu nasazení po vygenerování plánu nasazení, ale před spuštěním plánu nasazení. Plán nasazení můžete upravit přidáním nebo odebráním kroků. Přispěvatelé nasazení mají přístup k plánu nasazení, výsledkům porovnání a zdrojovým a cílovým modelům.
  • Nasazení (DeploymentPlanExecutor): Tento typ rozšíření se spustí při spuštění plánu nasazení a poskytuje přístup k plánu nasazení jen pro čtení. DeploymentPlanExecutor provádí akce na základě plánu nasazení.

Příklady scénářů rozšiřitelnosti

K povolení následujících ukázkových scénářů můžete implementovat přispěvatele sestavení nebo nasazení:

  • Generování dokumentace schématu během sestavení projektu – pro podporu tohoto scénáře implementujete BuildContributor a přepíšete metodu OnExecute pro vygenerování dokumentace schématu. Můžete vytvořit cílový soubor, který definuje výchozí argumenty, které určují, jestli se přípona spustí, a zadat název výstupního souboru.
  • Generování sestavy rozdílů při nasazení projektu SQL – Pro podporu tohoto scénáře implementujete DeploymentPlanExecutor , který při nasazení projektu SQL vygeneruje soubor XML.
  • Upravte plán nasazení tak, aby se změnil, když dojde k pohybu dat – pro podporu tohoto scénáře implementujete DeploymentPlanModifier a iterujete plán nasazení. Pro každý sqlTableMigrationStep v daném plánu prozkoumáte výsledek porovnání a zjistěte, jestli se má tento krok provést nebo přeskočit.
  • Zkopírujte soubory do vygenerovaného souboru dacpac při nasazení projektu SQL – pro podporu tohoto scénáře implementujete přispěvatele nasazení a přepíšete metodu OnEstablishDeploymentConfiguration, abyste určili, které soubory jsou označené jako DeploymentExtensionConfiguration systémem projektu. Tyto soubory by se měly zkopírovat do výstupní složky a přidat do vygenerovaného souboru dacpac. Přispěvatel můžete také upravit tak, aby sloučil více souborů do jednoho nového souboru, který se zkopíruje do výstupní složky a přidá se do manifestu nasazení. Během nasazování můžete implementovat onApplyDeploymentConfiguration metoda extrahovat tyto soubory z dacpac a připravit je na použití v OnExecute metoda.

Přispěvatel může přijmout vstup během běhu programu ve formě dvojic argumentů název/hodnota. Tyto argumenty umožňují koncovým uživatelům v době sestavení nebo nasazení přizpůsobit chování přispěvatele. Můžete například umožnit uživatelům zadat název vstupního nebo výstupního souboru nebo řídit výběr objektů z modelu.

Přispěvatelé nasazení

Proces nasazení pro projekty SQL podporuje rozšiřitelnost prostřednictvím přispěvatelů nasazení, kteří přistupují k plánu nasazení a mohou ho upravit (DeploymentPlanModifier) nebo implementovat akci na základě plánu (DeploymentPlanExecutor). Přispěvatelé nasazení mají přístup k plánu nasazení, výsledkům porovnání a zdrojovým a cílovým modelům. Pomocí DeploymentPlanModifier můžete pomocí přispěvatelů nasazení přidat nebo odebrat kroky z plánu nasazení nebo upravit kroky v plánu nasazení. DeploymentPlanModifiers jsou nejčastěji používanými přispěvateli nasazení.

Snímek obrazovky s procesem nasazení DacFx, kde se plán nasazení počítá z rozdílů v modelu a upravený přispěvatelem nasazení

Přispěvatelé pro nasazení mohou být opakovaně použiti díky parameterizaci a mohou být využiti ve více projektech. Vedle archivovaných ukázek pro DacExtensions vytvořili a sdíleli členové komunity své vlastní znovupoužitelné příspěvky pro nasazení jako open-source projekty.

Integrace SqlPackage

SqlPackage je nástroj příkazového řádku, který lze použít k vytváření a nasazování projektů SQL. Při použití s SqlPackage přispěvatelé nasazení přizpůsobí proces publikování a mohou být zadány s vlastnostmi akce publikování, například /p:AdditionalDeploymentContributors. Přispěvatelé nasazení musí být v umístění, které je přístupné pro SqlPackage, jako je například stejná složka jako spustitelný soubor SqlPackage nebo ve složce, která je zadána ve vlastnosti /p:AdditionalDeploymentContributorPaths. Další informace o akci publikování a vlastnostech, které můžete použít k určení přispěvatelů nasazení, naleznete v tématu SqlPackage Publish.

Účastníci nasazení musí být sestaveni se stejnou hlavní verzí knihovny DacFx jako SqlPackage v těchto scénářích:

  • Použití verze sqlPackage rozhraní .NET Framework, která vyžaduje shodu hlavní verze s přispěvatelem nasazení.
  • Když se SqlPackage aktualizuje pomocí upravených definic rozhraní API knihovny DacFx, které se můžou změnit z verze na verzi. Zásadní změny jsou omezené na aktualizace hlavní verze.

Pokud není přispěvatel nasazení sestavený s kompatibilní verzí DacFx, operace SqlPackage selže při pokusu o načtení rozšíření za běhu. Pokud se v SqlPackage nepodaří načíst komponenta nasazení, zobrazí se chybová zpráva podobná následující:

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.

Při integraci přispěvatelů nasazení s SqlPackage v kanálech automatizace zvažte správu verze SqlPackage nainstalované v agentu sestavení. Správa instalace SqlPackage vám umožňuje zajistit, že odpovídá verzi knihovny DacFx použité při vytváření vašich komponent nasazení. Pro větší flexibilitu použijte nástroj dotnet Microsoft.SqlPackage místo .NET Framework SqlPackage. Další informace o tom, jak nainstalovat SqlPackage v rámci pracovního toku v agentovi sestavení, pokud prostředí nelze změnit, najdete tak, že se podíváte na článek SqlPackage ve vývojových kanálech.

Související obsah

  • Last updated on