search

dotnet / docs

This repository contains .NET Documentation.
https://learn.microsoft.com/dotnet
Creative Commons Attribution 4.0 International
4.26k stars 5.89k forks source link

Add installation of different templates and how this affects the CLI experience to dotnet new #5961

Closed mairaw closed 4 years ago

mairaw commented 6 years ago

dotnet new web --framework netcoreapp2.0 doesn't work out of the box.

However, if you install old templates into your new SDK by running

dotnet new --install Microsoft.DotNet.Web.ProjectTemplates.2.0 --nuget-source https://dotnet.myget.org/F/aspnetcore-dev/api/v3/index.json

Then dotnet new web --framework netcoreapp2.0 works.

Need to understand how this works and document it.

/cc @KathleenDollard @dsplaisted @natemcmaster

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

natemcmaster commented 6 years ago

I feel hesitant about documenting this with instructions to use MyGet. Packages on MyGet are only meant for aspnetcore contributors, but are not official supported. We frequently change myget feeds, delete packages, and make breaking changes on MyGet.

If the PMs are okay publishing these template packages to NuGet.org and making this the official way you get old templates, then let's get those bits published and document it use nuget.org instead.

cc @DamianEdwards @KathleenDollard @danroth27

danroth27 commented 6 years ago

The packages for the older templates are already on nuget.org. Ex https://www.nuget.org/packages/Microsoft.DotNet.Web.ProjectTemplates.2.0. @seancpeters can provide details on how this works.

natemcmaster commented 6 years ago

@danroth27 The version of those packages is pretty stale, and it looks like they’re still owned by Sayed. Should we update them with latest (e.g. 2.0.8) templates and transfer ownership to Microsoft?

danroth27 commented 6 years ago

Ah, not surprisingly, @natemcmaster is right :smiley:. Looks like we don't publish our template packages.

seancpeters commented 6 years ago

Yes, those older template packages are available on nuget.org - specifically all of these:

The dotnet cli currently only ships with the newest versions of each of these packages, i.e.:

Each of the versions of the packages supports a different framework, the number at the end (1.x, 2.0, 2.1) generally corresponds to the framework available. When showing help on a template, e.g. dotnet new web -h, if only 1 framework is available, it's not listed in the help options because it cannot be varied. But if multiple frameworks are available for a template, the help display with show them all. For example, after installing both:

Also note that the 1.x packages only have beta releases on nuget, and therefore the version must be included in the install string. This is because nuget restore is used during the template install process, and prerelease packages aren't restored with some package information. So to install the 1.x template packs, the version gets appended to the package, with a double colon separator: dotnet new -i Microsoft.DotNet.Web.ProjectTemplates.1.x::1.0.0-beta2-20170629-269 The exact version available can be seen on nuget.org https://www.nuget.org/packages/Microsoft.DotNet.Web.ProjectTemplates.1.x/1.0.0-beta2-20170629-269 But you can also install that pack with a wildcard, as long as it's sufficient to for nuget to match the prerelease version (the specifics are how nuget implements restore) dotnet new -i Microsoft.DotNet.Web.ProjectTemplates.1.x::1.0.0-* (appending ::1.0.0-* to any of the 1x packs listed at the beginning is sufficient to install them)

So, after installing the web project templates 2.0 and 1.x (as above), and having the 2.1 templates in-box, running help displays:

 -f|--framework             The target framework for the project.
                                 netcoreapp2.1    - Target netcoreapp2.1
                                 netcoreapp2.0    - Target netcoreapp2.0
                                 netcoreapp1.0    - Target netcoreapp1.0
                                 netcoreapp1.1    - Target netcoreapp1.1
                             Default: netcoreapp2.1

Note that the classlib template from Microsoft.DotNet.Common.ProjectTemplates.1.x also includes a number of netstandardX.X framework versions, so the number at the end of the package name doesn't always strictly / exclusively correspond to the netcoreapp version: dotnet new classlib -h (partial output)

  -f|--framework  The target framework for the project.
                      netcoreapp2.1     - Target netcoreapp2.1
                      netstandard2.0    - Target netstandard2.0
                      netcoreapp2.0     - Target netcoreapp2.0
                      netcoreapp1.0     - Target netcoreapp1.0
                      netcoreapp1.1     - Target netcoreapp1.1
                      netstandard1.0    - Target netstandard1.0
                      netstandard1.1    - Target netstandard1.1
                      netstandard1.2    - Target netstandard1.2
                      netstandard1.3    - Target netstandard1.3
                      netstandard1.4    - Target netstandard1.4
                      netstandard1.5    - Target netstandard1.5
                      netstandard1.6    - Target netstandard1.6
                  Default: netstandard2.0

I can go into more detail on any of this as needed.

mairaw commented 6 years ago

Thanks @seancpeters! We don't have that flexibility of dynamically changing the options shown on docs. So I'll have to add the option and explain how it works. 😄

So, this framework option would show up for all templates listed here (except for the bottom 4)?

seancpeters commented 6 years ago

Most of them, but not all. In addition to the bottom 4, these do not have a framework:

tdykstra commented 4 years ago

This was addressed by #18080