Suggested update to the MAUI Docs on publishing

[rolfbjarne]

From @dansiegel on Tue, 28 Jun 2022 15:50:53 GMT

Steps to Reproduce

This is running the publish from the MacOS Terminal

1. dotnet publish -f:net6.0-ios -c Debug /p:ArchiveOnBuild=true /p:ApplicationDisplayVersion=0.1.0 /p:ApplicationVersion=15 -o ~/repos/demo/MauiCIDemo/publish
2. dotnet publish -f:net6.0-ios -c Debug /p:ArchiveOnBuild=true /p:ApplicationDisplayVersion=0.1.0 /p:ApplicationVersion=15 -o ~/repos/demo/MauiCIDemo/publish -r ios-arm64 (also tried with /p:RuntimeIdentifier=ios-arm64 which had the same result)

Expected Behavior

The first command should work... The second command should have resolved the error encountered on the first.

Actual Behavior

After running the first command:

/usr/local/share/dotnet/packs/Microsoft.iOS.Sdk/15.4.311/targets/Xamarin.Shared.Sdk.Publish.targets(16,3): 
error : A runtime identifier must be specified in order to publish this project. [/Users/dansiegel/repos/demo/MauiCIDemo/MauiCIDemo/MauiCIDemo.csproj]

After running the second command:

/usr/local/share/dotnet/packs/Microsoft.MacCatalyst.Sdk/15.4.311/targets/Xamarin.Shared.Sdk.targets(1744,3): 
error : The RuntimeIdentifier 'ios-arm64' is invalid. [/Users/dansiegel/repos/demo/MauiCIDemo/MauiCIDemo/MauiCIDemo.csproj]

You'll notice btw that while the first error comes out of the Microsoft.iOS.Sdk, specifying the ios-arm64 runtime actually picks up the Microsoft.MacCatalyst.Sdk which is what throws the error for an unrecognized runtime.

Environment

dansiegel@dans-mbp MauiCIDemo % dotnet --version
6.0.301

dansiegel@dans-mbp MauiCIDemo % dotnet workload list

Installed Workload Ids      Installation Source
-----------------------------------------------
wasm-tools                  SDK 6.0.300        
macos                       SDK 6.0.300        
maui-tizen                  SDK 6.0.300        
maui-maccatalyst            SDK 6.0.300        
maui-ios                    SDK 6.0.300        
maui-android                SDK 6.0.300        
ios                         SDK 6.0.300        
maccatalyst                 SDK 6.0.300        
maui                        SDK 6.0.300        
tvos                        SDK 6.0.300        
tizen                       SDK 6.0.300        
android                     SDK 6.0.300        

Use `dotnet workload search` to find additional workloads to install.

Build Logs

See above

Example Project (If Possible)

dotnet new maui

Copied from original issue xamarin/xamarin-macios#15365

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 44286466-fb54-f175-d197-7deee0db1e30
• Version Independent ID: 44286466-fb54-f175-d197-7deee0db1e30
• Content: Publish a .NET MAUI app for iOS - .NET MAUI
• Content Source: docs/ios/deployment/overview.md
• Product: dotnet-mobile
• Technology: dotnet-maui
• GitHub Login: @davidbritch
• Microsoft Alias: dabritch

---

Associated WorkItem - 57839

[rolfbjarne]

From @rolfbjarne on Tue, 28 Jun 2022 17:16:02 GMT

The first one fails because we need to know the runtime identifier very early in the build process, and at that point we don't know whether we're building or publishing, and we default to a simulator runtime identifier, since that's the most common use case.

The second one fails due to NuGet/Home#11653.

You should be able to work around this by adding something like this in the project file:

<PropertyGroup Condition="'$(IsPublishing)'  == 'true' And '$(TargetFramework)' == 'net6.0-ios'">
    <RuntimeIdentifier>ios-arm64</RuntimeIdentifier>
</PropertyGroup>

and then

dotnet publish -f:net6.0-ios -c Debug /p:ArchiveOnBuild=true /p:ApplicationDisplayVersion=0.1.0 /p:ApplicationVersion=15 -o ~/repos/demo/MauiCIDemo/publish /p:IsPublishing=true

[rolfbjarne]

From @dansiegel on Tue, 28 Jun 2022 17:38:51 GMT

Might I suggest an update to the MAUI Docs on publishing

[rolfbjarne]

From @dansiegel on Tue, 28 Jun 2022 17:42:24 GMT

This does seem to resolve the issue however I am only seeing the IPA in the publish directory. Is there a flag we can pass to get the dSYM?

[rolfbjarne]

From @rolfbjarne on Wed, 29 Jun 2022 10:27:38 GMT

@dansiegel try passing /p:NoDSymUtil=false to see if that works

[rolfbjarne]

From @dansiegel on Thu, 30 Jun 2022 20:09:20 GMT

I've updated csproj to automatically set the Runtime based on TargetFramework & Configuration. Then adding the parameter you mentioned I end up with:

dotnet publish -f:net6.0-ios -c Release /p:ArchiveOnBuild=true \
  /p:ApplicationDisplayVersion=0.1.0 /p:ApplicationVersion=15 \
  -o ~/repos/demo/MauiCIDemo/publish /p:NoDSymUtil=false

This doesn't seem to make any difference. This results in the default behavior where the dSYM is generated it's just in bin/ios-arm64/. To be clear the issue wasn't that the dSYM isn't generated... the dSYM is generated, but it's just not getting moved to the publish directory. If you ran something like the above command (with or without the NoDSymUtil parameter) you would see:

• ~/repos/demo/MauiCIDemo/MauiCIDemo/bin/Release/net6.0-ios/ios-arm64/MauiCIDemo.app.dSYM
• ~/repos/demo/MauiCIDemo/publish/MauiCIDemo.ipa

What I would expect to see is the dSYM in the same publish directory as the IPA.

[rolfbjarne]

From @rolfbjarne on Thu, 30 Jun 2022 21:42:09 GMT

Ah yes, we put the .dSYM next to the .app we build, and then we don't move/copy it elsewhere after that.

It should be easy enough to copy it to the publish directory too.

[rolfbjarne]

From @rolfbjarne on Thu, 30 Jun 2022 21:59:17 GMT

I've created an enhancement request for this: xamarin/xamarin-macios#15384 (to avoid conflating multiple problems in a single issue here).

[rolfbjarne]

From @rolfbjarne on Thu, 30 Jun 2022 21:59:44 GMT

Might I suggest an update to the MAUI Docs on publishing

Could you link me to the exact document you read to make sure we're updating the right one?

[rolfbjarne]

From @dansiegel on Fri, 01 Jul 2022 16:04:51 GMT

@rolfbjarne makes perfect sense to move the dSYM request to its own issue...

Could you link me to the exact document you read to make sure we're updating the right one?

https://docs.microsoft.com/en-us/dotnet/maui/ios/deployment/overview#publish

A few issues I have with the publishing docs..

1. They are very focused on publishing from Windows using a Mac Host. While it is technically a valid scenario that should have some documentation, this really should be a separate topic as it's much more normal that you would be Publishing from a Mac. Most people today have some sort of CI pipeline, and this would be a very unusual thing to run from a Windows agent and connect to a remote Mac in CI. The focus around publishing IMHO really should be what is the proper setup/set of command to get what we need on the Mac
2. The RuntimeIdentifier is technically listed, but the importance of when/how it's included is missing...
   • It appears to be optional and is listed as can be specified on the command line.
   • There are so many erroneous notes, particularly around the Windows remote Mac Host scenario that you end up dismissing it entirely, as something that shouldn't be relevant.
   • Something similar to the suggestion above is noted in an earlier section Add code signing to your app, but again this also contains a number of other properties (for code signing), which are repeated as optional CLI parameters & would lead you think that this isn't a requirement for the Runtime Identifier.
3. Regarding the Code Signing section, I would note that these really only would be an issue if you have a lot of certs/profiles on your machine, and shouldn't be required when building in CI as long as you have imported the Cert & Profile you need for the build. I would also be concerned about these docs because this seems to indicate that you should be updating with a very specific cert/profile which people will check into source control and can lead to issues in team environments where devs have different certs.

[rolfbjarne]

From @rolfbjarne on Mon, 04 Jul 2022 11:24:11 GMT

Ok, that doc is stored here: https://github.com/dotnet/docs-maui/blob/main/docs/ios/deployment/overview.md#publish

[adegeo]

Hi @dansiegel Is this specific comment the issue related to docs? #681 (comment)

It's hard to read through everything and completely understand what work is being requested 😁

[dansiegel]

It's hard to read through everything and completely understand what work is being requested

Sounds a bit like the condition of the docs 😆... sorry this is gonna be long. Please feel free to ask any questions, also more than happy to jump on a teams call if it would help.

Seriously though when it comes to publishing an iOS app the docs don't provide a coherent story to begin with, and ultimately lack the critical information that someone needs if they are looking at publishing a net6+ iOS app.

One of the big problems in the docs currently is that they provide confusing information that is really for an edge case that probably needs its own docs rather than being the central focus. Or at the very least need some sort of segregation like we see in the Essentials docs where things get split out by platform. It is clear that when the publishing docs were written, they were written by someone working on a PC connecting to a remote mac host. While that's a legitimate (though likely very rare) edge case scenario, for someone looking to publish this needs to be clear from the perspective of I'm building on a Mac Host.

Because of all of the fluff about building on Windows and connecting to a remote Mac and all of the "notes" that go along with it, it distracts from the information people need when deciding what parameters they might actually need to pass dotnet publish... and even if you address the much needed notes regarding information that is missing it would be easy to miss because of the surrounding fluff that is irrelevant.

CRITICAL MISSING/WRONG INFORMATION

Currently buried in Add code signing data to your app project is an example showing that RuntimeIdentifier is specified in a conditional PropertyGroup. Later on in Publish section of the docs we see a long list of MSBuild properties including the RuntimeIdentifier with the following note that tells us that we can set any of the following properties from the cli or in the csproj.

In addition, the following common parameters can be specified on the command line if they aren't provided in a in your project file

The problem is as discussed in the original thread xamarin/xamarin-macios#15365, this just simply doesn't work as the RuntimeIdentifier must absolutely be specified in your csproj or some other .props file. Which makes the information in the existing Publish docs just plain false.

What's Needed

1. Either completely rewrite these docs from the perspective of someone on a Mac Host... or segregate similar to how the Essentials docs segregate platform specifics for Android, iOS, Windows
2. Be sure that the information is actually correct for the RuntimeIdentifier... even if it notes that this is linked to an open issue and the behavior may change in the future where dotnet publish is able to infer the correct runtime without explicitly setting it.
3. For properties like the RuntimeIdentifier list what valid identifiers there are for iOS
4. For Code Signing / Provisioning lets stop assuming people are doing everything in Visual Studio. Yes the IDE lets us cheat but one of the purposes of docs is to understand how things work. So lets be sure that the docs tell a story that includes what values you might use for automatic detection for Development, Ad-Hoc, Enterprise, App Store releases... and how to determine what a specific cert/profile value should be if they wanted to be explicit.
5. Let's think Continuous Integration. Yes building on a local machine is important, but chances are if we're discussing Publishing, most developers now are automating this task in CI and they're not interested in docs that are focused on "Right Click Publish". It needs to be how do I publish this for my team to test when it's building on a remote build agent that I don't have direct access to...

Hope that helps.

[adegeo]

Thank you for the feedback. The .NET CLI is supposed to be able to set all of those properties, such as the RuntimeIdentifier. It seems what @rolfbjarne is suggesting is a workaround to the problem that the identifier isn't being picked up soon enough by the build system? It's the first I've ever seen of that happening. @rolfbjarne, is this something that is going to be fixed? For CI and things like that, you got to be able to set these on the command line. Is something in the MSBuild config overridding RuntimeIdentifier and then you need to use the workaround for IsPublishing detection?? The docs are correct in the sense of "it's supposed to work that way, which is why it was ported over" and possibly at one point it did work that way. We'll have to look at how to fix this up, but I still really want to know if this is actually a bug or not.

As to the reason it's still Windows-focused, is that the tooling for macOS hasn't been fully ready for a full end-to-end create-an-app-in-mac-publish-on-mac. It seems that the VS for Mac 17.3 preview release will be the official version to support MAUI apps directly. However, that preview started a month after the GA of .NET MAUI, being 2 months ago, and we're still playing catch up to preview releases and service releases, etc. And yeah, we need to do more of "do it all via CLI (signing/provisioning) and also the IDE"

Anyway, thank you for the feedback on the article, it will help us get it sorted.

Tagging @davidbritch for priority

[rolfbjarne]

For CI and things like that, you got to be able to set these on the command line.

It's perfectly possible to set the RuntimeIdentifier on the command line.

What I said was that if you don't set a RuntimeIdentifer (either on the command line or in the csproj), we'll default to a simulator RuntimeIdentifier, because:

1. Usually when developers build their app the most common scenario is to build for the simulator (while debugging).
2. We have to set the RuntimeIdentifier very early in the build process, and at that point we don't know whether you're building or publishing, so we can't have a different default RuntimeIdentifier for dotnet build and dotnet publish.

To make things worse, passing the RuntimeIdentifier on the command line is likely to run into this problem if there are multiple target frameworks in the project file: dotnet/sdk#21877

Taking into account both of these problems, a solution I came up with was to add this to the project file:

<PropertyGroup Condition="'$(IsPublishing)'  == 'true' And '$(TargetFramework)' == 'net6.0-ios'">
    <RuntimeIdentifier>ios-arm64</RuntimeIdentifier>
</PropertyGroup>

and then publish like this:

$ dotnet publish -f:net6.0-ios /p:IsPublishing=true ...

of course this could be done with configurations instead:

<PropertyGroup Condition="'$(Configuration)'  == 'Release' And '$(TargetFramework)' == 'net6.0-ios'">
    <RuntimeIdentifier>ios-arm64</RuntimeIdentifier>
</PropertyGroup>

and then publish like this:

$ dotnet publish -f:net6.0-ios -c Release ...

Either way works, it's just a matter of taste (and there are probably other ways to do the same thing too).

[dansiegel]

A few things to note here...

When it comes to the docs I think we can safely say someone who is looking for docs on publishing cares about generating an IPA to potentially ship to the store or for internal use and not the Simulator. Given that... if the behavior was that it builds by default for the simulator this would need to be noted and documented how to build for the device in the docs...

That said my actual experience is that specifying the runtime in the CLI arguments does NOT work. @rolfbjarne please go back and look at the initial comment and you will notice that running either of the following

• dotnet publish -f:net6.0-ios -c Debug /p:ArchiveOnBuild=true -o ~/repos/demo/MauiCIDemo/publish -r ios-arm64
• dotnet publish -f:net6.0-ios -c Debug /p:ArchiveOnBuild=true -o ~/repos/demo/MauiCIDemo/publish /p:RuntimeIdentifier=ios-arm64

Resulted in this error

/usr/local/share/dotnet/packs/Microsoft.MacCatalyst.Sdk/15.4.311/targets/Xamarin.Shared.Sdk.targets(1744,3): 
error : The RuntimeIdentifier 'ios-arm64' is invalid.

Whether by design or bug, currently you MUST supply the RuntimeIdentifier via build props or in the csproj. Everything else including the IsPublishing can come in from CLI arguments.