Adds readme's to nuget for SDK and templates (#542)

* docs warning and redirect

* sdk nupkg readme

* adds readme to templates

src/Microsoft.Build.Sql.Templates/Microsoft.Build.Sql.Templates.csproj

@@ -8,6 +8,7 @@
     <Description>Templates for creating new Microsoft.Build.Sql projects.</Description>
     <PackageTags>DacFx sqlproj</PackageTags>
     <PackageLicenseFile>LICENSE.txt</PackageLicenseFile>
+    <PackageReadmeFile>README.md</PackageReadmeFile>
     <IncludeBuildOutput>false</IncludeBuildOutput>
     <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
     <NoDefaultExcludes>true</NoDefaultExcludes>
@@ -22,6 +23,7 @@
   </ItemGroup>
   <ItemGroup>
     <Content Include="$(EnlistmentRoot)/LICENSE.txt" PackagePath="/" Pack="true" />
+    <Content Include="README.md" PackagePath="/" Pack="true" />
     <Content Include="$(TemplateIntermediateOutputPath)\**" PackagePath="content/" Pack="true" />
   </ItemGroup>
 

src/Microsoft.Build.Sql.Templates/README.md

@@ -1,5 +1,9 @@
 # Microsoft.Build.Sql.Templates
 
+SQL projects templates for a new project and a sample code analysis rule.
+
+📗 Learn more about SQL projects at https://learn.microsoft.com/sql/tools/sql-database-projects/sql-database-projects
+
 ## Installing the templates
 
 The templates are available on [NuGet](https://www.nuget.org/packages/Microsoft.Build.Sql.Templates/).  To install the templates, run the following command:
@@ -8,10 +12,13 @@ The templates are available on [NuGet](https://www.nuget.org/packages/Microsoft.
 dotnet new install Microsoft.Build.Sql.Templates
 ```
 
+Microsoft.Build.Sql projects and code analysis rules can be created using the `sqlproj` and `sqlcodeanalysis` templates, respectively. Both projects require .NET SDK 8 or higher.
+
 ## Using the templates
 
 ### SQL project
 
+
 Creating a new project "AdventureWorks" (`-n` or `--name`):
 
 ```bash
@@ -63,9 +70,15 @@ dotnet build
 dotnet new install bin/Debug/Microsoft.Build.Sql.Templates.1.0.0.nupkg
 ```
 
-
 To uninstall the templates
 
 ```bash
 dotnet new uninstall Microsoft.Build.Sql.Templates
-```
+```
+
+
+## Resources
+
+- [Primary documentation](https://aka.ms/sqlprojects)
+- [CI/CD workflow samples](https://aka.ms/sqlprojects-samples)
+- [GitHub repository](https://github.com/microsoft/dacfx)

src/Microsoft.Build.Sql/Microsoft.Build.Sql.csproj

@@ -4,6 +4,7 @@
     <TargetFramework>net8.0</TargetFramework>
     <NuspecFile>$(MSBuildThisFileDirectory)Microsoft.Build.Sql.nuspec</NuspecFile>
     <PackageType>MSBuildSDK</PackageType>
+    <PackageReadmeFile>README.md</PackageReadmeFile>
     <IncludeBuildOutput>false</IncludeBuildOutput>
     <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
 
@@ -42,6 +43,7 @@
   </Target>
 
   <ItemGroup>
+    <None Include="README.md" Pack="true" PackagePath="\"/>
     <None Remove="tools\**" />
   </ItemGroup>
 

src/Microsoft.Build.Sql/Microsoft.Build.Sql.nuspec

@@ -18,11 +18,13 @@
     <tags>dacfx sqlproj build sdk</tags>
     <license type="file">LICENSE.txt</license>
     <requireLicenseAcceptance>false</requireLicenseAcceptance>
+    <readme>README.md</readme>
   </metadata>
   <files>
     <file src="sdk\**" target="sdk" />
     <file src="tools\**" target="tools" />
     <file src="..\..\LICENSE.txt" target="LICENSE.txt" />
     <file src="..\..\images\nuspecicon.png" target="images\nuspecicon.png" />
+    <file src="README.md" target="README.md" />
   </files>
 </package>

src/Microsoft.Build.Sql/README.md

@@ -1,31 +1,66 @@
 # Microsoft.Build.Sql (Preview)
 
-## Introduction
-.NET SDK for database projects (.sqlproj) available in preview.
+![NuGet Version](https://img.shields.io/nuget/v/microsoft.build.sql)
 
-This SDK is similar to [Microsoft.NET.Sdk](https://learn.microsoft.com/dotnet/core/project-sdk/overview) for .NET projects. It contains all the MSBuild targets and task libraries needed to build a database project into a DACPAC, which can then be used to publish to a database. You can read more about SDK-style projects here: https://learn.microsoft.com/dotnet/core/project-sdk/overview
+The Microsoft.Build.Sql SDK contains MSBuild support for SQL, similar to [Microsoft.NET.Sdk](https://learn.microsoft.com/dotnet/core/project-sdk/overview) for .NET projects.
 
-## Current Status
-This project is in preview and we are currently building tests for different functionality. Contributors welcome. Please feel free to open issues for bugs or improvements, or send PRs directly.
+## Overview
 
-The latest release can be found on [Nuget.org](https://www.nuget.org/packages/Microsoft.Build.Sql/).
+Your database objects are stored as code with Microsoft.Build.Sql SDK-style SQL projects. SQL database objects are aggregated from the *.sql* files in the project and *dotnet build* generates a `.dacpac` artifact for deploying the objects dynamically to a database. Development environment [integrations](https://learn.microsoft.com/sql/tools/sql-database-projects/sql-projects-tools) are available for VS Code and Visual Studio:
 
-Building and publishing database project is supported in [Azure Data Studio](https://github.com/microsoft/azuredatastudio) and [VS Code](https://marketplace.visualstudio.com/items?itemName=ms-mssql.sql-database-projects-vscode). Support for SDK-style projects will be added in Visual Studio SQL Server Data Tools (SSDT) in a future release.
+- [SQL database projects extension for VS Code and Azure Data Studio](https://marketplace.visualstudio.com/items?itemName=ms-mssql.sql-database-projects-vscode)
+- [Visual Studio SQL Server Data Tools (SSDT), preview](https://learn.microsoft.com/sql/ssdt/download-sql-server-data-tools-ssdt)
 
-## Using this SDK
+SQL code analysis and other build-time tests can validate database code quality and correctness during continuous integration of code changes. Leverage the [Microsoft.SqlPackage](https://www.nuget.org/packages/Microsoft.sqlpackage) .NET tool for deploying objects to databases and updating a project with the contents of a project.
 
-If you have an existing database project, you can convert it to use this SDK by following the steps in [Converting-Existing.md](docs/Converting-Existing.md).
+## Get started
 
-If you're looking to get started with Microsoft.Build.Sql on a new project, you can follow the brief tutorial in [Tutorial.md](docs/Tutorial.md).
+The Microsoft.Build.Sql SDK requires .NET 8 or higher.
+
+### New project
+
+.NET templates are available for quickly setting up a new SQL project. Install the [Microsoft.Build.Sql.Templates](https://www.nuget.org/packages/Microsoft.build.sql.templates) NuGet package to get started with a new SQL project.
+
+```bash
+dotnet new -i Microsoft.Build.Sql.Templates
+```
+
+Create a new SQL project using the **sqlproj** template.
+
+```bash
+dotnet new sqlproj -n ProductsTutorial
+```
+
+Any `.sql` files added to the project folder will be included in the build process and generate a `.dacpac` file. The `.dacpac` file can be used to deploy the database objects to a database.
+
+### From an existing database
+
+An existing database can be scripted out into a SQL project using the [Microsoft.SqlPackage](https://www.nuget.org/packages/Microsoft.sqlpackage) .NET tool. The following command will generate a SQL project from an existing database.
+
+```bash
+sqlpackage /a:Extract /tf:YourProjectFolder /scs:"Data Source=yourservername;Initial Catalog=yourdatabasename;Authentication=Active Directory Interactive" /p:ExtractTarget=SchemaObjectType
+```
+
+Use the [Microsoft.Build.Sql.Templates](https://www.nuget.org/packages/Microsoft.build.sql.templates) as outlined above to create a new SQL project file for the `.sql` files generated by the `sqlpackage` tool.
+
+## Convert an existing SQL project
+
+Depending on the complexity of your project, the conversion to a Microsoft.Build.Sql project may be straightforward. Building the project before the process and retaining the `.dacpac` for comparison after the conversion is highly recommended. The primary step in the conversion is to add the SDK reference. Edit the .sqlproj file by adding
+```xml
+<Sdk Name="Microsoft.Build.Sql" Version="0.2.5-preview" />
+``` 
+inside the `<Project>` tag.
+
+Depending on where you are developing, additional steps may be required. A walk-through of the conversion process is available at https://learn.microsoft.com/sql/tools/sql-database-projects/howto/convert-original-sql-project.
+
+## Resources
+
+- [Primary documentation](https://aka.ms/sqlprojects)
+- [CI/CD workflow samples](https://aka.ms/sqlprojects-samples)
+- [GitHub repository](https://github.com/microsoft/dacfx)
 
 ## Telemetry
 The .NET SDK for SQL includes a telemetry feature that collects usage data and sends it to Microsoft when you use build commands. The usage data includes exception information when the build command fails. Telemetry data helps the .NET team understand how the tools are used so they can be improved. Information on failures helps the team resolve problems and fix bugs.
 
 ### How to opt out
-The .NET SDK for SQL telemetry feature is enabled by default for Microsoft distributions of the SDK. To opt out of the telemetry feature, set the DACFX_TELEMETRY_OPTOUT environment variable to 1 or true. Telemetry feature can also be opt out by opting out [.NET SDK telemetry](https://learn.microsoft.com/dotnet/core/tools/telemetry#how-to-opt-out). 
-
-## Documentation
-- [Converting Existing Projects](docs/Converting-Existing.md)
-- [Functionality](docs/Functionality.md)
-- [Troubleshooting](docs/Troubleshooting.md)
-- [Tutorial](docs/Tutorial.md)
+The .NET SDK for SQL telemetry feature is enabled by default for Microsoft distributions of the SDK. To opt out of the telemetry feature, set the DACFX_TELEMETRY_OPTOUT environment variable to 1 or true. Telemetry feature can also be opt out by opting out [.NET SDK telemetry](https://learn.microsoft.com/dotnet/core/tools/telemetry#how-to-opt-out).

src/Microsoft.Build.Sql/docs/Converting-Existing.md

@@ -3,8 +3,7 @@
 This page provides guidance in converting existing SQL projects from Visual Studio SQL Server Data Tools (SSDT) or Azure Data Studio (ADS) to use the Microsoft.Build.Sql SDK.
 
 > [!WARNING]
-> Visual Studio does not yet support Microsoft.Build.Sql SDK-style SQL projects. Converting existing projects to use Microsoft.Build.Sql will require you to make further edits through VS Code or Azure Data Studio.
-
+> This article has been replaced by https://learn.microsoft.com/sql/tools/sql-database-projects/howto/convert-original-sql-project and is no longer updated. Please refer to the new documentation for the latest information.
 
 ## Changes to .sqlproj file
 To convert a database project into SDK-style, edit the .sqlproj file by adding

src/Microsoft.Build.Sql/docs/Functionality.md

@@ -1,4 +1,8 @@
 # Functionality
+
+> [!WARNING]
+> This article has been replaced by https://learn.microsoft.com/sql/tools/sql-database-projects/sql-database-projects and is no longer updated. Please refer to the new documentation for the latest information.
+
 In SQL projects there are several capabilities that can be specified in the `.sqlproj` file that impact the database model either at project build or deployment.  The following sections describe some of these capabilities that are available for Microsoft.Build.Sql projects.
 
 |Capability|Build time validation|Included in deployment|

src/Microsoft.Build.Sql/docs/Tutorial.md

@@ -1,4 +1,9 @@
 # Tutorial
+
+> [!WARNING]
+> This article has been replaced by https://learn.microsoft.com/sql/tools/sql-database-projects/tutorials/create-deploy-sql-project and is no longer updated. Please refer to the new documentation for the latest information.
+
+
 This page walks through creating a new SQL project and publishing it to a database from the command line and any text editor. For more information on using SQL projects in Azure Data Studio or VS Code, check out the [SQL Database Projects extension documentation](https://aka.ms/azuredatastudio-sqlprojects).
 
 ## 📁 Create a SQL project