aspnetcore/docs/AddingNewProjects.md

Adding New Projects To The Repo

Sample PR of final result: https://github.com/dotnet/aspnetcore/pull/41945

Creating a new project

1. Create a new folder that will house your .csproj and other project-related files.
2. (EXTREMELY IMPORTANT) Inside this new folder, make a new folder for the source files of your project. For regular functionality-adding project this will be called src. However, if you are adding a different kind of project, it will be called something more applicable (ex. test/ for a test project).
3. Open the .slnf you want to add your project to in VS (preferably via the startvs.cmd script located in the same folder as the .slnf). Then add a new Solution Folder in the new folder with the same name and location as the actual folder created in the first step.
4. Create the project via the VS Add menu (select the folder -> right click -> Add -> New Project... -> follow the wizard).

Note: (Only applicable to src/ projects) Depending on what kind of project you are creating, VS will create different files in your project. You might also want to add the following files:

• PublicAPI.Shipped.txt
  • Lists publically visible APIs that are exported from your final compiled .dll.
  • This only lists APIs that have already been shipped to customers and cannot be changed.
  • There is an empty template at eng/PublicAPI.empty.txt for your reference. You can copy and rename the file to add it to your project. Make sure the name is exactly as shown above.
• PublicAPI.UnShipped.txt
  • Lists publicly visible APIs that are exported from your final compiled .dll. If this is not configured properly, you will get build errors. VS will warn you though with green squiggly lines. If you see these squiggly lines, open the VS Quick Actions (CTRL + '.') and select the option to add it to the public API.
  • This only lists APIs that have NOT already been shipped to customers. So, these can still change.
  • There is an empty template at eng/PublicAPI.empty.txt for your reference. You can copy and rename the file to add it to your project. Make sure the name is exactly as shown above.

• You can expose internals via @(InternalsVisibleTo) items in your .csproj.

  <ItemGroup>
    <InternalsVisibleTo Include="Microsoft.AspNetCore.My.TestProject" />
  

Adding to the rest of the repo

1. VS should have already registered your .csproj in the corresponding solution (.sln) and solution filter (.slnf) files.
   • If VS has not already modified these files, open the .slnf you want to add the project to. Create a solution folder for your project if doesn't exist already. Then right click solution folder -> Add -> Existing Project... -> follow the wizard.
2. Run the eng/scripts/GenerateProjectList.ps1 file to regenerate a number of eng/*.props files e.g. ProjectReferences.props.

Note: If you are adding a new project to the root src directory, you will also need to add a reference in both of the DotNetProjects lists of the eng/Build.props file. The first list (the one with condition '$(BuildMainlyReferenceProviders)' != 'true'") has items in the format of:

   <DotNetProjects Include="
                          $(RepoRoot)src\[YOUR FOLDER]\**\*.csproj;
                          ...

while the second (the one with condition '$(BuildMainlyReferenceProviders)' == 'true'") has them in the format of (note the second src):

  <DotNetProjects Include="
                        $(RepoRoot)src\[YOUR FOLDER]\**\src\*.csproj;
                        ...

(OPTIONAL) Including your project in SharedFx

1. Add the following line to the .csproj's PropertyGroup to include your project in the SharedFx API:

   <IsAspNetCoreApp>true</IsAspNetCoreApp>
   

2. Re-run the eng/scripts/GenerateProjectList.ps1 to add your project to the eng/SharedFramework.Local.props file and, if applicable, the eng/TrimmableProjects.props file.

3. Add your project name to the lists in src\Framework\test\TestData.cs. This is not strictly necessary for the project to work but there is a test on CI that will fail if this is not done. Make sure to include your project in a way that maintains alphabetical order.

Manually saving solution and solution filter files

VS is pretty good at keeping the files up to date and organized correctly. It will also prompt you if it finds an error and, in most cases, offer a solution to fix the issue. Sometimes just saving the file will trigger VS to resolve any issues automatically. However, if you would like to add a new solution filter file or update one manually you can find a tutorial link here.