Skip to content

Commit d8892b6

Browse files
rachmariAhmed Bilalmartin389Martin Lopes
authored
Ahdbilal actions lang dotnet (#15896)
* Adding language guide for dotnet * update structure and titles * migrate content tags * update frontmatter * update versioning scheme * update title name * Added some edits to draft * Fixed link * Fixed link * Versioned cache content for dotcom Co-authored-by: Ahmed Bilal <ahbilal@microsoft.com> Co-authored-by: Martin Lopes <54248166+martin389@users.noreply.github.com> Co-authored-by: Martin Lopes <martin389@github.com>
1 parent 215dbc1 commit d8892b6

2 files changed

Lines changed: 249 additions & 0 deletions

File tree

‎content/actions/guides/building-and-testing-net.md‎

Lines changed: 248 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,248 @@
1+
---
2+
title: Building and testing .NET
3+
intro: You can create a continuous integration (CI) workflow to build and test your .NET project.
4+
product: '{% data reusables.gated-features.actions %}'
5+
versions:
6+
free-pro-team: '*'
7+
enterprise-server: '>=2.22'
8+
---
9+
10+
### Introduction
11+
12+
This guide shows you how to build, test, and publish a .NET package.
13+
14+
{% data variables.product.prodname_dotcom %}-hosted runners have a tools cache with preinstalled software, which includes the .NET Core SDK. For a full list of up-to-date software and the preinstalled versions of .NET Core SDK, see [software installed on {% data variables.product.prodname_dotcom %}-hosted runners](/actions/reference/specifications-for-github-hosted-runners).
15+
16+
### Prerequisites
17+
18+
You should already be familiar with YAML syntax and how it's used with {% data variables.product.prodname_actions %}. For more information, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions)."
19+
20+
We recommend that you have a basic understanding of the .NET Core SDK. For more information, see [Getting started with .NET](https://dotnet.microsoft.com/learn).
21+
22+
### Starting with the .NET workflow template
23+
24+
{% data variables.product.prodname_dotcom %} provides a .NET workflow template that should work for most .NET projects, and this guide includes examples that show you how to customize this template. For more information, see the [.NET workflow template](https://github.com/actions/setup-dotnet).
25+
26+
To get started quickly, add the template to the `.github/workflows` directory of your repository.
27+
28+
{% raw %}
29+
```yaml
30+
name: dotnet package
31+
32+
on: [push]
33+
34+
jobs:
35+
build:
36+
37+
runs-on: ubuntu-latest
38+
strategy:
39+
matrix:
40+
dotnet-version: [ '2.2.103', '3.0', '3.1.x' ]
41+
42+
steps:
43+
- uses: actions/checkout@v2
44+
- name: Setup .NET Core SDK ${{ matrix.dotnet }}
45+
uses: actions/setup-dotnet@v1.6.0
46+
with:
47+
dotnet-version: {{ matrix.dotnet-version }}
48+
- name: Install dependencies
49+
run: dotnet restore
50+
- name: Build
51+
run: dotnet build --configuration Release --no-restore
52+
- name: Test
53+
run: dotnet test --no-restore --verbosity normal
54+
```
55+
{% endraw %}
56+
57+
### Specifying a .NET version
58+
59+
To use a preinstalled version of the .NET Core SDK on a {% data variables.product.prodname_dotcom %}-hosted runner, use the `setup-dotnet` action. This action finds a specific version of .NET from the tools cache on each runner, and adds the necessary binaries to `PATH`. These changes will persist for the remainder of the job.
60+
61+
The `setup-dotnet` action is the recommended way of using .NET with {% data variables.product.prodname_actions %}, because it ensures consistent behavior across different runners and different versions of .NET. If you are using a self-hosted runner, you must install .NET and add it to `PATH`. For more information, see the [`setup-dotnet`](https://github.com/marketplace/actions/setup-dotnet).
62+
63+
#### Using multiple .NET versions
64+
65+
{% raw %}
66+
```yaml
67+
name: dotnet package
68+
69+
on: [push]
70+
71+
jobs:
72+
build:
73+
74+
runs-on: ubuntu-latest
75+
strategy:
76+
matrix:
77+
dotnet: [ '2.2.103', '3.0', '3.1.x' ]
78+
79+
steps:
80+
- uses: actions/checkout@v2
81+
- name: Setup dotnet ${{ matrix.dotnet-version }}
82+
uses: actions/setup-dotnet@v1.6.0
83+
with:
84+
dotnet-version: ${{ matrix.dotnet-version }}
85+
# You can test your matrix by printing the current dotnet version
86+
- name: Display dotnet version
87+
run: dotnet --version
88+
```
89+
{% endraw %}
90+
91+
#### Using a specific .NET version
92+
93+
You can configure your job to use a specific version of .NET, such as `3.1.3`. Alternatively, you can use semantic version syntax to get the latest minor release. This example uses the latest minor release of .NET 3.
94+
95+
{% raw %}
96+
```yaml
97+
- name: Setup .NET 3.x
98+
uses: actions/setup-dotnet@v2
99+
with:
100+
# Semantic version range syntax or exact version of a dotnet version
101+
dotnet-version: '3.x'
102+
```
103+
{% endraw %}
104+
105+
### Installing dependencies
106+
107+
{% data variables.product.prodname_dotcom %}-hosted runners have the NuGet package manager installed. You can use the dotnet CLI to install dependencies from the NuGet package registry before building and testing your code. For example, the YAML below installs the `Newtonsoft` package.
108+
109+
{% raw %}
110+
```yaml
111+
steps:
112+
- uses: actions/checkout@v2
113+
- name: Setup dotnet
114+
uses: actions/setup-dotnet@v1.6.0
115+
with:
116+
dotnet-version: '3.1.x'
117+
- name: Install dependencies
118+
run: dotnet add package Newtonsoft.Json --version 12.0.1
119+
```
120+
{% endraw %}
121+
122+
{% if currentVersion == "free-pro-team@latest" %}
123+
124+
#### Caching dependencies
125+
126+
You can cache NuGet dependencies using a unique key, which allows you to restore the dependencies for future workflows with the [`cache`](https://github.com/marketplace/actions/cache) action. For example, the YAML below installs the `Newtonsoft` package.
127+
128+
For more information, see "[Caching dependencies to speed up workflows](/actions/guides/caching-dependencies-to-speed-up-workflows)."
129+
130+
{% raw %}
131+
```yaml
132+
steps:
133+
- uses: actions/checkout@v2
134+
- name: Setup dotnet
135+
uses: actions/setup-dotnet@v1.6.0
136+
with:
137+
dotnet-version: '3.1.x'
138+
- uses: actions/cache@v2
139+
with:
140+
path: ~/.nuget/packages
141+
# Look to see if there is a cache hit for the corresponding requirements file
142+
key: ${{ runner.os }}-nuget-${{ hashFiles('**/packages.lock.json') }}
143+
restore-keys: |
144+
${{ runner.os }}-nuget
145+
- name: Install dependencies
146+
run: dotnet add package Newtonsoft.Json --version 12.0.1
147+
```
148+
{% endraw %}
149+
150+
{% note %}
151+
152+
**Note:** Depending on the number of dependencies, it may be faster to use the dependency cache. Projects with many large dependencies should see a performance increase as it cuts down the time required for downloading. Projects with fewer dependencies may not see a significant performance increase and may even see a slight decrease due to how NuGet installs cached dependencies. The performance varies from project to project.
153+
154+
{% endnote %}
155+
156+
{% endif %}
157+
158+
### Building and testing your code
159+
160+
You can use the same commands that you use locally to build and test your code. This example demonstrates how to use `dotnet build` and `dotnet test` in a job:
161+
162+
{% raw %}
163+
```yaml
164+
steps:
165+
- uses: actions/checkout@v2
166+
- name: Setup dotnet
167+
uses: actions/setup-dotnet@v1.6.0
168+
with:
169+
dotnet-version: '3.1.x'
170+
- name: Install dependencies
171+
run: dotnet restore
172+
- name: Build
173+
run: dotnet build
174+
- name: Test with the dotnet CLI
175+
run: dotnet test
176+
```
177+
{% endraw %}
178+
179+
### Packaging workflow data as artifacts
180+
181+
After a workflow completes, you can upload the resulting artifacts for analysis. For example, you may need to save log files, core dumps, test results, or screenshots. The following example demonstrates how you can use the `upload-artifact` action to upload test results.
182+
183+
For more information, see "[Persisting workflow data using artifacts](/github/automating-your-workflow-with-github-actions/persisting-workflow-data-using-artifacts)."
184+
185+
{% raw %}
186+
```yaml
187+
name: dotnet package
188+
189+
on: [push]
190+
191+
jobs:
192+
build:
193+
194+
runs-on: ubuntu-latest
195+
strategy:
196+
matrix:
197+
dotnet-version: [ '2.2.103', '3.0', '3.1.x' ]
198+
199+
steps:
200+
- uses: actions/checkout@v2
201+
- name: Setup dotnet
202+
uses: actions/setup-dotnet@v1.6.0
203+
with:
204+
dotnet-version: ${{ matrix.dotnet-version }}
205+
- name: Install dependencies
206+
run: dotnet restore
207+
- name: Test with dotnet
208+
run: dotnet test --logger trx --results-directory "TestResults-${{ matrix.dotnet-version }}"
209+
- name: Upload dotnet test results
210+
uses: actions/upload-artifact@v2
211+
with:
212+
name: dotnet-results-${{ matrix.dotnet-version }}
213+
path: TestResults-${{ matrix.dotnet-version }}
214+
# Use always() to always run this step to publish test results when there are test failures
215+
if: ${{ always() }}
216+
```
217+
{% endraw %}
218+
219+
### Publishing to package registries
220+
221+
You can configure your workflow to publish your Dotnet package to a package registry when your CI tests pass. You can use repository secrets to store any tokens or credentials needed to publish your binary. The following example creates and publishes a package to {% data variables.product.prodname_registry %} using `dotnet core cli`.
222+
223+
{% raw %}
224+
```yaml
225+
name: Upload dotnet package
226+
227+
on:
228+
release:
229+
types: [created]
230+
231+
jobs:
232+
deploy:
233+
runs-on: ubuntu-latest
234+
steps:
235+
- uses: actions/checkout@v2
236+
- uses: actions/setup-dotnet@v1
237+
with:
238+
dotnet-version: '3.1.x' # SDK Version to use.
239+
source-url: https://nuget.pkg.github.com/<owner>/index.json
240+
env:
241+
NUGET_AUTH_TOKEN: ${{secrets.GITHUB_TOKEN}}
242+
- run: dotnet build <my project>
243+
- name: Create the package
244+
run: dotnet pack --configuration Release <my project>
245+
- name: Publish the package to GPR
246+
run: dotnet nuget push <my project>/bin/Release/*.nupkg
247+
```
248+
{% endraw %}

‎content/actions/guides/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ layout: product-sublanding
2828
<!-- {% link_in_list /about-continuous-integration %} -->
2929
<!-- {% link_in_list /setting-up-continuous-integration-using-workflow-templates %} -->
3030
<!-- {% link_in_list /building-and-testing-nodejs %} -->
31+
<!-- {% link_in_list /building-and-testing-net %} -->
3132
<!-- {% link_in_list /building-and-testing-powershell %} -->
3233
<!-- {% link_in_list /building-and-testing-python %} -->
3334
<!-- {% link_in_list /building-and-testing-ruby %} -->

0 commit comments

Comments
 (0)