Conversión de un proyecto SQL original a un proyecto de estilo SDK

Se aplica a:SQL ServerAzure SQL DatabaseInstancia administrada de Azure SQLBase de datos SQL en Microsoft Fabric

La creación de un nuevo proyecto SQL de estilo SDK es una tarea rápida. Sin embargo, si tienes proyectos SQL existentes, puedes convertirlos en proyectos SQL tipo SDK para aprovechar las nuevas funciones.

Después de convertir el proyecto, puedes usar las nuevas funciones del proyecto estilo SDK, tales como:

• Soporte para compilaciones multiplataforma
• Formato simplificado de archivo de proyecto
• Referencias de paquete

Para completar la conversión con cuidado, sigue estos pasos:

1. Crear una copia de seguridad del archivo de proyecto original.
2. Compilar un archivo .dacpac a partir del proyecto original para su comparación.
3. Modificar el archivo de proyecto para que sea un proyecto de estilo SDK.
4. Compilar un archivo .dacpac a partir del proyecto modificado para su comparación.
5. Comprobar que los archivos .dacpac son los mismos.

SQL Server Data Tools (SSDT) en Visual Studio no soporta proyectos tipo SDK. Después de convertir el proyecto, utiliza una de las siguientes herramientas para construir o editar el proyecto:

• La extensión SQL Database Projects en Visual Studio Code
• DevOps de bases de datos en SQL Server Management Studio (SSMS)
• La línea de comandos
• SQL Server Data Tools de estilo SDK (vista previa) en Visual Studio 2022

Prerequisites

Paso 1: cree una copia de seguridad del archivo de proyecto original

Antes de convertir el proyecto, cree una copia de seguridad del archivo de proyecto original. De este modo, puede revertir al proyecto original si es necesario.

En el Explorador de archivos, crea una copia del .sqlproj archivo del proyecto que quieres convertir añadida .original a la extensión del archivo. Por ejemplo, MyProject.sqlproj se convierte en MyProject.sqlproj.original.

Paso 2: compile un archivo .dacpac a partir del proyecto original para su comparación

dotnet build

# optionally specify the project file
dotnet build MyDatabaseProject.sqlproj

El proceso de compilación crea un archivo .dacpac en la carpeta bin\Debug del proyecto de manera predeterminada. Con el Explorador de archivos, localiza el .dacpac creado por el proceso de compilación y cópialo en una nueva carpeta fuera del directorio del proyecto con el nombre original_project.dacpac. Usa este .dacpac archivo para comparar y validar tu conversión más adelante.

Paso 3: modifique el archivo de proyecto para que sea un proyecto de estilo SDK

Modificar el archivo del proyecto es un proceso manual, que es mejor realizar en un editor de texto. Abra el archivo .sqlproj en un editor de texto y realice los siguientes cambios:

Obligatorio: añada la referencia del SDK

Dentro del elemento del proyecto, agregue un elemento Sdk para hacer referencia a Microsoft.Build.Sql y a la versión más reciente desde https://www.nuget.org/packages/Microsoft.build.sql, donde #.#.# se incluye en el fragmento de código siguiente.

<?xml version="1.0" encoding="utf-8"?>
<Project DefaultTargets="Build" ToolsVersion="4.0">
  <Sdk Name="Microsoft.Build.Sql" Version="#.#.#" />
...

Obligatorio: eliminar las importaciones de destino de compilación innecesarias

Los proyectos SQL originales hacen referencia a varios destinos de compilación y propiedades en instrucciones de importación. Excepto para los elementos <Import/> que haya agregado explícitamente, que son cambios únicos y deliberados, elimine las líneas que comienzan por <Import ...>. Ejemplos de elementos a eliminar si están presentes en .sqlproj:

...
<Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props" Condition="Exists('$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props')" />
<Import Condition="..." Project="...\Microsoft.Data.Tools.Schema.SqlTasks.targets"/>
<Import Condition="'$(SQLDBExtensionsRefPath)' != ''" Project="$(SQLDBExtensionsRefPath)\Microsoft.Data.Tools.Schema.SqlTasks.targets" />
<Import Condition="'$(SQLDBExtensionsRefPath)' == ''" Project="$(MSBuildExtensionsPath)\Microsoft\VisualStudio\v$(VisualStudioVersion)\SSDT\Microsoft.Data.Tools.Schema.SqlTasks.targets" />
...

Obligatorio: elimine la carpeta Propiedades

Los proyectos SQL originales tienen una entrada para una carpeta Properties que representa el acceso a las propiedades del proyecto en el Explorador de soluciones. Elimina este elemento del archivo del proyecto.

Ejemplo de un elemento a eliminar si está presente en .sqlproj:

<ItemGroup>
  <Folder Include="Properties" />
</ItemGroup>

Obligatorio: eliminar los elementos de compilación incluidos de manera predeterminada

Los proyectos SQL originales enumeran todos los .sql archivos que representan objetos de base de datos explícitamente en el archivo de proyecto como <Build Include="..." /> elementos. En proyectos SQL de estilo SDK, cualquier .sql archivo del árbol de carpetas del proyecto (**/*.sql) se incluye por defecto. Quita los archivos .sql especificados en los elementos <Build Include="...." /> correspondientes a esos archivos para evitar problemas de rendimiento de compilación.

Elimina líneas como las siguientes del archivo del proyecto:

  <Build Include="SalesLT/Products.sql" />
  <Build Include="SalesLT/SalesLT.sql" />
  <Build Include="SalesLT/Categories.sql" />
  <Build Include="SalesLT/CategoriesProductCount.sql" />

No elimines:

• <Build Include="..." /> elementos para .sql archivos que no están en el árbol de carpetas del proyecto SQL
• <PreDeploy Include="..." /> o <PostDeploy Include="..." /> elementos, porque estos nodos dictan un comportamiento específico para esos archivos
• Elementos que no son archivos .sql, como archivos .publish.xml en elementos <None Include="..." />, archivos .refactorlog.xml en elementos <RefactorLog Include="..." /> o archivos .xsd en elementos <Build Include="..." />

Opcional: elimine referencias de SSDT

El SQL Server Data Tools (SSDT) original requería contenido adicional en el archivo de proyecto para detectar la instalación de Visual Studio. Estas líneas son innecesarias en proyectos SQL de estilo SDK y se pueden eliminar:

  <PropertyGroup>
    <VisualStudioVersion Condition="'$(VisualStudioVersion)' == ''">11.0</VisualStudioVersion>
    <!-- Default to the v11.0 targets path if the targets file for the current VS version is not found -->
    <SSDTExists Condition="Exists('$(MSBuildExtensionsPath)\Microsoft\VisualStudio\v$(VisualStudioVersion)\SSDT\Microsoft.Data.Tools.Schema.SqlTasks.targets')">True</SSDTExists>
    <VisualStudioVersion Condition="'$(SSDTExists)' == ''">11.0</VisualStudioVersion>
  </PropertyGroup>

Opcional: elimine la configuración de compilación predeterminada

Los proyectos SQL originales incluyen dos grandes bloques para los ajustes de compilación de Release y Debug, mientras que en los proyectos SQL de estilo SDK el SDK conoce los valores predeterminados de estas opciones. Si no tiene personalizaciones en la configuración de compilación, considere la posibilidad de eliminar estos bloques:

  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
    <OutputPath>bin\Release\</OutputPath>
    <BuildScriptName>$(MSBuildProjectName).sql</BuildScriptName>
    <TreatWarningsAsErrors>False</TreatWarningsAsErrors>
    <DebugType>pdbonly</DebugType>
    <Optimize>true</Optimize>
    <DefineDebug>false</DefineDebug>
    <DefineTrace>true</DefineTrace>
    <ErrorReport>prompt</ErrorReport>
    <WarningLevel>4</WarningLevel>
  </PropertyGroup>
  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
    <OutputPath>bin\Debug\</OutputPath>
    <BuildScriptName>$(MSBuildProjectName).sql</BuildScriptName>
    <TreatWarningsAsErrors>false</TreatWarningsAsErrors>
    <DebugSymbols>true</DebugSymbols>
    <DebugType>full</DebugType>
    <Optimize>false</Optimize>
    <DefineDebug>true</DefineDebug>
    <DefineTrace>true</DefineTrace>
    <ErrorReport>prompt</ErrorReport>
    <WarningLevel>4</WarningLevel>
  </PropertyGroup>

La referencia de propiedades del proyecto enumera las propiedades disponibles y sus valores predeterminados.

Paso 4: Archivos de solución

Es posible que se haga referencia al archivo de proyecto en un archivo de solución (.sln). Si tienes un archivo de solución, actualízalo para que haga referencia al nuevo archivo de proyecto estilo SDK. Si no tiene un archivo de solución, puede omitir esta sección y continuar con el paso 5.

Opción 1: Crear un archivo de solución

Si el archivo de solución contiene solo el proyecto SQL, es más fácil eliminar el archivo de solución y crear un nuevo archivo de solución con el proyecto tipo SDK.

dotnet new sln --name MySolution
dotnet sln MySolution.sln add MyDatabaseProject\MyDatabaseProject.sqlproj

Opción 2: Editar el archivo de solución

Si el archivo de solución contiene varios proyectos, actualiza el archivo de solución para que haga referencia al nuevo archivo de proyecto estilo SDK. Puede editar el archivo de solución en un editor de texto y cambiar la referencia del proyecto al nuevo archivo de proyecto de estilo SDK. La referencia del proyecto en el archivo de solución debe tener este aspecto:

Project("{PROJECT_TYPE_GUID}") = "MyDatabaseProject", "MyDatabaseProject\MyDatabaseProject.sqlproj", "{PROJECT_GUID}"
EndProject

El valor PROJECT_TYPE_GUID de un proyecto Microsoft.Build.Sql es 42EA0DBD-9CF1-443E-919E-BE9C484E4577. PROJECT_GUID es un identificador único del proyecto que se encuentra en el elemento <ProjectGuid> del archivo del proyecto. Si tienes un archivo de solución con tu proyecto, no necesitas cambiar el PROJECT_GUID valor. Cambia el valor de PROJECT_TYPE_GUID al GUID del tipo de proyecto Microsoft.Build.Sql.

Paso 5: Compilación de un .dacpac archivo a partir del proyecto modificado para la comparación

dotnet build

# optionally specify the project file
dotnet build MyDatabaseProject.sqlproj

El proceso de compilación crea un archivo .dacpac en la carpeta bin\Debug del proyecto de manera predeterminada. Con el Explorador de archivos, localiza el .dacpac creado por el proceso de compilación y cópialo en una carpeta nueva fuera del directorio del proyecto. Usa este .dacpac archivo para comparar y validar tu conversión más adelante.

Paso 6: Comprobar que los .dacpac archivos son los mismos

Para comprobar que la conversión se ha realizado correctamente, compare los archivos .dacpac creados a partir de los proyectos originales y modificados. Utiliza las capacidades de comparación de esquemas de los proyectos SQL para visualizar la diferencia en los modelos de base de datos entre los dos .dacpac archivos. Como alternativa, use la utilidad de línea de comandos DacpacVerify para comparar los dos archivos .dacpac, incluidos sus scripts previos y posteriores a la implementación y la configuración del proyecto.

Puedes instalar DacpacVerify como una herramienta dotnet. Para instalar la herramienta, ejecute el comando siguiente:

dotnet tool install --global Microsoft.DacpacVerify --prerelease

La sintaxis de DacpacVerify es especificar la ruta de archivo en dos archivos .dacpac como dacpacverify <source DACPAC path> <target DACPAC path>. Para comparar los dos .dacpac archivos, ejecute el siguiente comando:

DacpacVerify original_project.dacpac modified_project.dacpac

Puede usar la herramienta de comparación de esquemas para comparar objetos de los .dacpac archivos.

Cuando ejecutas la comparación de esquemas, no deberían mostrarse resultados. La falta de diferencias indica que el proyecto original y el modificado son equivalentes, produciendo el mismo modelo de base de datos en el archivo .dacpac.

Contenido relacionado

• ¿Qué son los proyectos de base de datos SQL?
• Introducción a los proyectos de base de datos SQL
• Referencias de paquetes de proyectos SQL