Update and refresh Create package dotnet (#2863)

Author: v-thepet

docs/create-packages/creating-a-package-dotnet-cli.md

@@ -1,135 +1,134 @@
 ---
-title: Create a NuGet package using the dotnet CLI
-description: A detailed guide to the process of designing and creating a NuGet package, including key decision points like files and versioning.
+title: Create a NuGet package with the dotnet CLI
+description: Read a detailed guide about the process of designing and creating a NuGet package, including key decision points like files and versioning.
 author: JonDouglas
 ms.author: jodou
-ms.date: 07/14/2022
+ms.date: 08/29/2022
 ms.topic: conceptual
 ---
 
-# Create a NuGet package using the dotnet CLI
+# Create a NuGet package with the dotnet CLI
 
-No matter what your package does or what code it contains, you use one of the CLI tools, either `nuget.exe` or `dotnet.exe`, to package that functionality into a component that can be shared with and used by any number of other developers. This article describes how to create a package using the dotnet CLI. To install the `dotnet` CLI, see [Install NuGet client tools](../install-nuget-client-tools.md). Starting in Visual Studio 2017, the dotnet CLI is included with .NET Core workloads.
+NuGet packages contain code that developers can reuse in their projects. No matter what your code does or contains, you use a command-line tool, either `nuget.exe` or `dotnet.exe`, to create the NuGet package.
 
-For .NET Core and .NET Standard projects that use the [SDK-style format](../resources/check-project-format.md), and any other SDK-style projects, NuGet uses information in the project file directly to create a package. For step-by-step tutorials, see [Create .NET Standard Packages with dotnet CLI](../quickstart/create-and-publish-a-package-using-the-dotnet-cli.md) or [Create .NET Standard Packages with Visual Studio](../quickstart/create-and-publish-a-package-using-visual-studio.md).
+This article describes how to create a package by using the [dotnet CLI](). Starting in Visual Studio 2017, the dotnet CLI is included with all .NET and .NET Core workloads. If you need to install the dotnet CLI or other NuGet client tools, see [Install NuGet client tools](../install-nuget-client-tools.md).
 
-`msbuild -t:pack` is functionality equivalent to `dotnet pack`. To build with MSBuild, see [Create a NuGet package using MSBuild](creating-a-package-msbuild.md).
+This topic applies only to .NET and other projects that use the [SDK-style format](../resources/check-project-format.md). For these projects, NuGet uses information from the project file to create a package. For quickstart tutorials, see [Create packages with the dotnet CLI](../quickstart/create-and-publish-a-package-using-the-dotnet-cli.md) or [Create packages with Visual Studio](../quickstart/create-and-publish-a-package-using-visual-studio.md).
 
-> [!IMPORTANT]
-> This topic applies to [SDK-style](../resources/check-project-format.md) projects, typically .NET Core and .NET Standard projects.
-
-## Set properties
+The MSBuild [msbuild -t:pack](creating-a-package-msbuild.md#run-the-msbuild--tpack-command) command is functionally equivalent to [dotnet pack](/dotnet/core/tools/dotnet-pack). For more information about creating a package with MSBuild, see [Create a NuGet package using MSBuild](creating-a-package-msbuild.md).
 
-The following properties are required to create a package.
+> [!NOTE]
+> - To create and publish packages for non-SDK-style projects, typically .NET Framework projects, see [Create a package using the nuget.exe CLI](Creating-a-Package.md) or [Create and publish a package using Visual Studio (.NET Framework)](../quickstart/create-and-publish-a-package-using-visual-studio-net-framework.md).
+> 
+> - For projects migrated from *packages.config* to [PackageReference](../consume-packages/package-references-in-project-files.md), use `msbuild -t:pack`. For more information, see [Create a package after migration](../consume-packages/migrate-packages-config-to-package-reference.md#create-a-package-after-migration).
 
-- `PackageId`, the package identifier, which must be unique across the gallery that hosts the package. If not specified, the default value is `AssemblyName`.
-- `Version`, a specific version number in the form *Major.Minor.Patch[-Suffix]* where *-Suffix* identifies [pre-release versions](prerelease-packages.md). If not specified, the default value is 1.0.0.
-- The package title as it should appear on the host (like nuget.org)
-- `Authors`, author and owner information. If not specified, the default value is `AssemblyName`.
-- `Company`, your company name. If not specified, the default value is `AssemblyName`.
+## Set properties
 
-In Visual Studio, you can set these values in the project properties (right-click the project in Solution Explorer, choose **Properties**, and select the **Package** tab). You can also set these properties directly in the project files (`.csproj`).
+You can create an example class library project by using the `dotnet new classlib` command, and package the project by using `dotnet pack`. The `dotnet pack` command uses the following properties. If you don't specify values in the project file, the command uses default values.
 
-```xml
-<PropertyGroup>
-  <PackageId>AppLogger</PackageId>
-  <Version>1.0.0</Version>
-  <Authors>your_name</Authors>
-  <Company>your_company</Company>
-</PropertyGroup>
-```
+- `PackageId`, the package identifier, must be unique across nuget.org and any other targets that host the package. If you don't specify a value, the command uses the `AssemblyName`.
+- `Version` is a specific version number in the form `Major.Minor.Patch[-Suffix]`, where `-Suffix` identifies [prerelease versions](prerelease-packages.md). If not specified, the default value is `1.0.0`.
+- `Authors` are the authors of the package. If not specified, the default value is the `AssemblyName`.
+- `Company` is company information. If not specified, the default value is the `Authors` value.
+- `Product` is product information. If not specified, the default value is the `AssemblyName`.
 
-> [!Important]
-> Give the package an identifier that's unique across nuget.org or whatever package source you're using.
+In Visual Studio, you can set these values in the project properties. Right-click the project in **Solution Explorer**, select **Properties**, and then select the **Package** section. You can also add the properties directly to the *.csproj* or other project file.
 
-The following example shows a simple, complete project file with these properties included. (You can create a new default project using the `dotnet new classlib` command.)
+The following example shows a project file with package properties added.
 
 ```xml
 <Project Sdk="Microsoft.NET.Sdk">
   <PropertyGroup>
     <TargetFramework>netstandard2.0</TargetFramework>
-    <PackageId>AppLogger</PackageId>
+    <PackageId>UniqueID</PackageId>
     <Version>1.0.0</Version>
-    <Authors>your_name</Authors>
-    <Company>your_company</Company>
+    <Authors>Author Name</Authors>
+    <Company>Company Name</Company>
+    <Product>Product Name</Product>
   </PropertyGroup>
 </Project>
 ```
 
-You can also set the optional properties, such as `Title`, `PackageDescription`, and `PackageTags`, as described in [MSBuild pack targets](../reference/msbuild-targets.md#pack-target), [Controlling dependency assets](../consume-packages/package-references-in-project-files.md#controlling-dependency-assets), and [NuGet metadata properties](/dotnet/core/tools/csproj#nuget-metadata-properties).
+You can add other optional properties, such as `Title`, `PackageDescription`, and `PackageTags`.
 
-> [!NOTE]
-> For packages built for public consumption, pay special attention to the **PackageTags** property, as tags help others find your package and understand what it does.
+>[!NOTE]
+> For packages you build for public consumption, pay special attention to the `PackageTags` property. Tags help others find your package and understand what it does.
 
-For details on declaring dependencies and specifying version numbers, see [Package references in project files](../consume-packages/package-references-in-project-files.md) and [Package versioning](../concepts/package-versioning.md). It is also possible to surface assets from dependencies directly in the package by using the `<IncludeAssets>` and `<ExcludeAssets>` attributes. For more information, see [Controlling dependency assets](../consume-packages/package-references-in-project-files.md#controlling-dependency-assets).
+The `dotnet pack` command automatically converts `PackageReference`s  in your project files to dependencies in the created package. You can control which assets to include through the `IncludeAssets`, `ExcludeAssets` and `PrivateAssets` tags. For more information, see [Controlling dependency assets](../consume-packages/package-references-in-project-files.md#controlling-dependency-assets).
 
-## Add an optional description field
+For more information about dependencies, optional properties, and versioning, see:
 
-[!INCLUDE [add description to package](includes/add-description.md)]
+- [Package references in project files](../consume-packages/package-references-in-project-files.md)
+- [Package versioning](../concepts/package-versioning.md)
+- [NuGet metadata properties](/dotnet/core/tools/csproj#nuget-metadata-properties)
+- [MSBuild pack targets](../reference/msbuild-targets.md#pack-target)
 
-## Choose a unique package identifier and set the version number
+### Choose a unique package identifier and set the version number
 
 [!INCLUDE [choose-package-id](includes/choose-package-id.md)]
 
+### Add an optional description field
+
+[!INCLUDE [add description to package](includes/add-description.md)]
+
 ## Run the pack command
 
-To build a NuGet package (a `.nupkg` file) from the project, run the `dotnet pack` command, which also builds the project automatically:
+To build the NuGet package or *.nupkg* file, run the [dotnet pack](/dotnet/core/tools/dotnet-pack) command from the project folder, which also builds the project automatically.
 
 ```dotnetcli
-# Uses the project file in the current folder by default
 dotnet pack
 ```
 
-The output shows the path to the `.nupkg` file.
+The output shows the path to the *.nupkg* file:
 
 ```output
-Microsoft (R) Build Engine version 15.5.180.51428 for .NET Core
-Copyright (C) Microsoft Corporation. All rights reserved.
-
-  Restore completed in 29.91 ms for D:\proj\AppLoggerNet\AppLogger\AppLogger.csproj.
-  AppLogger -> D:\proj\AppLoggerNet\AppLogger\bin\Debug\netstandard2.0\AppLogger.dll
+MSBuild version 17.3.0+92e077650 for .NET
+  Determining projects to restore...
+  Restored D:\proj\AppLoggerNet\AppLogger\AppLogger.csproj (in 97 ms).
   Successfully created package 'D:\proj\AppLoggerNet\AppLogger\bin\Debug\AppLogger.1.0.0.nupkg'.
 ```
 
 ### Automatically generate package on build
 
-To automatically run `dotnet pack` when you run `dotnet build`, add the following line to your project file within `<PropertyGroup>`:
+To automatically run `dotnet pack` whenever you run `dotnet build`, add the following line to your project file in the `<PropertyGroup>` tag:
 
 ```xml
 <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
 ```
 
-When you run `dotnet pack` on a solution, this packs all the projects in the solution that are packable ([\<IsPackable\>](/dotnet/core/tools/csproj#nuget-metadata-properties) property is set to `true`).
-
 > [!NOTE]
-> When you automatically generate the package, the time to pack increases the build time for your project.
+> When you automatically generate the package, packing increases the build time for your project.
+
+Running `dotnet pack` on a solution packs all the projects in the solution that are packable, that is, have the `IsPackable` property set to `true`.
 
 ### Test package installation
 
-Before publishing a package, you typically want to test the process of installing a package into a project. The tests make sure that the necessary files all end up in their correct places in the project.
+Before you publish a package, you should test installing the package into a project. Testing ensures that the necessary files end up in their correct places in the project.
 
-You can test installations manually in Visual Studio or on the command line using the normal [package installation steps](../consume-packages/overview-and-workflow.md#ways-to-install-a-nuget-package).
+Test the installation manually in Visual Studio or on the command line by using the normal [package installation process](../consume-packages/overview-and-workflow.md#ways-to-install-a-nuget-package).
 
 > [!IMPORTANT]
-> Packages are immutable. If you correct a problem, change the contents of the package and pack again, when you retest you will still be using the old version of the package until you [clear your global packages](../consume-packages/managing-the-global-packages-and-cache-folders.md#clearing-local-folders) folder. This is especially relevant when testing packages that don't use a unique prerelease label on every build.
+> - You can't change packages once created. If you correct a problem, change the package contents and repack.
+> 
+> - After you recreate the package, retesting still uses the old version of the package until you [clear your global packages folder](../consume-packages/managing-the-global-packages-and-cache-folders.md#clearing-local-folders). Clearing the folder is especially important for packages that don't use a unique prerelease label on every build.
+
+## Next steps
 
-## Next Steps
+Once you create the package, you can publish the *.nupkg* file to the host of your choice.
 
-Once you've created a package, which is a `.nupkg` file, you can publish it to the gallery of your choice as described on [Publishing a Package](../nuget-org/publish-a-package.md).
+> [!div class="nextstepaction"]
+> [Publish a package](../nuget-org/publish-a-package.md)
 
-You might also want to extend the capabilities of your package or otherwise support other scenarios as described in the following topics:
+See the following articles for ways to extend the capabilities of your package or support other scenarios:
 
 - [Package versioning](../concepts/package-versioning.md)
 - [Support multiple target frameworks](../create-packages/multiple-target-frameworks-project-file.md)
 - [Add a package icon](../reference/nuspec.md#icon)
 - [Transformations of source and configuration files](../create-packages/source-and-config-file-transformations.md)
 - [Localization](../create-packages/creating-localized-packages.md)
-- [Pre-release versions](../create-packages/prerelease-packages.md)
+- [Prerelease versions](../create-packages/prerelease-packages.md)
 - [Set package type](../create-packages/set-package-type.md)
 - [MSBuild props and targets](../concepts/MSBuild-props-and-targets.md)
 - [Create packages with COM interop assemblies](../create-packages/author-packages-with-COM-interop-assemblies.md)
-
-Finally, there are additional package types to be aware of:
-
-- [Native Packages](../guides/native-packages.md)
-- [Symbol Packages](../create-packages/symbol-packages-snupkg.md)
+- [Create native packages](../guides/native-packages.md)
+- [Create symbol packages (.snupkg)](symbol-packages-snupkg.md)

docs/create-packages/includes/add-description.md

@@ -1,6 +1,6 @@
-The package's optional description, displayed on the package's NuGet.org page, is either pulled in from the `<description></description>` used in the `.csproj` file or pulled in via the `$description` in the [.nuspec file](../../reference/nuspec.md).
+The package's optional description appears on the **README** tab of the package's nuget.org page. The description pulls from the `<Description>` in the project file or the `$description` in the [.nuspec file](../../reference/nuspec.md).
 
-An example of a _description_ field is shown in the following XML text of the `.csproj` file for a .NET package:
+The following example shows a `Description` in the *.csproj* file for a .NET package:
 
 ```xml
 <Project Sdk="Microsoft.NET.Sdk">