Utiliser des projets de style SDK SQL avec l’extension projets SQL Database (préversion)

Article
10/19/2023

Cet article présente Microsoft.Build.Sql pour les projets SQL de style SDK dans l’extension des projets SQL Database dans Azure Data Studio ou Visual Studio Code. Les projets de SQL de style SDK sont particulièrement avantageux pour les applications fournies via des pipelines ou des environnements multiplateformes intégrés. L’annonce initiale est disponible dans TechCommunity.

Notes

Microsoft.Build.Sql est en préversion.

Créer un projet de base de données de style SDK

Vous pouvez créer un projet de base de données de style SDK à partir d’un projet vide ou d’une base de données existante.

Projet vide

Dans la vue Database Projects, sélectionnez le bouton Nouveau projet et entrez un nom de projet dans l’entrée de texte qui s’affiche. Dans la boîte de dialogue Sélectionner un dossier qui s’affiche, choisissez un répertoire où doivent être placés le dossier du projet, le fichier .sqlproj et tout autre contenu.

Par défaut, la sélection du projet de style SDK (préversion) est cochée . Quand la boîte de dialogue est terminée, le projet vide est ouvert et visible dans la vue Database Projects à des fins de modifications.

à partir d’une base de données existante ;

Dans la vue Projet, sélectionnez le bouton Créer le projet à partir de la base de données et connectez-vous à un serveur SQL. Une fois la connexion établie, sélectionnez une base de données dans la liste des bases de données disponibles et définissez le nom du projet. Sélectionnez une structure cible pour l’extraction.

Par défaut, la sélection du projet de style SDK (préversion) est cochée . Lorsque le dialogue est terminé, le nouveau projet est ouvert et contient des scripts SQL pour le contenu de la base de données sélectionnée.

Générer et publier

À partir des interfaces Azure Data Studio et Visual Studio Code, la génération et la publication d’un projet de SQL de style SDK sont effectuées de la même façon que le format de projet SQL précédent. Pour plus d’informations sur ce processus, consultez Générer et publier un projet.

Pour générer un projet SQL de style kit de développement logiciel (SDK) à partir de la ligne de commande sur Windows, macOS ou Linux, utilisez la commande suivante :

dotnet build

Le fichier .dacpac résultant de la création d’un projet de style SDK SQL est compatible avec les outils associés à l’infrastructure d’application de la couche Données (.dacpac, .bacpacy compris SqlPackage et sql-action dans GitHub).

Fonctionnalités des projets

Dans les projets SQL, plusieurs fonctionnalités peuvent être spécifiées dans le fichier .sqlproj qui impactent le modèle de base de données au moment de la génération ou du déploiement du projet. Les sections suivantes décrivent certaines de ces fonctionnalités disponibles pour les projets Microsoft.Build.Sql.

Plateforme cible

La propriété de plateforme cible est contenue dans la balise DSP dans le fichier .sqlproj sous l’élément <PropertyGroup>. La plateforme cible est utilisée lors de la génération du projet pour valider la prise en charge des fonctionnalités incluses dans le projet et est ajoutée au fichier .dacpac en tant que propriété. Par défaut, pendant le déploiement, la plateforme cible est vérifiée par rapport à la base de données cible pour garantir la compatibilité. Si la plateforme cible n’est pas prise en charge par la base de données cible, le déploiement échoue, sauf si une option de publication de remplacement est spécifiée.

<Project DefaultTargets="Build">
  <Sdk Name="Microsoft.Build.Sql" Version="0.1.12-preview" />
  <PropertyGroup>
    <Name>AdventureWorks</Name>
    <DSP>Microsoft.Data.Tools.Schema.Sql.SqlAzureV12DatabaseSchemaProvider</DSP>
  </PropertyGroup>

Les paramètres valides pour la plateforme cible sont les suivants :

Microsoft.Data.Tools.Schema.Sql.Sql120DatabaseSchemaProvider
Microsoft.Data.Tools.Schema.Sql.Sql130DatabaseSchemaProvider
Microsoft.Data.Tools.Schema.Sql.Sql140DatabaseSchemaProvider
Microsoft.Data.Tools.Schema.Sql.Sql150DatabaseSchemaProvider
Microsoft.Data.Tools.Schema.Sql.Sql160DatabaseSchemaProvider
Microsoft.Data.Tools.Schema.Sql.SqlAzureV12DatabaseSchemaProvider
Microsoft.Data.Tools.Schema.Sql.SqlDwDatabaseSchemaProvider
Microsoft.Data.Tools.Schema.Sql.SqlServerlessDatabaseSchemaProvider
Microsoft.Data.Tools.Schema.Sql.SqlDwUnifiedDatabaseSchemaProvider

Références de base de données

La validation du modèle de base de données au moment de la génération peut être étendue au-delà du contenu du projet SQL par le biais de références de base de données. Les références de base de données spécifiées dans le fichier .sqlproj peuvent référencer un autre projet SQL ou un fichier .dacpac, représentant une autre base de données ou plusieurs composants de la même base de données.

Les attributs suivants sont disponibles pour les références de base de données qui représentent une autre base de données :

DatabaseSqlCmdVariable : la valeur est le nom de la variable utilisée pour référencer la base de données
- Paramètre de référence : <DatabaseSqlCmdVariable>SomeOtherDatabase</DatabaseSqlCmdVariable>
- Exemple d’utilisation : SELECT * FROM [$(SomeOtherDatabase)].dbo.Table1
ServerSqlCmdVariable : la valeur est le nom de la variable utilisée pour référencer le serveur où réside la base de données. Utilisé avec DatabaseSqlCmdVariable, quand la base de données se trouve sur un autre serveur.
- Paramètre de référence : <ServerSqlCmdVariable>SomeOtherServer</ServerSqlCmdVariable>
- Exemple d’utilisation : SELECT * FROM [$(SomeOtherServer)].[$(SomeOtherDatabase)].dbo.Table1
DatabaseVariableLiteralValue : la valeur est le nom littéral de la base de données tel qu’utilisé dans le projet SQL, similaire à DatabaseSqlCmdVariable, mais la référence à une autre base de données est une valeur littérale
- Paramètre de référence : <DatabaseVariableLiteralValue>SomeOtherDatabase</DatabaseVariableLiteralValue>
- Exemple d’utilisation : SELECT * FROM [SomeOtherDatabase].dbo.Table1

Dans un fichier projet SQL, une référence de base de données est spécifiée en tant qu’élément ArtifactReference avec l’attribut Include défini sur le chemin du fichier .dacpac.

  <ItemGroup>
    <ArtifactReference Include="SampleA.dacpac">
      <DatabaseSqlCmdVariable>DatabaseA</DatabaseSqlCmdVariable>
    </ArtifactReference>
  </ItemGroup>
</Project>

Références de package

Les références de package sont utilisées pour référencer des packages NuGet qui contiennent un fichier .dacpac et pour étendre le modèle de base de données au moment de la génération, à l’image d’une référence de base de données.

L’exemple suivant tiré d’un fichier projet SQL référence le Microsoft.SqlServer.Dacpacspackage pour la base de données master.

  <ItemGroup>
    <PackageReference Include="Microsoft.SqlServer.Dacpacs" Version="160.0.0" />
  </ItemGroup>
</Project>

En plus des attributs disponibles pour les références de base de données, l’attribut DacpacName suivant peut être spécifié pour sélectionner un fichier .dacpac dans un package qui contient plusieurs fichiers .dacpac.

  <ItemGroup>
    <PackageReference Include="Microsoft.SqlServer.Dacpacs" Version="160.0.0">
      <DacpacName>msdb</DacpacName>
    </PackageReference>
  </ItemGroup>
</Project>

Variables SqlCmd

Les variables SqlCmd peuvent être définies dans le fichier .sqlproj et sont utilisées pour remplacer les jetons dans les objets et scripts SQL pendant le.dacpac déploiement. L’exemple suivant tiré d’un fichier projet SQL définit une variable nommée EnvironmentName qui peut être utilisée dans les objets et les scripts du projet.

  <ItemGroup>
    <SqlCmdVariable Include="EnvironmentName">
      <DefaultValue>testing</DefaultValue>
      <Value>$(SqlCmdVar__1)</Value>
    </SqlCmdVariable>
  </ItemGroup>
</Project>

IF '$(EnvironmentName)' = 'testing'
BEGIN
    -- do something
END

Quand un projet SQL compilé (.dacpac) est déployé, la valeur de la variable est remplacée par la valeur spécifiée dans la commande de déploiement. Par exemple, la commande suivante déploie AdventureWorks.dacpac et définit la valeur de la variable EnvironmentName sur production.

SqlPackage /Action:Publish /SourceFile:AdventureWorks.dacpac /TargetConnectionString:{connection_string_here} /v:EnvironmentName=production

Scripts de pré/post-déploiement

Les scripts de pré-déploiement et de post-déploiement sont des scripts SQL inclus dans le projet à exécuter pendant le déploiement. Les scripts de pré/post-déploiement sont inclus dans le fichier .dacpac, mais ils ne sont pas compilés en un modèle objet de base de données ou validés avec un modèle objet de base de données. Un script de pré-déploiement est exécuté avant l’application du modèle de base de données, tandis qu’un script de post-déploiement est exécuté après. L’exemple suivant tiré d’un fichier projet SQL ajoute le fichier populate-app-settings.sql en tant que script de post-déploiement.

  <ItemGroup>
    <PostDeploy Include="populate-app-settings.sql" />
  </ItemGroup>
</Project>

Partager via