Skip to content

Commit 382dbc6

Browse files
karann-msftkarann-msft
authored
Merge pull request NuGet#1661 from NuGet/karann-msft-icons
icon docs
2 parents d96275b + b988925 commit 382dbc6

File tree

7 files changed

+218
-4
lines changed

7 files changed

+218
-4
lines changed

‎docs/TOC.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -231,6 +231,9 @@
231231
### [NU5035](reference/errors-and-warnings/NU5035.md)
232232
### [NU5036](reference/errors-and-warnings/NU5036.md)
233233
### [NU5037](reference/errors-and-warnings/NU5037.md)
234+
### [NU5046](reference/errors-and-warnings/NU5046.md)
235+
### [NU5047](reference/errors-and-warnings/NU5047.md)
236+
### [NU5048](reference/errors-and-warnings/NU5048.md)
234237
### [NU5100](reference/errors-and-warnings/NU5100.md)
235238
### [NU5101](reference/errors-and-warnings/NU5101.md)
236239
### [NU5102](reference/errors-and-warnings/NU5102.md)

‎docs/reference/Errors-and-Warnings.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,4 +38,5 @@ The errors and warnings listed here are available only with [PackageReference-ba
3838
| NuGet internal warnings | [NU1500](./errors-and-warnings/NU1500.md) |
3939
| Signed packages warnings (creation and verification) | [NU3000](./errors-and-warnings/NU3000.md), [NU3002](./errors-and-warnings/NU3002.md), [NU3003](./errors-and-warnings/NU3003.md), [NU3006](./errors-and-warnings/NU3006.md), [NU3007](./errors-and-warnings/NU3007.md), [NU3009](./errors-and-warnings/NU3009.md), [NU3010](./errors-and-warnings/NU3010.md), [NU3011](./errors-and-warnings/NU3011.md), [NU3012](./errors-and-warnings/NU3012.md), [NU3013](./errors-and-warnings/NU3013.md), [NU3014](./errors-and-warnings/NU3014.md), [NU3015](./errors-and-warnings/NU3015.md), [NU3016](./errors-and-warnings/NU3016.md), [NU3017](./errors-and-warnings/NU3017.md), [NU3018](./errors-and-warnings/NU3018.md), [NU3019](./errors-and-warnings/NU3019.md), [NU3020](./errors-and-warnings/NU3020.md), [NU3021](./errors-and-warnings/NU3021.md), [NU3022](./errors-and-warnings/NU3022.md), [NU3023](./errors-and-warnings/NU3023.md), [NU3024](./errors-and-warnings/NU3024.md), [NU3025](./errors-and-warnings/NU3025.md), [NU3026](./errors-and-warnings/NU3026.md), [NU3027](./errors-and-warnings/NU3027.md), [NU3028](./errors-and-warnings/NU3028.md), [NU3029](./errors-and-warnings/NU3029.md), [NU3030](./errors-and-warnings/NU3030.md), [NU3031](./errors-and-warnings/NU3031.md), [NU3032](./errors-and-warnings/NU3032.md), [NU3033](./errors-and-warnings/NU3033.md), [NU3035](./errors-and-warnings/NU3035.md), [NU3036](./errors-and-warnings/NU3036.md), [NU3037](./errors-and-warnings/NU3037.md), [NU3038](./errors-and-warnings/NU3038.md), [NU3040](./errors-and-warnings/NU3040.md) |
4040
| Pack Warnings | [NU5100](./errors-and-warnings/NU5100.md), [NU5101](./errors-and-warnings/NU5101.md), [NU5102](./errors-and-warnings/NU5102.md), [NU5103](./errors-and-warnings/NU5103.md), [NU5104](./errors-and-warnings/NU5104.md), [NU5105](./errors-and-warnings/NU5105.md), [NU5106](./errors-and-warnings/NU5106.md), [NU5107](./errors-and-warnings/NU5107.md), [NU5108](./errors-and-warnings/NU5108.md), [NU5109](./errors-and-warnings/NU5109.md), [NU5110](./errors-and-warnings/NU5110.md), [NU5111](./errors-and-warnings/NU5111.md), [NU5112](./errors-and-warnings/NU5112.md), [NU5114](./errors-and-warnings/NU5114.md), [NU5115](./errors-and-warnings/NU5115.md), [NU5116](./errors-and-warnings/NU5116.md), [NU5117](./errors-and-warnings/NU5117.md), [NU5118](./errors-and-warnings/NU5118.md), [NU5119](./errors-and-warnings/NU5119.md), [NU5120](./errors-and-warnings/NU5120.md), [NU5121](./errors-and-warnings/NU5121.md), [NU5122](./errors-and-warnings/NU5122.md), [NU5123](./errors-and-warnings/NU5123.md), [NU5500](./errors-and-warnings/NU5500.md)
41-
| License specific Pack Warnings | [NU5124](./errors-and-warnings/NU5124.md), [NU5125](./errors-and-warnings/NU5125.md)
41+
| License specific Pack Warnings | [NU5124](./errors-and-warnings/NU5124.md), [NU5125](./errors-and-warnings/NU5125.md)
42+
| Icon specific Pack Warnings | [NU5046](./errors-and-warnings/NU5046.md), [NU5047](./errors-and-warnings/NU5047.md), [NU5048](./errors-and-warnings/NU5048.md)

‎docs/reference/errors-and-warnings/NU5046.md

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
title: NuGet Error NU5046
3+
description: NU5046 Error code
4+
author: dominoFire
5+
ms.author: feaguila
6+
ms.date: 9/4/2019
7+
ms.topic: reference
8+
ms.reviewer: karann
9+
f1_keywords:
10+
- NU5046
11+
---
12+
13+
# NuGet Error NU5046
14+
15+
<pre>The icon file 'icon.png' does not exist in the package.</pre>
16+
17+
18+
### Issue
19+
20+
NuGet is unable find the icon file in the package.
21+
22+
23+
### Solution
24+
25+
- Make sure that the file that is marked as the package icon exists at the source and it is readable, and the target matches the path expected by the `icon` property.
26+
- Ensure that the file is referenced in the nuspec or in the project file.
27+
* When creating a package from a MSBuild project file, make sure to reference the icon file in the project, as follows:
28+
29+
```xml
30+
<Project Sdk="Microsoft.NET.Sdk">
31+
<PropertyGroup>
32+
...
33+
<PackageIcon>icon.png</PackageIcon>
34+
...
35+
</PropertyGroup>
36+
37+
<ItemGroup>
38+
...
39+
<None Include="images\icon.png" Pack="true" PackagePath=""/>
40+
...
41+
</ItemGroup>
42+
</Project>
43+
```
44+
45+
* When you are creating a package from a nuspec file, make sure to include the icon file in the `<files/>` section:
46+
47+
```xml
48+
<package>
49+
<metadata>
50+
...
51+
<icon>images\icon.png</icon>
52+
...
53+
</metadata>
54+
<files>
55+
...
56+
<file src="..\icon.png" target="images\" />
57+
...
58+
</files>
59+
</package>
60+
```
61+
62+
[Learn more about packaging an icon image file](../msbuild-targets.md#packing-an-icon-image-file).

‎docs/reference/errors-and-warnings/NU5047.md

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
---
2+
title: NuGet Error NU5047
3+
description: NU5047 Error code
4+
author: dominoFire
5+
ms.author: feaguila
6+
ms.date: 9/4/2019
7+
ms.topic: reference
8+
ms.reviewer: karann
9+
f1_keywords:
10+
- NU5047
11+
---
12+
13+
# NuGet Error NU5047
14+
15+
<pre>The icon file size must not exceed 1 megabyte.</pre>
16+
17+
18+
# Issue
19+
20+
The file that is specified as the package icon is larger than 1 megabyte (MB). NuGet only allows icons whose file size is less than 1 MB.
21+
22+
23+
# Solution
24+
25+
Use an image editor program to reduce the size of the package icon file.

‎docs/reference/errors-and-warnings/NU5048.md

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
title: NuGet Error NU5048
3+
description: NU5048 Error code
4+
author: dominoFire
5+
ms.author: feaguila
6+
ms.date: 9/4/2019
7+
ms.topic: reference
8+
ms.reviewer: karann
9+
f1_keywords:
10+
- NU5048
11+
---
12+
13+
# NuGet Error NU5048
14+
15+
<pre>The 'PackageIconUrl'/'iconUrl' element is deprecated. Consider using the 'PackageIcon'/'icon' element instead. Learn more at https://aka.ms/deprecateIconUrl</pre>
16+
17+
18+
### Issue
19+
20+
Icon URL is deprecated in favor of embedding the icon inside the NuGet package. Possible causes are:
21+
22+
- When creating a package from a nuspec file, it contains a `<iconUrl/>` entry.
23+
- When creating a package from a MSBuild project file, it contains a `<PackageIconUrl>` property.
24+
25+
26+
### Solution
27+
28+
To stop seeing this warning, add an embedded icon to your package.
29+
30+
For MSBuild project files, add an `<PackageIcon/>` property, as follows:
31+
32+
```xml
33+
<Project Sdk="Microsoft.NET.Sdk">
34+
<PropertyGroup>
35+
...
36+
<PackageIcon>icon.png</PackageIcon>
37+
...
38+
</PropertyGroup>
39+
40+
<ItemGroup>
41+
...
42+
<None Include="images\icon.png" Pack="true" PackagePath=""/>
43+
...
44+
</ItemGroup>
45+
</Project>
46+
```
47+
48+
For nuspec files, add an `<icon/>` entry that points to the file that will be the package icon:
49+
50+
```xml
51+
<package>
52+
<metadata>
53+
...
54+
<icon>images\icon.png</icon>
55+
...
56+
</metadata>
57+
<files>
58+
...
59+
<file src="..\icon.png" target="images\" />
60+
...
61+
</files>
62+
</package>
63+
```
64+
65+
[Learn more about packaging an icon image file](../msbuild-targets.md#packing-an-icon-image-file).

‎docs/reference/msbuild-targets.md

Lines changed: 31 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -55,9 +55,10 @@ Note that the `Owners` and `Summary` properties from `.nuspec` are not supported
5555
| RequireLicenseAcceptance | PackageRequireLicenseAcceptance | false | |
5656
| license | PackageLicenseExpression | empty | Corresponds to `<license type="expression">` |
5757
| license | PackageLicenseFile | empty | Corresponds to `<license type="file">`. You may need to explicitly pack the referenced license file. |
58-
| LicenseUrl | PackageLicenseUrl | empty | `licenseUrl` is being deprecated, use the PackageLicenseExpression or PackageLicenseFile property |
58+
| LicenseUrl | PackageLicenseUrl | empty | `PackageLicenseUrl` is deprecated, use the PackageLicenseExpression or PackageLicenseFile property |
5959
| ProjectUrl | PackageProjectUrl | empty | |
60-
| IconUrl | PackageIconUrl | empty | |
60+
| Icon | PackageIcon | empty | You may need to explicitly pack the referenced icon image file.|
61+
| IconUrl | PackageIconUrl | empty | `PackageIconUrl` is deprecated, use the PackageIcon property |
6162
| Tags | PackageTags | empty | Tags are semi-colon delimited. |
6263
| ReleaseNotes | PackageReleaseNotes | empty | |
6364
| Repository/Url | RepositoryUrl | empty | Repository URL used to clone or retrieve source code. Example: *https://github.com/NuGet/NuGet.Client.git* |
@@ -112,8 +113,35 @@ To suppress package dependencies from generated NuGet package, set `SuppressDepe
112113

113114
### PackageIconUrl
114115

116+
> [!Important]
117+
> PackageIconUrl is deprecated. Use [PackageIcon](#packing-an-icon-image-file) instead.
118+
115119
As part of the change for [NuGet Issue 352](https://github.com/NuGet/Home/issues/352), `PackageIconUrl` will eventually be changed to `PackageIconUri` and can be relative path to a icon file which will included at the root of the resulting package.
116120

121+
### Packing an icon image file
122+
123+
When packing an icon image file, you need to use PackageIcon property to specify the package path, relative to the root of the package. In addition, you need to make sure that the file is included in the package. Image file size is limited to 1 MB. Supported file formats include JPEG and PNG. We recommend an image resolution of 64x64.
124+
125+
For example:
126+
127+
```xml
128+
<PropertyGroup>
129+
...
130+
<PackageIcon>icon.png</PackageIcon>
131+
...
132+
</PropertyGroup>
133+
134+
<ItemGroup>
135+
...
136+
<None Include="images\icon.png" Pack="true" PackagePath=""/>
137+
...
138+
</ItemGroup>
139+
```
140+
141+
[Package Icon sample](https://github.com/NuGet/Samples/tree/master/PackageIconExample).
142+
143+
For the nuspec equivalent, take a look at [nuspec reference for icon](nuspec.md#icon).
144+
117145
### Output assemblies
118146

119147
`nuget pack` copies output files with extensions `.exe`, `.dll`, `.xml`, `.winmd`, `.json`, and `.pri`. The output files that are copied depend on what MSBuild provides from the `BuiltOutputProjectGroup` target.
@@ -216,6 +244,7 @@ When packing a license file, you need to use PackageLicenseFile property to spec
216244
<None Include="licenses\LICENSE.txt" Pack="true" PackagePath=""/>
217245
</ItemGroup>
218246
```
247+
219248
[License file sample](https://github.com/NuGet/Samples/tree/master/PackageLicenseFileExample).
220249

221250
### IsTool

‎docs/reference/nuspec.md

Lines changed: 30 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,7 @@ A URL for the package's home page, often shown in UI displays as well as nuget.o
8585

8686
#### licenseUrl
8787
> [!Important]
88-
> licenseUrl is being deprecated. Use license instead.
88+
> licenseUrl is deprecated. Use license instead.
8989
9090
A URL for the package's license, often shown in UIs like nuget.org.
9191

@@ -139,7 +139,36 @@ license-expression = 1*1(simple-expression / compound-expression / UNLICENSED)
139139
```
140140

141141
#### iconUrl
142+
143+
> [!Important]
144+
> iconUrl is deprecated. Use icon instead.
145+
142146
A URL for a 64x64 image with transparency background to use as the icon for the package in UI display. Be sure this element contains the *direct image URL* and not the URL of a web page containing the image. For example, to use an image from GitHub, use the raw file URL like <em>https://github.com/\<username\>/\<repository\>/raw/\<branch\>/\<logo.png\></em>.
147+
148+
#### icon
149+
150+
It is a path to an image file within the package, often shown in UIs like nuget.org as the package icon. Image file size is limited to 1 MB. Supported file formats include JPEG and PNG. We recommend an image resoulution of 64x64.
151+
152+
For example, you would add the following to your nuspec when creating a package using nuget.exe:
153+
154+
```xml
155+
<package>
156+
<metadata>
157+
...
158+
<icon>images\icon.png</icon>
159+
...
160+
</metadata>
161+
<files>
162+
...
163+
<file src="..\icon.png" target="images\" />
164+
...
165+
</files>
166+
</package>
167+
```
168+
169+
[Package Icon nuspec sample.](https://github.com/NuGet/Samples/tree/master/PackageIconNuspecExample)
170+
171+
For the MSBuild equivalent, take a look at [Packing an icon image file](msbuild-targets.md#packing-an-icon-image-file).
143172

144173
#### requireLicenseAcceptance
145174
A Boolean value specifying whether the client must prompt the consumer to accept the package license before installing the package.

0 commit comments

Comments
 (0)