Add publishing guidance for macOS applications #49417

Copilot · 2025-10-22T18:19:55Z

Summary

Created a new macOS publishing documentation page at docs/core/deploying/macos.md that provides:

Prerequisites for macOS publishing (Apple Developer Account, Xcode Command Line Tools, .NET SDK)
Instructions to publish the app using methods from the main deployment overview (with link to /dotnet/core/deploying/)
Information about the native apphost and required entitlements
- Apps not published as Native AOT require com.apple.security.cs.allow-jit entitlement
- Apps published as Native AOT require no entitlements
- Links to Native AOT documentation for more information
- Optional entitlements for debugging and diagnostics: com.apple.security.get-task-allow for dump collection and com.apple.security.cs.debugger for attaching debuggers
Guidance to sign and notarize using Apple's documentation (with link to Apple's notarization guide)
Warning about application crashes when executing restricted operations without proper signing/notarization

The documentation follows all repository writing style guidelines:

Active voice with second person ("you")
Conversational tone
Sentence case headings
Proper frontmatter with ai-usage disclosure
Clear structure with prerequisites, instructions, and warnings
Correct Apple branding (macOS)
Proper links to related documentation
Clear terminology (Native AOT vs non-Native AOT apps instead of CoreCLR terminology)

This pull request was created as a result of the following prompt from Copilot chat.

Add a new documentation page for publishing .NET applications on Mac OS. This page, located at docs/core/deploying/macos.md, provides guidance on the additional requirements for publishing .NET apps on Mac OS, including code signing, notarization, and entitlements. The documentation includes:

Prerequisites (Apple Developer Account, Xcode Command Line Tools, .NET SDK)

Instructions to build and publish the app

Notes about the native apphost and required entitlements

Guidance to sign and notarize the app using Apple documentation

A warning about security warnings if not signed/notarized

Page authored by @agocke.

Refer to the following file content:

title: Mac OS
description: Learn how to publish .NET applications for Mac OS, including signing, notarization, and app entitlements.
author: @agocke
ms.date: [DATE]
ms.topic: how-to

Publish .NET Apps for Mac OS

Publishing .NET applications for Mac OS requires several additional steps compared to other platforms, due to Apple's security requirements.

Requirements

Apple Developer Account: Needed for code signing and notarization.

Xcode Command Line Tools: Provides codesign, altool, and other utilities.

.NET SDK: Ensure you have the latest .NET SDK installed.

Steps to Publish

1. Build and Publish Your App

Use one the methods described under Publishing to produce a application. This can either be a framework-dependent or self-contained application.

2. Apphost and Entry Point

.NET creates a native apphost executable as the entry point for your app. This apphost must be signed and, if your app uses special capabilities, it must be assigned the appropriate entitlements.

For CoreCLR apps, the com.apple.security.cs.allow-jit entitlement is required.

For Native AOT apps, no entitlements are required.

3. Sign and notarize

Use Apple's developer documentation to sign and notarize the binary.

Note: Failing to sign and notarize your app may result in users seeing security warnings or being unable to launch your application.

Create a pull request titled "Add publishing guidance for Mac OS applications".

Original prompt

Add a new documentation page for publishing .NET applications on Mac OS. This page, located at docs/core/deploying/macos.md, provides guidance on the additional requirements for publishing .NET apps on Mac OS, including code signing, notarization, and entitlements. The documentation includes:

Prerequisites (Apple Developer Account, Xcode Command Line Tools, .NET SDK)

Instructions to build and publish the app

Notes about the native apphost and required entitlements

Guidance to sign and notarize the app using Apple documentation

A warning about security warnings if not signed/notarized

Page authored by @agocke.

Refer to the following file content:

title: Mac OS
description: Learn how to publish .NET applications for Mac OS, including signing, notarization, and app entitlements.
author: @agocke
ms.date: [DATE]
ms.topic: how-to

Publish .NET Apps for Mac OS

Publishing .NET applications for Mac OS requires several additional steps compared to other platforms, due to Apple's security requirements.

Requirements

Apple Developer Account: Needed for code signing and notarization.

Xcode Command Line Tools: Provides codesign, altool, and other utilities.

.NET SDK: Ensure you have the latest .NET SDK installed.

Steps to Publish

1. Build and Publish Your App

Use one the methods described under Publishing to produce a application. This can either be a framework-dependent or self-contained application.

2. Apphost and Entry Point

.NET creates a native apphost executable as the entry point for your app. This apphost must be signed and, if your app uses special capabilities, it must be assigned the appropriate entitlements.

For CoreCLR apps, the com.apple.security.cs.allow-jit entitlement is required.

For Native AOT apps, no entitlements are required.

3. Sign and notarize

Use Apple's developer documentation to sign and notarize the binary.

Note: Failing to sign and notarize your app may result in users seeing security warnings or being unable to launch your application.

Create a pull request titled "Add publishing guidance for Mac OS applications".

This pull request was created as a result of the following prompt from Copilot chat.

Add a new documentation page for publishing .NET applications on Mac OS. This page, located at docs/core/deploying/macos.md, provides guidance on the additional requirements for publishing .NET apps on Mac OS, including code signing, notarization, and entitlements. The documentation includes:

Prerequisites (Apple Developer Account, Xcode Command Line Tools, .NET SDK)

Instructions to build and publish the app

Notes about the native apphost and required entitlements

Guidance to sign and notarize the app using Apple documentation

A warning about security warnings if not signed/notarized

Page authored by @agocke.

Refer to the following file content:

title: Mac OS
description: Learn how to publish .NET applications for Mac OS, including signing, notarization, and app entitlements.
author: @agocke
ms.date: [DATE]
ms.topic: how-to

Publish .NET Apps for Mac OS

Publishing .NET applications for Mac OS requires several additional steps compared to other platforms, due to Apple's security requirements.

Requirements

Apple Developer Account: Needed for code signing and notarization.

Xcode Command Line Tools: Provides codesign, altool, and other utilities.

.NET SDK: Ensure you have the latest .NET SDK installed.

Steps to Publish

1. Build and Publish Your App

Use one the methods described under Publishing to produce a application. This can either be a framework-dependent or self-contained application.

2. Apphost and Entry Point

.NET creates a native apphost executable as the entry point for your app. This apphost must be signed and, if your app uses special capabilities, it must be assigned the appropriate entitlements.

For CoreCLR apps, the com.apple.security.cs.allow-jit entitlement is required.

For Native AOT apps, no entitlements are required.

3. Sign and notarize

Use Apple's developer documentation to sign and notarize the binary.

Note: Failing to sign and notarize your app may result in users seeing security warnings or being unable to launch your application.

Create a pull request titled "Add publishing guidance for Mac OS applications".

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

Internal previews

📄 File	🔗 Preview link
docs/core/deploying/macos.md	docs/core/deploying/macos

Co-authored-by: agocke <[email protected]>

docs/core/deploying/macos.md

Co-authored-by: agocke <[email protected]>

Copilot

Pull Request Overview

This PR adds new documentation for publishing .NET applications on Mac OS, addressing Apple-specific requirements like code signing, notarization, and entitlements. The document is AI-assisted and follows the repository's style guidelines.

Key changes:

New how-to guide covering Mac OS publishing prerequisites and steps
Documentation of platform-specific entitlement requirements for CoreCLR vs Native AOT apps
Security guidance on signing and notarization requirements

docs/core/deploying/macos.md

agocke · 2025-10-22T19:08:48Z

cc @mmitche @jkoritzinsky @jjonescz

docs/core/deploying/macos.md

Co-authored-by: agocke <[email protected]>

mmitche · 2025-10-23T13:07:03Z

docs/core/deploying/macos.md

+
+## Publish your app
+
+Use one of the methods described in the [.NET application publishing overview](index.md) to produce an application. You can create either a framework-dependent or self-contained application.


index.md file not found.

Maybe link to publishing docs? https://learn.microsoft.com/en-us/dotnet/core/deploying/

@copilot please fix

Fixed in commit e18a988. Changed the link from index.md to /dotnet/core/deploying/ to point to the published documentation.

docs/core/deploying/macos.md

mmitche · 2025-10-23T13:08:40Z

docs/core/deploying/macos.md

+
+## Sign and notarize
+
+Use Apple's developer documentation to sign and notarize the binary.


Link to apple's developer docs?

Added link to Apple's notarization documentation in commit e18a988.

Co-authored-by: agocke <[email protected]>

jkotas · 2025-10-24T19:03:41Z

docs/core/deploying/macos.md

+
+.NET creates a native *apphost* executable as the entry point for your app. This apphost must be signed and, if your app uses special capabilities, it must be assigned the appropriate **entitlements**.
+
+### Entitlements for CoreCLR apps


"CoreCLR apps" is not something that we explain anywhere. We should explain this as apps published as Native AOT vs. apps not published as Native AOT. Also, link to Native AOT publishing topic from here.

Updated in commit e97042e. Replaced "CoreCLR apps" terminology with "apps not published as Native AOT" and "apps published as Native AOT", and added links to the Native AOT documentation.

Co-authored-by: jkotas <[email protected]>

jkotas · 2025-10-24T19:12:29Z

docs/core/deploying/macos.md

+
+## Prerequisites
+
+Before you publish your .NET application for macOS, ensure you have the following:


Is this talking about dotnet publish or some other kind of publish? I assume that it is the latter. Does it need clarification?

Initial plan

6828cd0

Copilot AI assigned Copilot and agocke Oct 22, 2025

Copilot started work on behalf of agocke October 22, 2025 18:20 View session

Add Mac OS publishing documentation

7676183

Co-authored-by: agocke <[email protected]>

dotnet-policy-service bot added the dotnet-fundamentals/svc label Oct 22, 2025

Copilot AI changed the title ~~[WIP] Add documentation page for publishing .NET applications on Mac OS~~ Add publishing guidance for Mac OS applications Oct 22, 2025

Copilot AI requested a review from agocke October 22, 2025 18:28

Copilot finished work on behalf of agocke October 22, 2025 18:28

agocke reviewed Oct 22, 2025

View reviewed changes

docs/core/deploying/macos.md Outdated Show resolved Hide resolved

Copilot started work on behalf of agocke October 22, 2025 18:33 View session

Update warning message about unsigned apps

18f8a41

Co-authored-by: agocke <[email protected]>

Copilot AI requested a review from agocke October 22, 2025 18:35

Copilot finished work on behalf of agocke October 22, 2025 18:35

agocke marked this pull request as ready for review October 22, 2025 19:02

agocke requested review from a team and adegeo as code owners October 22, 2025 19:02

Copilot AI review requested due to automatic review settings October 22, 2025 19:02

Copilot AI reviewed Oct 22, 2025

View reviewed changes

jkoritzinsky reviewed Oct 22, 2025

View reviewed changes

docs/core/deploying/macos.md Outdated Show resolved Hide resolved

Copilot started work on behalf of agocke October 22, 2025 20:48 View session

Fix macOS branding and add debugging entitlements

115eefc

Co-authored-by: agocke <[email protected]>

Copilot AI changed the title ~~Add publishing guidance for Mac OS applications~~ Add publishing guidance for macOS applications Oct 22, 2025

Copilot finished work on behalf of agocke October 22, 2025 20:54

Copilot started work on behalf of agocke October 22, 2025 20:54 View session

Copilot finished work on behalf of agocke October 22, 2025 20:56

agocke approved these changes Oct 22, 2025

View reviewed changes

jjonescz approved these changes Oct 23, 2025

View reviewed changes

mmitche reviewed Oct 23, 2025

View reviewed changes

docs/core/deploying/macos.md Show resolved Hide resolved

mmitche reviewed Oct 23, 2025

View reviewed changes

Copilot started work on behalf of agocke October 23, 2025 15:55 View session

Add links to publishing overview and Apple notarization docs

e18a988

Co-authored-by: agocke <[email protected]>

Copilot AI requested a review from agocke October 23, 2025 15:59

Copilot finished work on behalf of agocke October 23, 2025 15:59

jkoritzinsky approved these changes Oct 24, 2025

View reviewed changes

jkotas reviewed Oct 24, 2025

View reviewed changes

Copilot started work on behalf of jkotas October 24, 2025 19:04 View session

Clarify Native AOT terminology and add links

e97042e

Co-authored-by: jkotas <[email protected]>

Copilot finished work on behalf of jkotas October 24, 2025 19:08

Copilot AI requested a review from jkotas October 24, 2025 19:08

jkotas approved these changes Oct 24, 2025

View reviewed changes

jkotas reviewed Oct 24, 2025

View reviewed changes

jkotas self-requested a review October 24, 2025 19:13


		## Publish your app

		Use one of the methods described in the [.NET application publishing overview](index.md) to produce an application. You can create either a framework-dependent or self-contained application.


		## Sign and notarize

		Use Apple's developer documentation to sign and notarize the binary.


		.NET creates a native apphost executable as the entry point for your app. This apphost must be signed and, if your app uses special capabilities, it must be assigned the appropriate entitlements.

		### Entitlements for CoreCLR apps


		## Prerequisites

		Before you publish your .NET application for macOS, ensure you have the following:

Add publishing guidance for macOS applications #49417

Are you sure you want to change the base?

Add publishing guidance for macOS applications #49417

Conversation

Copilot AI commented Oct 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

title: Mac OS description: Learn how to publish .NET applications for Mac OS, including signing, notarization, and app entitlements. author: @agocke ms.date: [DATE] ms.topic: how-to

Publish .NET Apps for Mac OS

Requirements

Steps to Publish

1. Build and Publish Your App

2. Apphost and Entry Point

3. Sign and notarize

Use Apple's developer documentation to sign and notarize the binary.

title: Mac OS description: Learn how to publish .NET applications for Mac OS, including signing, notarization, and app entitlements. author: @agocke ms.date: [DATE] ms.topic: how-to

Publish .NET Apps for Mac OS

Requirements

Steps to Publish

1. Build and Publish Your App

2. Apphost and Entry Point

3. Sign and notarize

Use Apple's developer documentation to sign and notarize the binary.

title: Mac OS description: Learn how to publish .NET applications for Mac OS, including signing, notarization, and app entitlements. author: @agocke ms.date: [DATE] ms.topic: how-to

Publish .NET Apps for Mac OS

Requirements

Steps to Publish

1. Build and Publish Your App

2. Apphost and Entry Point

3. Sign and notarize

Use Apple's developer documentation to sign and notarize the binary.

Internal previews

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

agocke commented Oct 22, 2025

Uh oh!

Uh oh!

mmitche Oct 23, 2025

Choose a reason for hiding this comment

Uh oh!

mmitche Oct 23, 2025

Choose a reason for hiding this comment

Uh oh!

agocke Oct 23, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 23, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mmitche Oct 23, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 23, 2025

Choose a reason for hiding this comment

Uh oh!

jkotas Oct 24, 2025

Choose a reason for hiding this comment

Uh oh!

jkotas Oct 24, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 24, 2025

Choose a reason for hiding this comment

Uh oh!

jkotas Oct 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Copilot AI commented Oct 22, 2025 •

edited

Loading

title: Mac OS
description: Learn how to publish .NET applications for Mac OS, including signing, notarization, and app entitlements.
author: @agocke
ms.date: [DATE]
ms.topic: how-to

title: Mac OS
description: Learn how to publish .NET applications for Mac OS, including signing, notarization, and app entitlements.
author: @agocke
ms.date: [DATE]
ms.topic: how-to

title: Mac OS
description: Learn how to publish .NET applications for Mac OS, including signing, notarization, and app entitlements.
author: @agocke
ms.date: [DATE]
ms.topic: how-to

jkotas Oct 24, 2025 •

edited

Loading