Repository files navigation

This repository is the home for the .NET Core Template Engine. It contains the brains fordotnet new.Whendotnet new is invoked, it will call the Template Engine to create the artifacts on disk.Template Engine is a library for manipulating streams, including operations to replace values, include/excluderegions and processif,else if,else andend if style statements.

• Class Library/Console App
• Test projects
• ASP.NET project and items

We have created adotnet template samples repo, which shows how you can usethe Template Engine to create new templates. The samples are setup to be stand alone for specific examples. If you are in need of a sample, and it doesn't exist pleasecreate an issue in the samples repo.

You can create new projects withdotnet new, this section will briefly describe that. For more info take a look atAnnouncing .NET Core Tools Updates in VS 2017 RC.

To get started let's find out what options we have by executingdotnet new --help. The result is pasted in the block below.

$ dotnet new mvc --helpMVC ASP.NET Web Application (C#)Author: MicrosoftOptions:  -au|--auth           Thetype of authentication to use                           None          - No authentication                           Individual    - Individual authentication                       Default: None  -uld|--use-local-db  Whether or not to use LocalDB instead of SQLite                       bool - Optional                       Default:false  -f|--framework                           1.0    - Target netcoreapp1.0                           1.1    - Target netcoreapp1.1                       Default: 1.0

Let's create a new project named "MyAwesomeProject" in the "src/MyProject" directory. This project should be an ASP.NET MVC project with Individual Auth. To create that templateexecutedotnet new mvc -n MyAwesomeProject -o src/MyProject -au Individual. Let's try that now, the result is below.

$ dotnet new mvc -n MyAwesomeProject -o src/MyProject -au IndividualThe template"MVC Application" created successfully.

The project was successfully created on disk as expected insrc/MyProject. From here, we can run normaldotnet commands likedotnet restore anddotnet build.

We have a pretty good help system built in, including template specific help (for exampledotnet new mvc --help). If you're not sure the syntax please try that,if you have any difficulties please file a newissue.

Now that we've covered the basics of usingdotnew new, lets move on to info for template authors and contributors.

You can install additional templates that can be used bydotnet new. SeeAvailable templates for dotnet new.

The instructions below enable a new command at thedotnet CLI,dotnet new3, that uses the bits and templates contained in this repo. Think of it as a "preview" version ofdotnet new for trying out new switches, interactions and display styles before rolling them in to the product.

Commands executed againstdotnet new3 won't impact the behavior ofdotnet new, Visual Studio for Mac, Visual Studio, nor any other environment.

If you're authoring templates, or interested in contributing to this repo, then you're likely interested in how to use the latest version of this experience.The steps required are outlined below.

• Fork this repository.
• Clone the forked repository to your local machine.
  • master is a build branch and does not accept contributions directly.
  • The default branch is the active development branch that accepts contributions and flows to master to produce packages.

• Open up a command prompt and navigation to the root of your source code.
• Run the build script appropriate for your environment.
  • Windows:build.cmd
  • Mac/Linux:build.sh
• When running the build script, the existing built-in commanddotnet new will be preserved. A new commanddotnet new3 will be enabled which allows you to createfiles with the latest Template Engine.
• That's it! Now you can rundotnet new3.

For example, here is the result of runningdotnet new3 --help on a Mac (truncated to save space here).

$ dotnet new3 --helpTemplate Instantiation Commandsfor .NET Core CLI.Usage: dotnet new3 [arguments] [options]Arguments:  template  The template to instantiate.<truncated>

• The build that produces thetemplate NuGet packages currently has a dependency onnuget.exe.
  • Because of this, those that wish toinstall using thetemplate NuGet packages will need to be on Windows in order to produce the appropriate assets.

Debugging code requires your currentdotnet new3 session to have its active build session configured to DEBUG, and a debugger from your application of choice to be attached to the current runningdotnet new3 process. The steps required to accomplish this are outlined below.

• When working with the source inside Visual Studio, it is recommended you use the latest available version.

• Open theMicrosoft.Templating.sln solution in the application you will use to attach your debugger.
  • This solution contains the projects needed to run, modify & debug the Template Engine.
• Once your solution is loaded, open up a new command prompt and navigate to the root of your repository.
• Execute thedn3buildmode-debug.cmd script.
  • This will set yourdotnet new3 build to a DEBUG mode.
• Run the "setup" script to build a newdotnet new3 session.

Once "setup" has completed successfully, run the following command.

dotnet new3 --debug:attach {{additonal args}}

By supplying the--debug:attach argument with any other argument(s) you are running, you are triggering a Console.ReadLine(); request which pauses execution of the Template Engine at an early point in its execution.

Once the engine is "paused", you have the opportunity to attach a debugger to the runningdotnet new3 process.

In the application you are using to attach a debugger...

• Open theMicrosoft.TemplateEngine.Cli.New3Command class and locate the following function.
  • New3Command.Run()
• Set a breakpoint at any point after the following block of code.

if(args.Any(x=>string.Equals(x,"--debug:attach",StringComparison.Ordinal))){// This is the line that is executed when --debug:attach is passed as// an argument.Console.ReadLine();}

• Attach the debugger to the current running 'dotnet new 3' process.
• For example, if you are usingVisual Studio you can perform the following.
  • Execute the keyboard shortcut -ctrl + alt + p.
  • This will open up a dialog that allows you to search for thedotnet-new3.exe process.
  • Locate the desired process, select it and hit theAttach button.

Now that you have a debug session attached to your properly configureddotnet new3 process, head back to the command line and hitenter. This will triggerConsole.Readline() to execute and your proceeding breakpoint to be hit inside the application you are using to debug.

Templates can be installed from packages in any NuGet feed, directories on the file system or ZIP type archives (zip, nupkg, vsix, etc.)To install a new template use the command:

dotnet new3 -i {the path to the folder containing the templates}

dotnet new3 --helpdotnet new3 -hdotnet new3

dotnet new3 --listdotnet new3 -ldotnet new3 mvc -l            Lists all templates containing the text "mvc"

dotnet new3 mvc --helpdotnet new3 mvc -h

dotnet new3 MvcWebTemplate --name MyProject --output src --ParameterName1 Value1 --ParameterName2 Value2 ... --ParameterNameN ValueNdotnet new3 MvcWebTemplate -n MyProject -o src --ParameterName1 Value1 --ParameterName2 Value2 ... --ParameterNameN ValueN

• Create formal docs
• Interactive mode (i.e. interactive prompts similar toyo aspnet)
• Integration with Visual Studio One ASP.NET dialog
• Integration with Visual Studio for Mac for .NET Core projects
• Integration withyo aspnet
• Template updates (both required and optional)
• Visual Studio wizard to enable community members to plug into VS as well
• Maybe: Visual Studio wizard which can display templates given a feed URL
• Suggestions welcome, please filean issue