diff --git a/scripts/utils/docsPRGen.ps1 b/scripts/utils/docsPRGen.ps1 new file mode 100644 index 00000000000..508650e1241 --- /dev/null +++ b/scripts/utils/docsPRGen.ps1 @@ -0,0 +1,33 @@ +# This takes docs.md and helps create/update files for the dotnet docs repo. +# https://github.com/dotnet/docs/blob/master/CONTRIBUTING.md#process-for-contributing + +param ( + [Parameter(Mandatory=$true)][string]$DotnetDocsRootDir + ) + +$mdFile = "src\NuGet.Core\NuGet.CommandLine.XPlat\external\docs.md" +$outFile = ""; +$todayShortDate = Get-Date -Format "MM/dd/yyyy" + +foreach($line in [System.IO.File]::ReadLines($mdFile)) +{ + if ($line.StartsWith("---file:")) + { + $relativeDestFilePath = $line.SubString(8) + $outFile = "$DotnetDocsRootDir\$relativeDestFilePath" + Remove-Item "$outFile" + New-Item "$outFile" -ItemType file + } + elseif ($line.StartsWith("ms.date:")) + { + Add-Content "$outFile" "ms.date: $todayShortDate" -Encoding ASCII + } + elseif ($line.StartsWith("***")) + { + #skip each line of the instructions at top of docs.md file + } + else + { + Add-Content "$outFile" $line -Encoding ASCII + } +} diff --git a/scripts/utils/ttGen.ps1 b/scripts/utils/ttGen.ps1 new file mode 100644 index 00000000000..654a1c33507 --- /dev/null +++ b/scripts/utils/ttGen.ps1 @@ -0,0 +1,12 @@ +Write-Host "Regenerating all generated files from all .tt files." +Write-Host "(requires t4.exe from 'dotnet tool install --global dotnet-t4' or right click .tt files in VS and 'run custom tool')" +Write-Host "" +$ttFiles = Get-ChildItem -Filter *.tt -Recurse -File -Name +foreach ($ttFile in $ttFiles) +{ + if (-not $ttFile.endswith("AssemblySourceFileGenerator.tt")) + { + Write-Host t4.exe $ttFile + t4.exe "$ttFile" + } +} diff --git a/src/NuGet.Clients/NuGet.CommandLine/NuGetCommand.resx b/src/NuGet.Clients/NuGet.CommandLine/NuGetCommand.resx index 05ca0b0cb0c..fbb5d725fe6 100644 --- a/src/NuGet.Clients/NuGet.CommandLine/NuGetCommand.resx +++ b/src/NuGet.Clients/NuGet.CommandLine/NuGetCommand.resx @@ -389,7 +389,7 @@ nuget setapikey 4003d786-cc37-4004-bfdf-c4f3e8ef9b3a -Source http://example.com/ Only localize "[name]" and "[source]" - UserName to be used when connecting to an authenticated source. + Username to be used when connecting to an authenticated source. Assembly to use for metadata. diff --git a/src/NuGet.Core/NuGet.CommandLine.XPlat/Commands/CommandParsers.tt b/src/NuGet.Core/NuGet.CommandLine.XPlat/Commands/CommandParsers.tt index f9e38805d86..650aef5289c 100644 --- a/src/NuGet.Core/NuGet.CommandLine.XPlat/Commands/CommandParsers.tt +++ b/src/NuGet.Core/NuGet.CommandLine.XPlat/Commands/CommandParsers.tt @@ -18,6 +18,11 @@ return type == "Argument"; } + bool IsOption(string type) + { + return type == "Option"; + } + string GetProperty(XElement element) { switch (element.Name.LocalName) @@ -26,8 +31,14 @@ return "Option"; case "SwitchOption": return "Option"; + case "Value": + return "Option"; case "Argument": return "Argument"; + case "Example": + return "Example"; + case "SeeAlso": + return "SeeAlso"; default: return "Unknown Element Type " + element.Name.LocalName; } diff --git a/src/NuGet.Core/NuGet.CommandLine.XPlat/Commands/Commands.xml b/src/NuGet.Core/NuGet.CommandLine.XPlat/Commands/Commands.xml index 319f5211700..f4930e5f7c0 100644 --- a/src/NuGet.Core/NuGet.CommandLine.XPlat/Commands/Commands.xml +++ b/src/NuGet.Core/NuGet.CommandLine.XPlat/Commands/Commands.xml @@ -3,49 +3,76 @@ Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. --> - + - + + + + + + + - + + + + - + + + + - + + + + - + + + + - + - + + + + diff --git a/src/NuGet.Core/NuGet.CommandLine.XPlat/Commands/Verbs.cs b/src/NuGet.Core/NuGet.CommandLine.XPlat/Commands/Verbs.cs index 06e14eb7423..fb21db9d24d 100644 --- a/src/NuGet.Core/NuGet.CommandLine.XPlat/Commands/Verbs.cs +++ b/src/NuGet.Core/NuGet.CommandLine.XPlat/Commands/Verbs.cs @@ -29,7 +29,7 @@ internal static void Register(CommandLineApplication app, CommandOptionType.SingleValue); CommandOption username = SourceCmd.Option( "-u|--username", - Strings.SourcesCommandUserNameDescription, + Strings.SourcesCommandUsernameDescription, CommandOptionType.SingleValue); CommandOption password = SourceCmd.Option( "-p|--password", @@ -256,7 +256,7 @@ internal static void Register(CommandLineApplication app, CommandOptionType.SingleValue); CommandOption username = SourceCmd.Option( "-u|--username", - Strings.SourcesCommandUserNameDescription, + Strings.SourcesCommandUsernameDescription, CommandOptionType.SingleValue); CommandOption password = SourceCmd.Option( "-p|--password", diff --git a/src/NuGet.Core/NuGet.CommandLine.XPlat/Commands/Verbs.tt b/src/NuGet.Core/NuGet.CommandLine.XPlat/Commands/Verbs.tt index 2a10d366ae3..009b33757d9 100644 --- a/src/NuGet.Core/NuGet.CommandLine.XPlat/Commands/Verbs.tt +++ b/src/NuGet.Core/NuGet.CommandLine.XPlat/Commands/Verbs.tt @@ -9,15 +9,30 @@ <# string InitCaps(string input) { + if (input == null) + { + return null; + } + string output = input.Substring(0, 1).ToUpper() + input.Substring(1); return output; } + bool IsArgumentOrOption(string type) + { + return IsArgument(type) || IsOption(type); + } + bool IsArgument(string type) { return type == "Argument"; } + bool IsOption(string type) + { + return type == "Option"; + } + string GetProperty(XElement element) { switch (element.Name.LocalName) @@ -26,8 +41,14 @@ return "Option"; case "SwitchOption": return "Option"; + case "Value": + return "Option"; case "Argument": return "Argument"; + case "Example": + return "Example"; + case "SeeAlso": + return "SeeAlso"; default: return "Unknown Element Type " + element.Name.LocalName; } @@ -93,28 +114,29 @@ foreach (XElement verb in commands.Descendants(XName.Get("Verb",""))) } foreach (XElement option in noun.Descendants()) { - string optionName = option.Attribute(XName.Get("Name", "")).Value; - string optionLongName = option.Attribute(XName.Get("LongName", ""))?.Value; - string optionHelp = option.Attribute(XName.Get("Help", ""))?.Value; - string optionFormalName = optionName.Replace("-",""); - - if (IsArgument(GetProperty(option))) + if (IsArgumentOrOption(GetProperty(option))) { - + string optionName = option.Attribute(XName.Get("Name", ""))?.Value; + string optionLongName = option.Attribute(XName.Get("LongName", ""))?.Value; + string optionHelp = option.Attribute(XName.Get("Help", ""))?.Value; + string optionFormalName = optionName.Replace("-",""); + if (IsArgument(GetProperty(option))) + { #> CommandArgument <#= optionFormalName #> = <#= nounFormalName #>Cmd.Argument( "<#= optionLongName != null ? optionLongName : optionName #>", <#= optionHelp != null ? "Strings."+optionHelp : "" #>); <# - } - else - { - string optionShortcut = option.Attribute(XName.Get("Shortcut",""))?.Value; + } + else if (IsOption(GetProperty(option))) + { + string optionShortcut = option.Attribute(XName.Get("Shortcut",""))?.Value; #> CommandOption <#= optionFormalName #> = <#= nounFormalName #>Cmd.Option( "<#= (optionShortcut != null ? "-" + optionShortcut + "|" : "") + "--" + optionName.ToLower() #>", <#= optionHelp != null ? "Strings."+optionHelp : "" #>, CommandOptionType.<#= GetOptionType(option) #>); <# + } } } #> @@ -127,30 +149,34 @@ foreach (XElement verb in commands.Descendants(XName.Get("Verb",""))) <# foreach (XElement option in noun.Descendants()) { - string optionName = option.Attribute(XName.Get("Name", "")).Value; - string optionFormalName = optionName.Replace("-",""); - string optionCapsName = InitCaps(optionFormalName); - if (IsArgument(GetProperty(option))) + if (IsArgumentOrOption(GetProperty(option))) { + string optionName = option.Attribute(XName.Get("Name", ""))?.Value; + string optionFormalName = optionName?.Replace("-",""); + string optionCapsName = InitCaps(optionFormalName); + + if (IsArgument(GetProperty(option))) + { #> <#= optionCapsName #> = <#=optionFormalName#>.Value, <# - } - else - { - string optionType = GetOptionType(option); - switch (optionType) + } + else if (IsOption(GetProperty(option))) { - case "SingleValue": + string optionType = GetOptionType(option); + switch (optionType) + { + case "SingleValue": #> <#= optionCapsName #> = <#= optionFormalName #>.Value(), <# - break; - case "NoValue": + break; + case "NoValue": #> <#= optionCapsName #> = <#= optionFormalName #>.HasValue(), <# - break; + break; + } } } } @@ -164,39 +190,41 @@ foreach (XElement verb in commands.Descendants(XName.Get("Verb",""))) bool required = option2.Attribute(XName.Get("Required", ""))?.Value == "true"; if (required) { - string optionName2 = option2.Attribute(XName.Get("Name", "")).Value; - string optionFormalName2 = optionName2.Replace("-",""); - string optionCapsName2 = InitCaps(optionFormalName2); - - if (IsArgument(GetProperty(option2))) + if (IsArgumentOrOption(GetProperty(option2))) { + string optionName2 = option2.Attribute(XName.Get("Name", ""))?.Value; + string optionFormalName2 = optionName2?.Replace("-",""); + string optionCapsName2 = InitCaps(optionFormalName2); + if (IsArgument(GetProperty(option2))) + { #> if (args.<#= optionCapsName2 #> == null) { throw new CommandException("'<#=optionFormalName2#>' argument is missing but required."); } <# - } - else - { - string optionType2 = GetOptionType(option2); - switch (optionType2) + } + else if (IsOption(GetProperty(option2))) { - case "SingleValue": + string optionType2 = GetOptionType(option2); + switch (optionType2) + { + case "SingleValue": #> if (args.<#= optionCapsName2 #> == null) { throw new CommandException("'<#=optionFormalName2#>' option is missing but required."); } <# - break; - case "NoValue": + break; + case "NoValue": #> //TODO: implement required for bool <# - break; + break; + } } - } + } } } #> <#= commandFormalName #><#= nounFormalName #>Runner.Run(args, getLogger); diff --git a/src/NuGet.Core/NuGet.CommandLine.XPlat/NuGet.CommandLine.XPlat.csproj b/src/NuGet.Core/NuGet.CommandLine.XPlat/NuGet.CommandLine.XPlat.csproj index 990001360ed..e524f26ab0d 100644 --- a/src/NuGet.Core/NuGet.CommandLine.XPlat/NuGet.CommandLine.XPlat.csproj +++ b/src/NuGet.Core/NuGet.CommandLine.XPlat/NuGet.CommandLine.XPlat.csproj @@ -39,6 +39,7 @@ + True True diff --git a/src/NuGet.Core/NuGet.CommandLine.XPlat/Strings.Designer.cs b/src/NuGet.Core/NuGet.CommandLine.XPlat/Strings.Designer.cs index a15d5d1dfc6..5c9448dcc2e 100644 --- a/src/NuGet.Core/NuGet.CommandLine.XPlat/Strings.Designer.cs +++ b/src/NuGet.Core/NuGet.CommandLine.XPlat/Strings.Designer.cs @@ -1112,6 +1112,15 @@ internal static string Option_ConfigFile { } } + /// + /// Looks up a localized string similar to The NuGet configuration file. If specified, only the settings from this file will be used. If not specified, the hierarchy of configuration files from the current directory will be used. To learn more about NuGet configuration go to https://docs.microsoft.com/en-us/nuget/consume-packages/configuring-nuget-behavior.. + /// + internal static string Option_ConfigFile_Docs { + get { + return ResourceManager.GetString("Option_ConfigFile_Docs", resourceCulture); + } + } + /// /// Looks up a localized string similar to Specifies the directory for the created NuGet package file. If not specified, uses the current directory. /// @@ -1455,11 +1464,11 @@ internal static string SourcesCommandUsageSummary { } /// - /// Looks up a localized string similar to UserName to be used when connecting to an authenticated source.. + /// Looks up a localized string similar to Username to be used when connecting to an authenticated source.. /// - internal static string SourcesCommandUserNameDescription { + internal static string SourcesCommandUsernameDescription { get { - return ResourceManager.GetString("SourcesCommandUserNameDescription", resourceCulture); + return ResourceManager.GetString("SourcesCommandUsernameDescription", resourceCulture); } } diff --git a/src/NuGet.Core/NuGet.CommandLine.XPlat/Strings.resx b/src/NuGet.Core/NuGet.CommandLine.XPlat/Strings.resx index 4e0228f171f..d845e56f0b4 100644 --- a/src/NuGet.Core/NuGet.CommandLine.XPlat/Strings.resx +++ b/src/NuGet.Core/NuGet.CommandLine.XPlat/Strings.resx @@ -622,27 +622,34 @@ For more information, visit https://docs.nuget.org/docs/reference/command-line-r Password to be used when connecting to an authenticated source. - Path to the package(s) source. + Path to the package source. - Applies to the list action. Accepts two values: Detailed (the default) and Short. + The format of the list command output: `Detailed` (the default) and `Short`. <List|Add|Remove|Enable|Disable|Update> -Name [name] -Source [source] Only localize "[name]" and "[source]" - - UserName to be used when connecting to an authenticated source. + + Username to be used when connecting to an authenticated source. Enables storing portable package source credentials by disabling password encryption. - Comma-separated list of valid authentication types for this source. By default, all authentication types are valid. Example: basic,negotiate - Please don't localize "basic,negotiate" + Comma-separated list of valid authentication types for this source. Set this to basic if the server advertises NTLM or Negotiate and your credentials must be sent using the Basic mechanism, for instance when using a PAT with on-premises Azure DevOps Server. Other valid values include negotiate, kerberos, ntlm, and digest, but these values are unlikely to be useful. + Please don't localize "basic, NTLM, Negotiate, kerberos, ntlm, digest" + + + Comma-separated list of valid authentication types for this source. Set this to `basic` if the server advertises NTLM or Negotiate and your credentials must be sent using the Basic mechanism, for instance when using a PAT with on-premises Azure DevOps Server. Other valid values include `negotiate`, `kerberos`, `ntlm`, and `digest`, but these values are unlikely to be useful. + Please don't localize "basic, NTLM, Negotiate, kerberos, ntlm, digest" - The NuGet configuration file. If specified, only the settings from this file will be used. If not specified, the hierarchy of configuration files from the current directory will be used. To learn more about NuGet configuration go to https://docs.microsoft.com/en-us/nuget/consume-packages/configuring-nuget-behavior. + The NuGet configuration file. If specified, only the settings from this file will be used. If not specified, the hierarchy of configuration files from the current directory will be used. For more information, see https://docs.microsoft.com/nuget/consume-packages/configuring-nuget-behavior. + + + The NuGet configuration file. If specified, only the settings from this file will be used. If not specified, the hierarchy of configuration files from the current directory will be used. For more information, see [Common NuGet Configurations](https://docs.microsoft.com/nuget/consume-packages/configuring-nuget-behavior). Add a NuGet source. diff --git a/src/NuGet.Core/NuGet.CommandLine.XPlat/external/docs.md b/src/NuGet.Core/NuGet.CommandLine.XPlat/external/docs.md new file mode 100644 index 00000000000..3a388abd94b --- /dev/null +++ b/src/NuGet.Core/NuGet.CommandLine.XPlat/external/docs.md @@ -0,0 +1,365 @@ + +***Run scripts\utils\ttGen.ps1 after changes to update docs.md +***Then run scripts\utils\docsPRGen.ps1 to split into several files in dotnet docs fork. +*** +***[Dotnet docs repo contrib guidelines](https://github.com/dotnet/docs/blob/master/CONTRIBUTING.md#process-for-contributing) +---file:docs\core\tools\dotnet-nuget-add-source.md +--- +title: dotnet nuget add source command +description: The dotnet nuget add source command adds a new package source to your NuGet configuration files. +ms.date: REPLACE_WITH_CURRENT_DATE_IN_PR_CREATION_TOOL +--- +# dotnet nuget add source + +**This article applies to:** ✔️ .NET Core 3.1.200 SDK and later versions + +## Name + +`dotnet nuget add source` - Add a NuGet source. + +## Synopsis + +```dotnetcli +dotnet nuget add source [--name] [--username] + [--password] [--store-password-in-clear-text] [--valid-authentication-types] + [--configfile] +dotnet nuget add source [-h|--help] +``` + +## Description + +The `dotnet nuget add source` command adds a new package source to your NuGet configuration files. + +## Arguments + +- **`PACKAGE_SOURCE_PATH`** + + Path to the package source. + +## Options + +- **`--configfile`** + + The NuGet configuration file. If specified, only the settings from this file will be used. If not specified, the hierarchy of configuration files from the current directory will be used. For more information, see [Common NuGet Configurations](https://docs.microsoft.com/nuget/consume-packages/configuring-nuget-behavior). + +- **`-n|--name`** + + Name of the source. + +- **`-p|--password`** + + Password to be used when connecting to an authenticated source. + +- **`--store-password-in-clear-text`** + + Enables storing portable package source credentials by disabling password encryption. + +- **`-u|--username`** + + Username to be used when connecting to an authenticated source. + +- **`--valid-authentication-types`** + + Comma-separated list of valid authentication types for this source. Set this to `basic` if the server advertises NTLM or Negotiate and your credentials must be sent using the Basic mechanism, for instance when using a PAT with on-premises Azure DevOps Server. Other valid values include `negotiate`, `kerberos`, `ntlm`, and `digest`, but these values are unlikely to be useful. + +## Examples + +- Add `nuget.org` as a source: + + ```dotnetcli + dotnet nuget add source https://api.nuget.org/v3/index.json -n nuget.org + ``` + +- Add `c:\packages` as a local source: + + ```dotnetcli + dotnet nuget add source c:\packages + ``` + +- Add a source that needs authentication: + + ```dotnetcli + dotnet nuget add source https://contoso.com/litware -n myTeam -u myUsername -p myPassword --store-password-in-clear-text + ``` + +- Add a source that needs authentication (then go install credential provider): + + ```dotnetcli + dotnet nuget add source https://pkgs.dev.azure.com/contoso/litware/_packaging/litware-deps/nuget/v3/index.json -n myTeam + ``` + +## See also + +- [Package source sections in NuGet.config files](/nuget/reference/nuget-config-file#package-source-sections) + +- [sources command (nuget.exe)](/nuget/reference/cli-reference/cli-ref-sources) +---file:docs\core\tools\dotnet-nuget-disable-source.md +--- +title: dotnet nuget disable source command +description: The dotnet nuget disable source command disables an existing source in your NuGet configuration files. +ms.date: REPLACE_WITH_CURRENT_DATE_IN_PR_CREATION_TOOL +--- +# dotnet nuget disable source + +**This article applies to:** ✔️ .NET Core 3.1.200 SDK and later versions + +## Name + +`dotnet nuget disable source` - Disable a NuGet source. + +## Synopsis + +```dotnetcli +dotnet nuget disable source [--configfile] +dotnet nuget disable source [-h|--help] +``` + +## Description + +The `dotnet nuget disable source` command disables an existing source in your NuGet configuration files. + +## Arguments + +- **`NAME`** + + Name of the source. + +## Options + +- **`--configfile`** + + The NuGet configuration file. If specified, only the settings from this file will be used. If not specified, the hierarchy of configuration files from the current directory will be used. For more information, see [Common NuGet Configurations](https://docs.microsoft.com/nuget/consume-packages/configuring-nuget-behavior). + +## Examples + +- Disable a source with name of `mySource`: + + ```dotnetcli + dotnet nuget disable source mySource + ``` + +## See also + +- [Package source sections in NuGet.config files](/nuget/reference/nuget-config-file#package-source-sections) + +- [sources command (nuget.exe)](/nuget/reference/cli-reference/cli-ref-sources) +---file:docs\core\tools\dotnet-nuget-enable-source.md +--- +title: dotnet nuget enable source command +description: The dotnet nuget enable source command enables an existing source in your NuGet configuration files. +ms.date: REPLACE_WITH_CURRENT_DATE_IN_PR_CREATION_TOOL +--- +# dotnet nuget enable source + +**This article applies to:** ✔️ .NET Core 3.1.200 SDK and later versions + +## Name + +`dotnet nuget enable source` - Enable a NuGet source. + +## Synopsis + +```dotnetcli +dotnet nuget enable source [--configfile] +dotnet nuget enable source [-h|--help] +``` + +## Description + +The `dotnet nuget enable source` command enables an existing source in your NuGet configuration files. + +## Arguments + +- **`NAME`** + + Name of the source. + +## Options + +- **`--configfile`** + + The NuGet configuration file. If specified, only the settings from this file will be used. If not specified, the hierarchy of configuration files from the current directory will be used. For more information, see [Common NuGet Configurations](https://docs.microsoft.com/nuget/consume-packages/configuring-nuget-behavior). + +## Examples + +- Enable a source with name of `mySource`: + + ```dotnetcli + dotnet nuget enable source mySource + ``` + +## See also + +- [Package source sections in NuGet.config files](/nuget/reference/nuget-config-file#package-source-sections) + +- [sources command (nuget.exe)](/nuget/reference/cli-reference/cli-ref-sources) +---file:docs\core\tools\dotnet-nuget-list-source.md +--- +title: dotnet nuget list source command +description: The dotnet nuget list source command lists all existing sources from your NuGet configuration files. +ms.date: REPLACE_WITH_CURRENT_DATE_IN_PR_CREATION_TOOL +--- +# dotnet nuget list source + +**This article applies to:** ✔️ .NET Core 3.1.200 SDK and later versions + +## Name + +`dotnet nuget list source` - Lists all configured NuGet sources. + +## Synopsis + +```dotnetcli +dotnet nuget list source [--format] [--configfile] +dotnet nuget list source [-h|--help] +``` + +## Description + +The `dotnet nuget list source` command lists all existing sources from your NuGet configuration files. + +## Options + +- **`--configfile`** + + The NuGet configuration file. If specified, only the settings from this file will be used. If not specified, the hierarchy of configuration files from the current directory will be used. For more information, see [Common NuGet Configurations](https://docs.microsoft.com/nuget/consume-packages/configuring-nuget-behavior). + +- **`--format`** + + The format of the list command output: `Detailed` (the default) and `Short`. + +## Examples + +- List configured sources from the current directory: + + ```dotnetcli + dotnet nuget list source + ``` + +## See also + +- [Package source sections in NuGet.config files](/nuget/reference/nuget-config-file#package-source-sections) + +- [sources command (nuget.exe)](/nuget/reference/cli-reference/cli-ref-sources) +---file:docs\core\tools\dotnet-nuget-remove-source.md +--- +title: dotnet nuget remove source command +description: The dotnet nuget remove source command removes an existing source from your NuGet configuration files. +ms.date: REPLACE_WITH_CURRENT_DATE_IN_PR_CREATION_TOOL +--- +# dotnet nuget remove source + +**This article applies to:** ✔️ .NET Core 3.1.200 SDK and later versions + +## Name + +`dotnet nuget remove source` - Remove a NuGet source. + +## Synopsis + +```dotnetcli +dotnet nuget remove source [--configfile] +dotnet nuget remove source [-h|--help] +``` + +## Description + +The `dotnet nuget remove source` command removes an existing source from your NuGet configuration files. + +## Arguments + +- **`NAME`** + + Name of the source. + +## Options + +- **`--configfile`** + + The NuGet configuration file. If specified, only the settings from this file will be used. If not specified, the hierarchy of configuration files from the current directory will be used. For more information, see [Common NuGet Configurations](https://docs.microsoft.com/nuget/consume-packages/configuring-nuget-behavior). + +## Examples + +- Remove a source with name of `mySource`: + + ```dotnetcli + dotnet nuget remove source mySource + ``` + +## See also + +- [Package source sections in NuGet.config files](/nuget/reference/nuget-config-file#package-source-sections) + +- [sources command (nuget.exe)](/nuget/reference/cli-reference/cli-ref-sources) +---file:docs\core\tools\dotnet-nuget-update-source.md +--- +title: dotnet nuget update source command +description: The dotnet nuget update source command updates an existing source in your NuGet configuration files. +ms.date: REPLACE_WITH_CURRENT_DATE_IN_PR_CREATION_TOOL +--- +# dotnet nuget update source + +**This article applies to:** ✔️ .NET Core 3.1.200 SDK and later versions + +## Name + +`dotnet nuget update source` - Update a NuGet source. + +## Synopsis + +```dotnetcli +dotnet nuget update source [--source] [--username] + [--password] [--store-password-in-clear-text] [--valid-authentication-types] + [--configfile] +dotnet nuget update source [-h|--help] +``` + +## Description + +The `dotnet nuget update source` command updates an existing source in your NuGet configuration files. + +## Arguments + +- **`NAME`** + + Name of the source. + +## Options + +- **`--configfile`** + + The NuGet configuration file. If specified, only the settings from this file will be used. If not specified, the hierarchy of configuration files from the current directory will be used. For more information, see [Common NuGet Configurations](https://docs.microsoft.com/nuget/consume-packages/configuring-nuget-behavior). + +- **`-p|--password`** + + Password to be used when connecting to an authenticated source. + +- **`-s|--source`** + + Path to the package source. + +- **`--store-password-in-clear-text`** + + Enables storing portable package source credentials by disabling password encryption. + +- **`-u|--username`** + + Username to be used when connecting to an authenticated source. + +- **`--valid-authentication-types`** + + Comma-separated list of valid authentication types for this source. Set this to `basic` if the server advertises NTLM or Negotiate and your credentials must be sent using the Basic mechanism, for instance when using a PAT with on-premises Azure DevOps Server. Other valid values include `negotiate`, `kerberos`, `ntlm`, and `digest`, but these values are unlikely to be useful. + +## Examples + +- Update a source with name of `mySource`: + + ```dotnetcli + dotnet nuget update source mySource --source c:\packages + ``` + +## See also + +- [Package source sections in NuGet.config files](/nuget/reference/nuget-config-file#package-source-sections) + +- [sources command (nuget.exe)](/nuget/reference/cli-reference/cli-ref-sources) diff --git a/src/NuGet.Core/NuGet.CommandLine.XPlat/external/docs.tt b/src/NuGet.Core/NuGet.CommandLine.XPlat/external/docs.tt new file mode 100644 index 00000000000..1c8b89768df --- /dev/null +++ b/src/NuGet.Core/NuGet.CommandLine.XPlat/external/docs.tt @@ -0,0 +1,383 @@ +<#@ template debug="false" hostspecific="true" language="C#" #> +<#@ assembly name="System.Xml.XDocument" #> +<#@ assembly name="System.Xml.Linq" #> +<#@ assembly name="System.Xml" #> +<#@ assembly name="System.Core" #> +<#@ assembly name="System.Collections" #> +<#@ import namespace="System.Collections.Generic" #> +<#@ import namespace="System.Linq" #> +<#@ import namespace="System.Text" #> +<#@ import namespace="System.Xml.Linq" #> +<#@ import namespace="System.Xml.XPath" #> +<#@ output extension=".md" #> +<#@ include file="src\NuGet.Core\NuGet.CommandLine.XPlat\external\docsHelpers.t4" #> +<# + string MakeFormal(string optionName, string shortcut) + { + string formalString = null; + if (shortcut != null) + { + formalString = "-" + shortcut + "|"; + } + return formalString + "--" + optionName; + } + + bool IsArgument(string type) + { + return type == "Argument"; + } + + bool IsOption(string type) + { + return type == "Option"; + } + + bool IsExample(string type) + { + return type == "Example"; + } + + bool IsSeeAlso(string type) + { + return type == "SeeAlso"; + } + + string GetProperty(XElement element) + { + switch (element.Name.LocalName) + { + case "SingleValueOption": + return "Option"; + case "SwitchOption": + return "Option"; + case "Value": + return "Option"; + case "Argument": + return "Argument"; + case "Example": + return "Example"; + case "SeeAlso": + return "SeeAlso"; + default: + return "Unknown Element Type " + element.Name.LocalName; + } + } + + string GetOptionType(XElement element) + { + switch (element.Name.LocalName) + { + case "SingleValueOption": + return "SingleValue"; + case "SwitchOption": + return "NoValue"; + case "Value": + return "Value"; + default: + return "Unknown Element Type " + element.Name.LocalName; + } + } + + string GetArgumentName(string argName, string longArgName) + { + if (argName == null) return null; + Char[] charsToProcess = string.IsNullOrEmpty(longArgName) ? argName.ToCharArray() : longArgName.ToCharArray(); + StringBuilder resultNameBuilder = new StringBuilder(); + + for (int i = 0; i < charsToProcess.Length; i++) + { + char upperChar = char.ToUpper(charsToProcess[i]); + if (charsToProcess[i] == upperChar && resultNameBuilder.Length != 0) + { + resultNameBuilder.Append("_" + upperChar.ToString()); + } + else + { + resultNameBuilder.Append(upperChar); + } + } + + return resultNameBuilder.ToString(); + } + + string GetHelpTextWithOverride(Dictionary stringDictionary, string helpText) + { + if (stringDictionary.ContainsKey(helpText.ToLower() + "_docs")) + { + return stringDictionary[helpText.ToLower() + "_docs"]; + } + else + { + return stringDictionary[helpText.ToLower()]; + } + } + + string commandFile = this.Host.ResolvePath(@"..\..\NuGet.CommandLine.XPlat\Commands\Commands.xml"); + XDocument commands = XDocument.Load(commandFile); + + // harvest all strings in strings.resx to string dictionary, so we can use it later in codegen. + string stringsResXPath = this.Host.ResolvePath(@"..\..\NuGet.CommandLine.XPlat\Strings.resx"); + XElement resxRoot = XDocument.Load(stringsResXPath).Root; + var stringDictionary = new Dictionary(); + foreach (XElement data in resxRoot.Descendants()) + { + if (data.Name.LocalName == "data") + { + string resName = data.Attribute(XName.Get("name", ""))?.Value; + string value = data.XPathSelectElement("value")?.Value; + if (resName != null && value != null) + { + stringDictionary.Add(resName.ToLower(), value); + } + } + } +#> +***Run scripts\utils\ttGen.ps1 after changes to update docs.md +***Then run scripts\utils\docsPRGen.ps1 to split into several files in dotnet docs fork. +*** +***[Dotnet docs repo contrib guidelines](https://github.com/dotnet/docs/blob/master/CONTRIBUTING.md#process-for-contributing) +<# + // Generate command docs + foreach (XElement verb in commands.Descendants(XName.Get("Verb",""))) + { + string verbName = verb.Attribute(XName.Get("Name", "")).Value; + string verbFormalName = verbName; + foreach (XElement noun in verb.Descendants(XName.Get("Noun"))) + { + string description = noun.Attribute(XName.Get("Description", ""))?.Value; + string nounName = noun.Attribute(XName.Get("Name", ""))?.Value; + string nounFormalName = nounName; + string version = noun.Attribute(XName.Get("Version", ""))?.Value; + + // calculate commandSyntax + var commandSyntaxBuilder = new StringBuilder(); + commandSyntaxBuilder.AppendFormat("dotnet nuget {0} {1}", verbFormalName, nounFormalName); + int lastLineBreak = 0; + + foreach (XElement option in noun.Descendants()) + { + string optionName = option.Attribute(XName.Get("Name", ""))?.Value; + string shortcut = option.Attribute(XName.Get("Shortcut", ""))?.Value; + string optionType = option.Attribute(XName.Get("Type", ""))?.Value; + string optionLongName = option.Attribute(XName.Get("LongName", ""))?.Value; + string helpText = option.Attribute(XName.Get("Help", ""))?.Value; + string optionFormalName = MakeFormal(optionName, shortcut); + bool required =false; + + if (commandSyntaxBuilder.Length - lastLineBreak > 55) + { + // linewrap so line isn't too long. + commandSyntaxBuilder.AppendLine(); + lastLineBreak = commandSyntaxBuilder.Length; + commandSyntaxBuilder.Append(" "); + } + + if (IsArgument(GetProperty(option))) + { + string argumentName = GetArgumentName(optionName, optionLongName); + commandSyntaxBuilder.Append(" <" + argumentName + ">"); + } + else if (IsOption(GetProperty(option))) + { + commandSyntaxBuilder.Append(!required ? " [" : " "); + commandSyntaxBuilder.Append(optionLongName != null ? "--" + optionLongName.ToLower() : "--" + optionName.ToLower()); + commandSyntaxBuilder.Append(!required ? "]" : ""); + } + } + + string commandSyntax = commandSyntaxBuilder.ToString(); +#> +---file:docs\core\tools\dotnet-nuget-<#= verbFormalName #>-<#= nounFormalName #>.md +--- +title: dotnet nuget <#= verbFormalName #> <#= nounFormalName #> command +description: The dotnet nuget <#= verbFormalName #> <#= nounFormalName #> command <#= description #> +ms.date: REPLACE_WITH_CURRENT_DATE_IN_PR_CREATION_TOOL +--- +# dotnet nuget <#= verbFormalName #> <#= nounFormalName #> + +**This article applies to:** ✔️ .NET Core <#= version#> SDK and later versions + +## Name + +`dotnet nuget <#= verbFormalName #> <#= nounFormalName #>` - <#= stringDictionary[(verbFormalName+nounFormalName+"CommandDescription").ToLower()] #> + +## Synopsis + +```dotnetcli +<#= commandSyntax #> +dotnet nuget <#= verbFormalName #> <#= nounFormalName #> [-h|--help] +``` + +## Description + +The `dotnet nuget <#= verbFormalName #> <#= nounFormalName #>` command <#= description #> +<# + var headerForArgumentsShown = false; + var headerForOptionsShown = false; + var headerForExamplesShown = false; + var headerForSeeAlsosShown = false; + + var arguments = new List(); + var examples = new List(); + var seeAlsos = new List(); + var sortedOptions = new List(); + + foreach (XElement option in noun.Descendants()) + { + string optionName = option.Attribute(XName.Get("Name", ""))?.Value; + string shortcut = option.Attribute(XName.Get("Shortcut", ""))?.Value; + string optionLongName = option.Attribute(XName.Get("LongName", ""))?.Value; + string helpText = option.Attribute(XName.Get("Help", ""))?.Value; + + string titleText = option.Attribute(XName.Get("Title", ""))?.Value; + string commandText = option.Attribute(XName.Get("Command", ""))?.Value; + string urlText = option.Attribute(XName.Get("Url", ""))?.Value; + + string optionFormalName = MakeFormal(optionName, shortcut)?.ToLower(); + + bool isArgument = IsArgument(GetProperty(option)); + string argumentName = GetArgumentName(optionName, optionLongName); + + var newOptionItem = new OptionItem() + { + Category = GetProperty(option), + OptionType = GetOptionType(option), + Name = optionName, + OptionFormalName = optionFormalName, + Shortcut = shortcut, + OptionLongName = optionLongName, + HelpText = helpText, + TitleText = titleText, + CommandText = commandText, + UrlText = urlText, + IsArgument = isArgument, + ArgumentName = argumentName, + }; + + switch (newOptionItem.Category) + { + case "Argument": + arguments.Add(newOptionItem); + break; + case "Example": + examples.Add(newOptionItem); + break; + case "SeeAlso": + seeAlsos.Add(newOptionItem); + break; + default: + sortedOptions.Add(newOptionItem); + break; + } + } + + sortedOptions = sortedOptions.OrderBy(i => i.Name).ToList(); +#> +<# + foreach (var argumentItem in arguments) + { + if (argumentItem.Category == "Argument") + { + if (!headerForArgumentsShown) + { +#> + +## Arguments + +<# + headerForArgumentsShown = true; + } +#> +- **`<#= argumentItem.ArgumentName #>`** + + <#= + GetHelpTextWithOverride(stringDictionary, argumentItem.HelpText) #> +<# + } + } +#> +<# + foreach (var optionItem in sortedOptions) + { + if (!headerForOptionsShown) + { +#> + +## Options + +<# + headerForOptionsShown = true; + } + + switch (optionItem.OptionType) + { + case "SingleValue": +#> +- **`<#= optionItem.OptionFormalName #>`** + + <#= GetHelpTextWithOverride(stringDictionary, optionItem.HelpText) #> + +<# + break; + case "NoValue": +#> +- **`<#= optionItem.OptionFormalName #>`** + + <#= GetHelpTextWithOverride(stringDictionary, optionItem.HelpText) #> + +<# + break; + case "Value": +#> +- **`<#= optionItem.OptionFormalName #>`** + + <#= GetHelpTextWithOverride(stringDictionary, optionItem.HelpText) #> + +<# + break; + } + } +#> +<# + foreach (var exampleItem in examples) + { + { + if (!headerForExamplesShown) + { +#> +## Examples +<# + headerForExamplesShown = true; + } +#> + +- <#= exampleItem.TitleText #> + + ```dotnetcli + <#= exampleItem.CommandText #> + ``` +<# + } + } +#> +<# + foreach (var seeAlsoItem in seeAlsos) + { + if (!headerForSeeAlsosShown) + { +#> + +## See also +<# + headerForSeeAlsosShown = true; + } +#> + +- [<#= seeAlsoItem.TitleText #>](<#= seeAlsoItem.UrlText #>) +<# + } +#> +<# + } + } +#> diff --git a/src/NuGet.Core/NuGet.CommandLine.XPlat/external/docsHelpers.t4 b/src/NuGet.Core/NuGet.CommandLine.XPlat/external/docsHelpers.t4 new file mode 100644 index 00000000000..f25d8b4d821 --- /dev/null +++ b/src/NuGet.Core/NuGet.CommandLine.XPlat/external/docsHelpers.t4 @@ -0,0 +1,19 @@ +<#@ template language="C#" #> + +<#+ + public class OptionItem + { + public string Category { get; set; } + public string Name { get; set; } + public string OptionFormalName { get; set; } + public string Shortcut { get; set; } + public string OptionType { get; set; } + public string OptionLongName { get; set; } + public string HelpText { get; set; } + public string TitleText { get; set; } + public string CommandText { get; set; } + public string UrlText { get; set; } + public bool IsArgument { get; set; } + public string ArgumentName { get; set; } + } +#> diff --git a/src/NuGet.Core/NuGet.CommandLine.XPlat/external/readme.md b/src/NuGet.Core/NuGet.CommandLine.XPlat/external/readme.md new file mode 100644 index 00000000000..0f8d05bec18 --- /dev/null +++ b/src/NuGet.Core/NuGet.CommandLine.XPlat/external/readme.md @@ -0,0 +1 @@ +These files under the external directory, are files that are related to this DLL, but are needed to generate docs content or code for other repos. diff --git a/src/NuGet.Core/NuGet.Commands/CommandArgs/VerbArgs.tt b/src/NuGet.Core/NuGet.Commands/CommandArgs/VerbArgs.tt index 98ebd52b212..2192d51eef1 100644 --- a/src/NuGet.Core/NuGet.Commands/CommandArgs/VerbArgs.tt +++ b/src/NuGet.Core/NuGet.Commands/CommandArgs/VerbArgs.tt @@ -13,11 +13,21 @@ return output; } + bool IsArgumentOrOption(string type) + { + return IsArgument(type) || IsOption(type); + } + bool IsArgument(string type) { return type == "Argument"; } + bool IsOption(string type) + { + return type == "Option"; + } + string GetProperty(XElement element) { switch (element.Name.LocalName) @@ -26,8 +36,14 @@ return "Option"; case "SwitchOption": return "Option"; + case "Value": + return "Option"; case "Argument": return "Argument"; + case "Example": + return "Example"; + case "SeeAlso": + return "SeeAlso"; default: return "Unknown Element Type " + element.Name.LocalName; } @@ -80,34 +96,38 @@ namespace NuGet.Commands <# foreach (XElement option in noun.Descendants()) { - string optionName = option.Attribute(XName.Get("Name", "")).Value; - string optionType = option.Attribute(XName.Get("Type", ""))?.Value; - string optionFormalName = InitCaps(optionName.Replace("-","")); - if (IsArgument(GetProperty(option))) + if (IsArgumentOrOption(GetProperty(option))) { + string optionName = option.Attribute(XName.Get("Name", ""))?.Value; + string optionType = option.Attribute(XName.Get("Type", ""))?.Value; + string optionFormalName = InitCaps(optionName?.Replace("-","")); + + if (IsArgument(GetProperty(option))) + { #> public string <#= optionFormalName #> { get; set; } <# - } - else - { - switch (GetOptionType(option)) + } + else if (IsOption(GetProperty(option))) { - case "SingleValue": + switch (GetOptionType(option)) + { + case "SingleValue": #> public string <#= optionFormalName #> { get; set; } <# - break; - case "NoValue": + break; + case "NoValue": #> public bool <#= optionFormalName #> { get; set; } <# - break; - case "Value": + break; + case "Value": #> public <#= optionType #> <#= optionFormalName #> { get; set; } <# - break; + break; + } } } }