Getting Started

Install tools

Download and install Visual Studio Community, which is the free version of Microsoft's integrated software development environment.

Visual Studio has lots of optional parts, depending on what kind of programming you want to do. The installer asks you select which "workloads" you want to install. Select "Universal Windows Platform development" and "Mobile development with .NET". You can add other options if you want, or you can add them later.

Installing Visual Studio Community also installs the GIT tools, which we'll be using to manage and share code.

Create a GitHub account and join SWHS-PC

You will need to create an account on github.com and join the SWHS-PC organization to contribute code.

Once you've created a github account, send your github user name to one of the SWHS-PC administrators (Nick or Mr. Green) and we will invite you to become a member of the SWHS-PC organization.

Once you've received and accepted the invitation, you can move on to the next step, which is to clone the repository.

Clone the repository

Cloning a repository makes a copy of it on your computer, so you can make changes locally. Later, we'll see how to move code changes up and down between the server and your local repository.

In this section, you will be entering commands using the PowerShell command line interface. As background, you may want to read PowerShell Basics.

The local repository can be anywhere on your computer, but for simplicity, these instructions assume you'll create repositories in C:\GitHub\SWHS-PC. If you're using a shared computer, you may want to put your repositories on a USB thumb drive, in which case the drive litter would be something else.

To create the above directory in PowerShell, you would type the following commands:

cd c:\
md GitHub
cd .\GitHub
md SWHS-PC
cd .\SWHS-PC

(You can save yourself some typing by taking advantage of auto-complete. For example, instead of typing "cd .\GitHub", just type "cd g" and press TAB.)

With C:\GitHub\SWHS-PC as the current directory, type the following command to clone the repository:

git clone https://github.com/SWHS-PC/Users.git

There should now be a Users folder under the current folder.

Create a topic branch

The next few sections will walk you through creating a simple "Hello World" program and getting your new code integrated into the master branch on GitHub. The first step for any change you want to make is to create a branch in GIT.

In the instructions below, YourName stands for some name unique to you. As a convention, we can use first name and last initial -- for example, BobJ if your name is Bob Jones. When you create a branch, you will include YourName as part of the branch name to ensure that we all use different names. Later, you will create a subdirectory named YourName to hold your code.

To create a topic branch, open a PowerShell window, and type the following commands:

cd c:\GitHub\SWHS-PC\Users
git checkout -b YourName/Make-Hello-World

While we're at it, let's also create a directory for your code:

md YourName
cd .\YourName

Now let's create your first program!

Create a "Hello World" program

Open Visual Studio and choose File / New / Project...

A big, complicated dialog box appears. Fill it in as follows:

• In the tree view at left, choose "Visual C#" / ".NET Core".
• Select "Console App (.NET Core)" in the right-hand pane.
• In the Name box, type "HelloWorld".
• In the Location box, type the path of your user folder, or click Browse to browse to it. It should be something like "C:\GitHub\SWHS-PC\Users\YourName".
• Make sure the "Create new Git repository" box is not checked.

Once you've filled everything in, click OK to create the project.

Press CTRL+SHIFT+B to build your program. This converts the source code to a runnable program. In this case, it will create a file named HelloWorld.dll, as well as a bunch of other files produced during the build process.

You can step through your program line-by-line by pressing press F10.

You can also run your program from the PowerShell prompt. Switch back to your PowerShell window and enter the following command:

ls -r *.dll

The -r switch means "recurse", and this command lists all files with the ".dll" extension in the current directory and all subdirectories. There will be a HelloWorld.dll file in the following directory:

C:\GitHub\SWHS-PC\Users\YourName\HelloWorld\bin\Debug\netcoreapp1.1

Double-click the directory path to select it, press CTRL+C to copy it the clipboard, then type cd followed by a space and paste the path by pressing CTRL+V. This will change the current directory to the directory that contains HelloWorld.dll. To run your program, type:

dotnet HelloWorld.dll

You've now created a working program. Read on to add your code to the GIT repository.

Add and commit your changes

The code for your new program now exists in your local working directory, but has not been added to the GIT branch. Switch back to the PowerShell window and type the following commands:

git add --all
git status
git commit --message "Create Hello World program."

The "add" command tells GIT what files you want to commit changes to. The --all switch means it adds all the files you've changed.

The "status" command tells you what files you've added, as well as any other changes you may have made but not added. You may notice that the source code files were added, but not HelloWorld.dll or other output that were created when you build the project. That's good. We only want to add source files to the repository, not the generated output files.

The "commit" command actually adds your changes to the current branch in your local repository.

Alternatively, you can commit your changes directly from within Visual Studio. Click the Team Explorer tab and then click Changes.

Push your changes

Committing added your changes to the current branch in the local repository. The next step is to "push" your changes up to the remote repository on GitHub. To do so, type the following command in PowerShell:

git push

The first time you type this command for a given branch, you will see an error message like this:

fatal: The current branch YourName/Make-user-dir has no upstream branch.
To push the current branch and set the remote as upstream, use

    git push --set-upstream origin YourName/Make-user-dir

Copy and past the command line from the error message and press ENTER. You only need to do this once for a given branch. If you make (and commit) more changes then you can push them by simply typing "git push".

Create a pull request

Your changes are now in the remote repository in GitHub, but they're still only in your topic branch. To get the changes merged into the main branch, you need to create a pull request (PR).

The pull request will also give others an opportunity to comment and give feedback on your change before it is merged. This is a great opportunity to catch errors, as well as learn ways to improve your code.

To create a pull request, navigate to the page for the repository on GitHub. Near the top of the page, under the heading "Your recently pushed branches", you should see the name of your topic branch. Click the green "Compare & pull request" button to the right of your branch name.

Change the name of your pull request if desired, add a comment if it's not self-explanatory, add reviewers, and click the green "Create pull request" button.

There's an opportunity now for reviewers to comment on or request changes to your pull request. If changes are requested, you can make the changes in your local repository, commit them, and push them as described earlier. The pull request will be automatically updated with any changes you push to your topic branch.

Completing the pull request

Once reviewers have approved your pull request, you can merge the changes into the main branch. In the pull request's Conversation tab, there is a green button with a drop-down arrow that includes three options: "Create a merge commit", "Squash and merge", and "Rebase and merge." Choose the "Squash and merge" option.

When the merge is complete, you will be prompted to delete the topic branch. You should do this, as it is no longer needed.

Finally, let's update your local repository. Open a PowerShell window and type the following commands:

cd c:\GitHub\SWHS-PC\Users
git checkout master
git pull

This switches your repository back from your topic branch back to the master branch, and then "pulls" changes to the master branch from the remote repository. This includes the changes you just merged, as well as any changes made by others.

You can now also delete the topic branch from your local repository, as it's no longer needed. Type the following commands:

git branch
git branch -d YourTopicBranchName

The first command just lists all the branches in your local repository, and tells you what branch is currently checked out. The second command deletes the branch you specify. You can copy and paste the branch name from the output of the first command.