Uso de proyectos de SQL de estilo SDK con la extensión SQL Database Projects (versión preliminar)

Artículo
10/19/2023

En este artículo se presenta Microsoft.Build.Sql para proyectos de SQL de estilo SDK en la extensión SQL Database Projects en Azure Data Studio o Visual Studio Code. Los proyectos de SQL de estilo SDK son especialmente ventajosos para las aplicaciones enviadas a través de canalizaciones o entornos multiplataforma integrados. El anuncio inicial está disponible en TechCommunity.

Nota

Microsoft.Build.Sql se encuentra actualmente en una versión preliminar.

Creación de un proyecto de base de datos de estilo SDK

Puede crear un proyecto de base de datos de estilo SDK a partir de un proyecto en blanco o desde una base de datos existente.

Proyecto en blanco

En la vista Proyectos de base de datos, seleccione el botón Nuevo proyecto y escriba un nombre de proyecto en la entrada de texto que aparece. En el cuadro de diálogo Seleccionar una carpeta que aparece, seleccione un directorio para guardar la carpeta del proyecto, el archivo .sqlproj y el resto del contenido.

De forma predeterminada, se comprueba la selección del proyecto de estilo SDK (versión preliminar). Una vez completado el cuadro de diálogo, el proyecto vacío se abre y aparece en la vista Proyectos de base de datos para su edición.

De una base de datos existente

En la vista Proyecto, seleccione el botón Crear proyecto a partir de base de datos y conéctese a un servidor de SQL. Una vez que se haya establecido la conexión, seleccione una base de datos en la lista de bases de datos disponibles y establezca el nombre del proyecto. Seleccione una estructura de destino para la extracción.

De forma predeterminada, se comprueba la selección del proyecto de estilo SDK (versión preliminar). Una vez completado el cuadro de diálogo, el nuevo proyecto se abre y contiene scripts de SQL para el contenido de la base de datos seleccionada.

Compilación y publicación

Desde las interfaces de Azure Data Studio y Visual Studio Code, la compilación y publicación de un proyecto de SQL de estilo SDK se completa de la misma manera que el formato de proyecto de SQL anterior. Para más información sobre este proceso, consulte Compilación y publicación de un proyecto.

Para crear un proyecto SQL de estilo SDK desde la línea de comandos en Windows, macOS o Linux, use el siguiente comando:

dotnet build

El archivo .dacpac resultante de la creación de un proyecto de SQL de estilo SDK es compatible con las herramientas asociadas al marco de trabajo de la aplicación de capa de datos (.dacpac, .bacpac), incluidos SqlPackage y sql-action, de GitHub.

Capacidades del proyecto

En los proyectos de SQL existen varias funcionalidades que se pueden especificar en el archivo .sqlproj, las cuales afectan al modelo de base de datos en la compilación o la implementación del proyecto. En las secciones siguientes se describen algunas de estas funcionalidades disponibles para los proyectos de Microsoft.Build.Sql.

Plataforma de destino

La propiedad de la plataforma de destino se encuentra en la etiqueta DSP del archivo .sqlproj, en el elemento <PropertyGroup>. La plataforma de destino se usa durante la compilación del proyecto para validar la compatibilidad con las características incluidas en el proyecto y se agrega al archivo .dacpac como una propiedad. De forma predeterminada, la plataforma de destino se compara con la base de datos de destino durante la implementación para garantizar la compatibilidad. Si la base de datos de destino no admite la plataforma de destino, se produce un error en la implementación a menos que se especifique una opción de publicación de invalidación.

<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>

La configuración válida para la plataforma de destino es:

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

Referencias de base de datos

La validación del modelo de base de datos durante el tiempo de compilación puede extenderse más allá del contenido del proyecto de SQL mediante referencias de base de datos. Las referencias de base de datos especificadas en el archivo .sqlproj pueden referenciar a otro proyecto de SQL o a un archivo .dacpac, el cual representa otra base de datos o más componentes de la misma base de datos.

Los atributos siguientes están disponibles para las referencias de base de datos que representan otra base de datos:

DatabaseSqlCmdVariable: el valor es el nombre de la variable que se usa para hacer referencia a la base de datos
- Configuración de referencia: <DatabaseSqlCmdVariable>SomeOtherDatabase</DatabaseSqlCmdVariable>
- Ejemplo de uso: SELECT * FROM [$(SomeOtherDatabase)].dbo.Table1
ServerSqlCmdVariable: el valor es el nombre de la variable que se usa para hacer referencia al servidor donde se ubica la base de datos. Se usa con DatabaseSqlCmdVariable cuando la base de datos está ubicada en otro servidor.
- Configuración de referencia: <ServerSqlCmdVariable>SomeOtherServer</ServerSqlCmdVariable>
- Ejemplo de uso: SELECT * FROM [$(SomeOtherServer)].[$(SomeOtherDatabase)].dbo.Table1
DatabaseVariableLiteralValue: el valor es el nombre literal de la base de datos tal y como se usa en el proyecto de SQL. Es similar a DatabaseSqlCmdVariable, pero la referencia a otra base de datos es un valor literal
- Configuración de referencia: <DatabaseVariableLiteralValue>SomeOtherDatabase</DatabaseVariableLiteralValue>
- Ejemplo de uso: SELECT * FROM [SomeOtherDatabase].dbo.Table1

En un archivo de proyecto de SQL, una referencia de base de datos se especifica como un elemento ArtifactReference con el atributo Include establecido en la ruta de acceso del archivo .dacpac.

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

Referencias de paquete

Las referencias de paquetes se usan para hacer referencia a paquetes NuGet que contienen un archivo .dacpac y para ampliar el modelo de base de datos durante el tiempo de compilación de forma similar a una referencia de base de datos.

En el ejemplo siguiente de un archivo de proyecto de SQL se hace referencia al paquete Microsoft.SqlServer.Dacpacs de la base de datos master.

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

Además de los atributos disponibles para las referencias de base de datos, se puede especificar el siguiente atributo DacpacName para seleccionar un .dacpac de un paquete que contenga varios archivos .dacpac.

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

Variables SQLCMD

Las variables SqlCmd se pueden definir en el archivo .sqlproj y se usan para reemplazar tokens en objetos y scripts de SQL durante la implementación .dacpac. En el ejemplo siguiente de un archivo de proyecto de SQL se define una variable denominada EnvironmentName que está disponible para su uso en los objetos y scripts del proyecto.

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

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

Cuando se implementa un proyecto de SQL compilado (.dacpac), el valor de la variable se reemplaza por el valor especificado en el comando de implementación. Por ejemplo, el comando siguiente implementa AdventureWorks.dacpac y establece el valor de la variable EnvironmentName en production.

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

Scripts previos y posteriores a la implementación

Los scripts previos y posteriores a la implementación son scripts de SQL que se incluyen en el proyecto y se ejecutan durante la implementación. Los scripts previos y posteriores a la implementación se incluyen en .dacpac, pero no se compilan ni se validan con el modelo de objetos de la base de datos. Se ejecuta un script anterior a la implementación antes de aplicar el modelo de base de datos. Se ejecuta un script posterior a la implementación tras aplicar el modelo de base de datos. En el ejemplo siguiente de un archivo de proyecto de SQL se agrega el archivo populate-app-settings.sql como script posterior a la implementación.

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

Compartir vía