You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -4,71 +4,36 @@ This page contains steps to build and run the .NET MAUI repository from source.
4
4
5
5
## Initial setup
6
6
### Windows
7
-
- Install VS 17.8 or newer
7
+
- Install VS 17.10 or newer
8
8
- Follow [these steps](https://learn.microsoft.com/dotnet/maui/get-started/installation?tabs=vswin) to include MAUI
9
-
- Select the 20348 SDK option inside Individual Components or [install 20348 manually](https://go.microsoft.com/fwlink/?linkid=2164145). If you know you have 20348 installed but are still getting an error around this SDK missing, trying uninstalling and reinstalling the SDK.
10
9
- If building iOS with pair to Mac: Install current stable Xcode on your Mac. Install from the [App Store](https://apps.apple.com/us/app/xcode/id497799835?mt=12) or [Apple Developer portal](https://developer.apple.com/download/more/?name=Xcode)
11
10
- If you're missing any of the Android SDKs, Visual Studio should prompt you to install them. If it doesn't prompt you then use the [Android SDK Manager](https://learn.microsoft.com/xamarin/android/get-started/installation/android-sdk) to install the necessary SDKs.
- Follow [these steps](https://learn.microsoft.com/en-us/dotnet/maui/get-started/installation?view=net-maui-8.0&tabs=visual-studio-code), installing VS Code, MAUI extension, .NET8, Xcode, OpenJDK, and Android SDK
16
-
- Install Mono from [Mono Project](https://www.mono-project.com)
17
-
- For Xcode, you can install from the [App Store](https://apps.apple.com/us/app/xcode/id497799835?mt=12) or [Apple Developer portal](https://developer.apple.com/download/more/?name=Xcode)
18
-
- As of 26 March 2024, Xcode 15.3 is not yet supported. Check [this issue](https://github.com/dotnet/maui/issues/21057) for updates
19
-
- Edit your `.zprofile` file to ensure that the following environment variables are set/modified (you may need to adjust the version of OpenJDK):
- Follow the steps for installing the .NET MAUI Dev Kit for VS Code: https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.dotnet-maui
31
16
32
17
## Building the Build Tasks
33
18
Before opening the solution in Visual Studio / VS Code you **MUST** build the build tasks.
34
19
35
-
### Windows
36
-
- Do this to build the build tasks and launch Visual Studio, automatically opening the default solution:
20
+
1. Open a command prompt/terminal/shell window
21
+
1. Navigate to the location of your cloned `dotnet/maui` repo, for example:
22
+
```shell
23
+
cd\repos\maui
24
+
```
25
+
1. Run these commands:
26
+
```dotnetcli
27
+
dotnet tool restore
28
+
dotnet build ./Microsoft.Maui.BuildTasks.slnf
29
+
```
37
30
38
-
```dotnetcli
39
-
dotnet tool restore
40
-
dotnet cake --target=VS --workloads=global
41
-
```
31
+
## Windows
32
+
Open the `Microsoft.Maui-windows.slnf` file in Visual Studio from the root of the repo.
42
33
43
-
- OR do this to just build the build tasks. You can then launch Visual Studio manually and open the solution of your choosing:
34
+
## Mac
44
35
45
-
```dotnetcli
46
-
dotnet tool restore
47
-
dotnet build ./Microsoft.Maui.BuildTasks.slnf
48
-
```
49
-
50
-
### Mac
51
-
- Do this to build the tasks and open the Visual Studio Code codespace:
52
-
53
-
```dotnetcli
54
-
dotnet tool restore
55
-
dotnet cake --target=VSCode --workloads=global
56
-
```
57
-
58
-
*NOTE*: `--workloads=global` means use the normal (globally installed) .NET workloads.
59
-
60
-
61
-
## Available Solutions
62
-
- Microsoft.Maui.sln
63
-
- Kitchen sink solution. This includes all of the `Compatibility` projects and all of the platforms that we compile for. It is very unlikely you will need to use this solution for development.
64
-
- Microsoft.Maui-dev.sln
65
-
- `Microsoft.Maui.sln` but without the `Compatibility` projects. Because we can't detect solution filters inside `MSBuild` we had to create a separate `sln` without the `Compatibility` projects.
66
-
- Microsoft.Maui-windows.slnf
67
-
- `Microsoft.Maui-dev.sln` with all of the targets you can't build on `Windows` removed (GTK/Catalyst). Default solution on Windows.
68
-
- Microsoft.Maui-mac.slnf
69
-
- `Microsoft.Maui-dev.sln` with all of the `Windows` targets filtered out. Legacy solution for VS Mac.
70
-
- Microsoft.Maui-vscode.sln
71
-
- Solution for VS Code (VS Code doesn't support solution filters)
36
+
Open the root folder of the repository in VS Code.
72
37
73
38
*NOTE*: IntelliSense takes a decent amount of time to fully process your solution. It will eventually work through all the necessary tasks. If you are having IntelliSense issues, usually unloading/reloading the `maui.core` and `maui.controls` projects will resolve.
74
39
@@ -81,7 +46,7 @@ Use ‘main’ for bug fixes that don’t require API changes. For new features
- *Controls.DeviceTests*: .NET MAUI Controls Visual Runner for running device based xunit tests. This is useful for tests that require XAML features
127
-
- *Core.DeviceTests*: .NET MAUI Core Visual Runner for running device based xunit tests. This is for tests that don't require any MAUI Controls based features
128
-
- *Essentials.DeviceTests*: Visual Runner running all the .NET MAUI essentials xunit tests.
129
-
- *MauiBlazorWebView.DeviceTests*: Visual Runner for BlazorWebView tests.
These are tests used for exercising the UI through accessibility layers to simulate user interactions
136
-
137
-
```
138
-
├── Controls
139
-
│ ├── tests
140
-
│ ├── ├── Controls.TestCases.App
141
-
│ │ ├── Controls.TestCases.Shared.Tests
142
-
```
143
-
144
-
- *Controls.TestCases.App*: .NET MAUI Sample used for the automated UI tests
145
-
- *Controls.TestCases.Shared.Tests*: .NET MAUI library used to define the UI tests
146
-
147
-
Each platform has a specific UI tests library project where it is possible to add specific tests per platform.
148
-
149
-
```
150
-
├── Controls
151
-
│ ├── tests
152
-
│ │ ├── Controls.TestCases.Android.Tests
153
-
│ │ ├── Controls.TestCases.iOS.Tests
154
-
│ │ ├── Controls.TestCases.Mac.Tests
155
-
│ │ ├── Controls.TestCases.WinUI.Tests
156
-
```
157
-
158
-
### Unit Test Projects
159
-
160
-
These are tests that will not run on a device. This is useful for testing device independent logic.
161
-
162
-
```
163
-
├── Controls
164
-
│ ├── test
165
-
│ │ ├── Controls.Core.UnitTests
166
-
├── Core
167
-
│ ├── test
168
-
│ │ ├── Core.UnitTests
169
-
├── Essentials
170
-
│ ├── test
171
-
│ │ ├── Essentials.UnitTests
172
-
```
173
-
174
-
### Reproducing an Issue/Debugging .NET MAUI Code
175
-
Open the .NET MAUI workspace in VSCode.
176
-
In VSCode, selectthe device that you will be testing on. Using the command palette (ctrl-shift-P/command-shift-P) type`pick device` and
177
-
you will be presented with a set of choices for your target device (Android, iOS, etc). Select one.
178
-
There is a sample project in`src/Controls/samples/Controls.Sample.Sandbox`. This is an empty project
179
-
into which you can add your code to reproduce an issue and also set breakpoints in .NET MAUI source code.
180
-
Let VSCode know this is the project you want to selectby going to the command palette (ctrl-shift-P/command-shift-P)
181
-
and typing `pick startup` and select".NET MAUI: Pick Startup Project" and select the Sandbox project.
182
-
183
-
Before using the command palette for the first time, you may have to wait a minute
184
-
for intellisense and other tasks to complete before using the command palette. If the project hasn't
185
-
'settled' yet, you will see an error "Pick Startup Project has resulted in an error."
186
-
187
-
*Note:* When you are committing your PR, do not include your changes to the Sandbox project.
188
-
189
-
### Integration Tests
190
-
191
-
The Integration test project under `src/TestUtils/src/Microsoft.Maui.IntegrationTests` contains tests which build and/or run MAUI templates or other projects.
192
-
193
-
These tests can be ran using the test explorer in VS, or from command line with `dotnet test`. Here's how to run an individual test with parameters from command line:
194
-
195
-
```bash
196
-
dotnet test src/TestUtils/src/Microsoft.Maui.IntegrationTests --logger "console;verbosity=diagnostic" --filter "Name=Build\(%22maui%22,%22net7.0%22,%22Debug%22,False\)"
197
-
```
198
-
199
-
You can find detailed information about testing in the [Wiki](https://github.com/dotnet/maui/wiki/Testing).
200
-
201
-
### Additional Cake Commands
202
-
203
-
#### Clean
204
-
`--clean`
205
-
- This will do a recursive delete of all your obj/bin folders. This is helpful if for some reason your repository is in a bad state and you don't want to go as scorched earth as `git clean -xdf`
*Note* you will have to `git clean -xdf` your project if you change or add platforms.
218
-
219
-
### Blazor Desktop
220
-
221
-
To build and run Blazor Desktop samples, check out the [Blazor Desktop](https://github.com/dotnet/maui/wiki/Blazor-Desktop) wiki topic.
222
-
223
-
### Android
224
-
225
-
To workaround a performance issue, all `Resource.designer.cs`
226
-
generation is disabled for class libraries in this repo.
227
-
228
-
If you need to add a new `@(AndroidResource)` value to be used from C#
229
-
code in .NET MAUI:
230
-
231
-
1. Comment out the `<PropertyGroup>` in `Directory.Build.targets` that
232
-
sets `$(AndroidGenerateResourceDesigner)` and
233
-
`$(AndroidUseIntermediateDesignerFile)` to `false`.
234
-
235
-
2. Build .NET MAUI as you normally would. You will get compiler errors
236
-
about duplicate fields, but `obj\Debug\net[current_sdk_version]-android\Resource.designer.cs`
237
-
should now be generated.
238
-
239
-
3. Open `obj\Debug\net[current_sdk_version]-android\Resource.designer.cs`, and find the
240
-
field you need such as:
241
-
242
-
```csharp
243
-
// aapt resource value: 0x7F010000
244
-
public static int foo = 2130771968;
245
-
```
246
-
247
-
4. Copy this field to the `Resource.designer.cs` checked into source
248
-
control, such as: `src\Controls\src\Core\Platform\Android\Resource.designer.cs`
249
-
250
-
5. Restore the commented code in `Directory.Build.targets`.
251
-
252
-
253
-
# Advanced Scenarios
254
-
255
-
### Compile using a local `bin\dotnet` via `dotnet-local.*`
256
-
257
-
This method will use the .NET and workload versions that are specific to the branch you are on, which is a good way to ensure compatibility.
258
-
259
-
Use `dotnet-local.cmd` on Windows or `dotnet-local.sh` on Unix to ensure that `PATH` is set consistently.
260
-
261
-
#### Cake
262
-
263
-
You can run a `Cake` target to bootstrap .NET SDK in `bin\dotnet` and launch Visual Studio:
264
-
265
-
```dotnetcli
266
-
dotnet tool restore
267
-
dotnet cake --target=VS
268
-
```
269
-
270
-
There is also a `VSCode` target for launching Visual Studio Code.
271
-
272
-
```dotnetcli
273
-
dotnet tool restore
274
-
dotnet cake --target=VSCode
275
-
```
276
-
277
-
#### Testing branch against your project
278
-
`--sln=<Path to SLN>`
279
-
- This will pack .NET and then open a VS instance using the local pack. This is useful if you want to check to see if the changes in a branch will address your particular issues. Pack only runs the first time so you will need to explicitly add the `--pack` flag if you make changes and need to repack.
- This creates .NET MAUI packs inside the local dotnet install. This lets you use the CLI commands with the local dotnet to create/deploy with any changes that have been made on that branch (including template changes).
Note: the `-m:1` is important as it restricts MSBuild to 1 node.
356
-
357
-
Once MSBuild starts it will print the following
358
-
359
-
```dotnetcli
360
-
Waiting for debugger to attach (dotnet PID xxxx). Press enter to continue...
361
-
```
362
-
363
-
You need to copy the PID value so we can use this in the IDE. For Visual Studio you can use the `Attach to Process` menu option, while you have the Microsoft.Maui.sln solution open. For VSCode open the workspace then use the `Attach to Process` Run and Debug option. You will be prompted for the PID and it will then connect.
68
+
- *Essentials.Sample*: Full gallery demonstrating the library previously known as Essentials. These are all the non UI related MAUI APIs.
364
69
365
-
Once connected go back to your command prompt and press ENTER so that the MSBuild process can continue.
70
+
### Testing
366
71
367
-
You will be able to set breakpoints in Tasks (but not Targets) and step through code from this point on.
If you want to test in-tree in VSCode the `Build Platform Sample` command will ask you if you want to debug MSBuild tasks and fill in the `MSBUILDDEBUGONSTART` for you. The PID text will appear in the `Terminal` window in VSCode. You can then use the `Attach to Process` Run and Debug option to attach to the process.
0 commit comments