Справочник по конфигурациям в C#

СПРАВОЧНИК

Справочник-шпаргалка по конфигурациям в C# — типы, синтаксис, стандартная библиотека, типовые паттерны. Не заменяет пошаговое обучение. Учебный курс: раздел.

Учебные статьи: Типы данных · Работа с типами.

Справочные таблицы

Содержание справочника

1. .csproj — файл проекта (MSBuild)
2. Directory.Build.props и Directory.Build.targets
3. global.json
4. launchSettings.json — настройки запуска (отладка и CLI)
5. appsettings.json и окружения
6. runtimeconfig.json — конфигурация среды выполнения
7. deps.json — зависимости приложения
8. packages.lock.json — фиксация версий зависимостей
9. nuget.config — глобальные и локальные настройки NuGet
10. packages.config — устаревшая модель управления пакетами
11. project.assets.json — промежуточный файл восстановления
12. .nuspec — манифест NuGet-пакета
13. Дополнительные параметры в .csproj для публикации и упаковки
14. app.config / web.config — конфигурация .NET Framework
15. Трансформации конфигурации (web.debug.config, web.release.config)
16. Внешние файлы конфигурации
17. machine.config
18. Settings.settings и userSettings
19. WCF-конфигурация (System.serviceModel)
20. app.manifest — манифест приложения Windows
21. Дополнительно: CPVM и анализ

1. `.csproj` — файл проекта (MSBuild)

Файл описывает компиляцию, ссылки, пакеты и свойства сборки. Является XML-документом, совместимым с MSBuild.

1.1. Корневой элемент и базовые атрибуты

<Project Sdk="Microsoft.NET.Sdk">

Sdk — указывает на SDK-проект (.NET SDK — Microsoft.NET.Sdk, веб — Microsoft.NET.Sdk.Web, для тестов — Microsoft.NET.Sdk.Test).
- Допустимые значения:
  - Microsoft.NET.Sdk
  - Microsoft.NET.Sdk.Web
  - Microsoft.NET.Sdk.Worker
  - Microsoft.NET.Sdk.Razor
  - Microsoft.NET.Sdk.WindowsDesktop (WPF/WinForms)
  - Microsoft.NET.Sdk.BlazorWebAssembly
  - MSBuild.Sdk.Extras — для кроссплатформенных библиотек (Xamarin, UWP и т.п.)
- Влияет на импортируемые props и targets.
- Можно явно импортировать SDK через <Import Sdk="..." />, но это редко нужно.

1.2. `<PropertyGroup>` — свойства проекта

Основные свойства (часто объединяются по Condition или Label):

Свойство	Тип	Описание	Значение по умолчанию / примечания
`TargetFramework`	строка	Целевая платформа (одна). Для нескольких — `TargetFrameworks`.	Например: `net8.0`, `net7.0-windows`, `net6.0-android34.0`. Формат: `net[версия][-ОС[-версия]]`.
`TargetFrameworks`	строка	Список через `;`. Например: `net6.0;net7.0;net8.0`.	При его наличии `TargetFramework` игнорируется.
`OutputType`	строка	Тип выходного файла.	`Library`, `Exe`, `WinExe`, `Module`, `AppContainerExe`, `WinMdObj`.
`AssemblyName`	строка	Имя сборки (без расширения `.dll`/`.exe`).	По умолчанию — имя проекта.
`RootNamespace`	строка	Корневое пространство имён.	По умолчанию — `AssemblyName`.
`LangVersion`	строка	Версия языка C#.	`latest`, `preview`, `default`, или явно: `10.0`, `11.0`, `12.0`.
`Nullable`	строка	Включение Nullable Reference Types.	`enable`, `disable`, `annotations`, `warnings`.
`ImplicitUsings`	строка	Авто-добавление `global using` из SDK.	`enable`, `disable`.
`NullableContextOptions`	строка	[Устаревшее] — заменено `Nullable`.
`GenerateDocumentationFile`	bool	Создание XML-документации.	`false`. При `true` генерируется `<AssemblyName>.xml`.
`DocumentationFile`	путь	Явный путь к XML-файлу документации.	Автоматически `<OutputPath><AssemblyName>.xml`, если не задано.
`NoWarn`, `WarningsAsErrors`, `TreatWarningsAsErrors`	список / bool	Управление предупреждениями.	`NoWarn` — через `;`, например: `CS1591;NU1701`. `TreatWarningsAsErrors` приоритетнее `WarningsAsErrors`.
`DebugType`	строка	Формат отладочной информации.	`portable` (по умолчанию), `full`, `pdbonly`, `embedded`, `none`.
`DebugSymbols`	bool	Генерировать ли `.pdb`.	`true` в `Debug`, `false` в `Release`, если не переопределено.
`Deterministic`	bool	Детерминированная сборка (стабильный `MVID`).	`true` по умолчанию в SDK-проектах.
`ContinuousIntegrationBuild`	bool	Признак CI-сборки (влияет на `SourceLink`, `EmbedAllSources`).	Обычно `true` в CI.
`EmbedAllSources`	bool	Встраивать исходники в `.pdb`.	Требует `DebugType=embedded` или `portable` + SourceLink.
`PublishReadyToRun`	bool	AOT-компиляция (R2R).	Требует указания `RuntimeIdentifier`.
`PublishSingleFile`	bool	Упаковка в один исполняемый файл.	Может конфликтовать с `SelfContained=false`.
`SelfContained`	bool	Включать ли runtime в публикацию.	По умолчанию `true`, если указан `RuntimeIdentifier`.
`RuntimeIdentifier`, `RuntimeIdentifiers`	строка / список	Целевые RID (например, `win-x64`, `linux-arm64`).	При `RuntimeIdentifiers` — мультиплатформенная публикация.
`PlatformTarget`	строка	Целевая архитектура.	`AnyCPU` (по умолчанию), `x86`, `x64`, `arm64`, `Itanium`. Влияет на JIT, но не на RID.
`IsPackable`	bool	Включать ли проект в `dotnet pack`.	`true`, если есть `PackageId` или `PackageVersion`.
`PackageId`, `PackageVersion`, `Authors`, `Description`, `PackageLicenseExpression`, `PackageProjectUrl`, `RepositoryUrl`, `RepositoryType`, `PackageTags`	строка	Метаданные NuGet-пакета.	Обязательны только `PackageId` и `PackageVersion` для `pack`.
`AnalysisLevel`	строка	Уровень анализа кода (CAxxx).	`latest`, `5`, `5.0`, `6.0`, `7.0`, `8.0`, `preview`. Или `none`.
`EnforceCodeStyleInBuild`	bool	Применять правила из `.editorconfig` на уровне ошибок.	`false` по умолчанию. Требует `<AnalysisMode>` или `<CodeAnalysisTreatWarningsAsErrors>`.
`AnalysisMode`	строка	Набор правил анализа.	`all`, `recommended`, `minimum`, `none`. Можно уточнить: `AnalysisLevel` + `AnalysisMode`.
`EnableNETAnalyzers`	bool	Включить встроенные анализаторы .NET.	`true` по умолчанию, начиная с .NET 5.
`RestorePackagesWithLockFile`	bool	Использовать `packages.lock.json`.	`false`. При `true` — фиксация версий зависимостей.
`CopyLocalLockFileAssemblies`	bool	Копировать зависимости в выходную папку (даже если не `SelfContained`).	`false` — только при `dotnet publish`. Полезно для отладки локальных зависимостей.

Пример

<PropertyGroup>
  <TargetFramework>net8.0</TargetFramework>
  <ImplicitUsings>enable</ImplicitUsings>
  <Nullable>enable</Nullable>
  <LangVersion>12.0</LangVersion>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);CS1591</NoWarn>
  <AnalysisLevel>8.0-recommended</AnalysisLevel>
  <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
</PropertyGroup>

1.3. `<ItemGroup>` — элементы проекта

1.3.1. `<PackageReference>`

<PackageReference Include="Newtonsoft.Json" Version="13.0.3" />

Доп. атрибуты:

Version — строка, семвер (может включать *, например 13.0.* — но не рекомендуется).
PrivateAssets — all, runtime, compile, contentfiles, analyzers, build, none. Определяет, что не передаётся по транзитивности.
ExcludeAssets: аналогично, но исключает из текущего проекта.
GeneratePathProperty: true — создаёт MSBuild-свойство PkgNewtonsoft_Json, указывающее на папку пакета.
IncludeAssets: ограничивает, какие части пакета использовать.

1.3.2. `<ProjectReference>`

<ProjectReference Include="..\Shared\Shared.csproj" />

Доп. атрибуты:

Private: true/false — влияет на PrivateAssets при упаковке NuGet.
SkipGetTargetFrameworkProperties: true — отключает проверку совместимости TargetFramework.
GlobalPropertiesToRemove: список свойств, удаляемых при построении зависимого проекта (через ;).

1.3.3. `<Reference>` — ссылка на сборку (устаревшее, но допустимо)

<Reference Include="System.Data" />
<Reference Include="MyAssembly">
  <HintPath>..\lib\MyAssembly.dll</HintPath>
</Reference>

HintPath — путь к .dll.
SpecificVersion — true/false.
Private — копировать ли в выходную папку.

1.3.4. `<Compile>`, `<EmbeddedResource>`, `<None>`, `<Content>`

Update, Remove, Include — для тонкой настройки элементов.
Атрибуты:
- DependentUpon — для вложенности в IDE (.Designer.cs → .cs).
- Link — виртуальный путь в Solution Explorer.
- CopyToOutputDirectory — Never, Always, PreserveNewest.
- Visible: true/false — отображать в IDE.
- ExcludeFromSingleFile: true — исключить из PublishSingleFile.

1.3.5. `<FrameworkReference>` — ссылка на метапакет фреймворка

<FrameworkReference Include="Microsoft.AspNetCore.App" />

Требуется для Microsoft.NET.Sdk.Web, но может быть явно указано.

2. `Directory.Build.props` и `Directory.Build.targets`

Файлы для наследуемых настроек на уровне каталога.

Обрабатываются рекурсивно: от корня к проекту.
Directory.Build.props импортируется до содержимого .csproj.
Directory.Build.targets — после.

Пример `Directory.Build.props`

<Project>
  <PropertyGroup>
    <LangVersion>12.0</LangVersion>
    <Nullable>enable</Nullable>
    <AnalysisLevel>8.0-all</AnalysisLevel>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="8.0.0" PrivateAssets="all" />
  </ItemGroup>
</Project>

⚠️ Важно: файлы не наследуются через символические ссылки и не работают при сборке из другого корневого каталога (например, dotnet build /p:ProjectDir=...).

3. `global.json`

Управляет версией SDK и поведением восстановления пакетов.

{
  "sdk": {
    "version": "8.0.100",
    "rollForward": "latestPatch",
    "allowPrerelease": false
  },
  "msbuild-sdks": {
    "MSBuild.Sdk.Extras": "3.0.44"
  },
  "tools": {
    "dotnet": "8.0.100"
  }
}

Ключ	Тип	Описание	Допустимые значения
`sdk.version`	строка	Требуемая версия .NET SDK.	Семвер (например, `7.0.403`, `8.0.100`).
`sdk.rollForward`	строка	Стратегия "перекатывания" при отсутствии точной версии.	`disable`, `latestPatch`, `minor`, `latestMinor`, `major`, `latestMajor`. По умолчанию — `latestPatch`.
`sdk.allowPrerelease`	bool	Разрешить предварительные версии SDK.	`true`/`false`.
`msbuild-sdks`	объект	Фиксация версий внешних MSBuild SDK (например, `MSBuild.Sdk.Extras`).	Ключ — имя SDK, значение — версия.
`tools.dotnet`	строка	(Устаревшее) — дублирует `sdk.version`.

Файл ищется вверх по дереву каталогов от проекта.

4. `launchSettings.json` — настройки запуска (отладка и CLI)

Располагается в Properties/launchSettings.json. Используется только в среде разработки — Visual Studio, VS Code, dotnet run. Не включается в сборку (dotnet publish игнорирует его).

dotnet publish

Формат — JSON. Содержит профили (profiles), переменные окружения и параметры запуска.

4.1. Корневые секции

{
  "$schema": "https://json.schemastore.org/launchsettings.json",
  "iisSettings": { ... },
  "profiles": { ... }
}

`iisSettings` — конфигурация IIS Express (только для `.Web` SDK)

Параметр	Тип	Описание	Примечания
`windowsAuthentication`	bool	Включить Windows Auth.	По умолчанию `false`.
`anonymousAuthentication`	bool	Включить анонимную аутентификацию.	По умолчанию `true`.
`iisExpress` → `applicationUrl`	строка	URL для IIS Express (например, `"http://localhost:5000"`).	Можно несколько через `;`.
`iisExpress` → `sslPort`	int	Порт для HTTPS (например, `44300`).	Автоматически генерирует сертификат `localhost`.
`iis` → `applicationUrl`, `sslPort`	—	Аналогично, но для локального IIS (редко используется).

`profiles` — набор сред запуска

Ключ — имя профиля (например, "IIS Express", "MyApp"). Каждый профиль — объект со следующими полями:

Параметр	Тип	Описание	Допустимые значения / примечания
`commandName`	строка	Команда запуска.	`"Project"` (запуск через `dotnet run`), `"IISExpress"`, `"Executable"` (произвольный exe), `"WSL2"` (для Linux в WSL), `"Docker"` (требует расширение).
`launchBrowser`	bool	Открыть браузер после запуска.	Применяется только при `commandName: "Project"` или `"IISExpress"`.
`applicationUrl`	строка	URL, передаваемый в `--urls` при `dotnet run`.	Переопределяет `ASPNETCORE_URLS`. Пример: `"https://localhost:7001;http://localhost:5001"`.
`environmentVariables`	объект	Переменные окружения.	Ключ — имя (`ASPNETCORE_ENVIRONMENT`, `DOTNET_ENVIRONMENT`), значение — строка. Например: `"ASPNETCORE_ENVIRONMENT": "Разработка"`.
`dotnetRunMessages`	bool	Выводить ли служебные сообщения `dotnet run`.	`true`/`false`.
`executablePath`	строка	Путь к исполняемому файлу (при `commandName: "Executable"`).
`commandLineArgs`	строка	Аргументы командной строки для `executablePath`.
`workingDirectory`	строка	Рабочая директория при запуске.	По умолчанию — корень проекта.
`nativeDebugging`	bool	Включить отладку неуправляемого кода.	Требует настройки отладчика.
`sqlDebugging`	bool	Отладка SQL (только в VS Enterprise).
`remoteDebugEnabled`	bool	Удалённая отладка (`clrdbg` на удалённой машине).
`dockerRunCommand`	строка	Команда `docker run` (при `commandName: "Docker"`).	Устаревшее; предпочтительно использовать `Dockerfile`.

Пример профиля

Код ITЗагрузка примера кода…

⚠️ Нюансы:

Изменения в launchSettings.json вступают в силу без пересборки, но могут потребовать перезапуска отладчика.
Переменные из environmentVariables переопределяют системные.
ASPNETCORE_ENVIRONMENT влияет на загрузку appsettings.{Environment}.json.

5. `appsettings.json` и окружения

Файл конфигурации приложения времени выполнения. Поддерживается через Microsoft.Extensions.Configuration.

5.1. Формат и загрузка

По умолчанию:

appsettings.json
appsettings.{Environment}.json (например, appsettings.Разработка.json)
Переменные окружения
Аргументы командной строки

Порядок — переопределение: последующие источники перекрывают предыдущие.

5.2. Поддерживаемые типы значений

string, bool, int, long, double, decimal
Объекты (вложенные section)
Массивы (через [0], [1] или объекты)

Пример

Код ITЗагрузка примера кода…

5.3. Специальные секции (интерпретируются фреймворком)

Секция	Описание	Примечания
`Logging`	Настройки логгера.	Поддерживает `LogLevel`, `Console`, `Debug`, `EventLog`, `ApplicationInsights`.
`AllowedHosts`	Список разрешённых хостов для `HostFiltering`.	`"*"` — разрешить все. Обязательно для безопасности в production.
`ConnectionStrings`	Строки подключения.	Доступ через `Configuration.GetConnectionString("name")`.
`Kestrel`	Конфигурация Kestrel.	Поддерживает `Endpoints`, `Limits`, `Certificates`.
`Serilog` / `NLog` / `log4net`	При наличии соответствующих провайдеров.	Не встроены, но широко используются.
`Azure` / `AWS` / `Google`	Секции для облачных SDK.	Например, `Azure:ServiceBus:ConnectionString`.

5.4. Переменные окружения как источник

Иерархия заменяется на __ (два подчёркивания):
Logging__LogLevel__Default=Debug
Имена — case-insensitive в Windows, case-sensitive в Linux.
ASPNETCORE_ и DOTNET_ префиксы имеют приоритет (например, ASPNETCORE_URLS переопределяет applicationUrl из launchSettings).

6. `runtimeconfig.json` — конфигурация среды выполнения

Генерируется при сборке (dotnet build) и публикации (dotnet publish). Располагается рядом с .dll: <AssemblyName>.runtimeconfig.json.

dotnet build

Содержит параметры для dotnet <app>.dll.

dotnet <app>.dll

6.1. Структура

Код ITЗагрузка примера кода…

`runtimeOptions` → ключи

Ключ	Тип	Описание	Допустимые значения / примечания
`tfm`	строка	Целевой фреймворк.	Влияет на загрузку метаданных.
`framework`	объект	Основной фреймворк (для framework-dependent apps).	`name`: `Microsoft.NETCore.App`, `Microsoft.AspNetCore.App`, `Microsoft.WindowsDesktop.App`. `version`: минимальная требуемая версия.
`frameworks`	массив	Множественные фреймворки (редко).	Например, для приложений с `Microsoft.NETCore.App` + `Microsoft.AspNetCore.App`.
`rollForward`	строка	Стратегия обновления runtime.	`LatestPatch`, `Minor`, `LatestMinor`, `Major`, `LatestMajor`, `Disable`. По умолчанию — `Minor`.
`applyPatches`	bool	Применять ли патчи (даже при `rollForward: "Disable"`).	Устаревшее.
`configProperties`	объект	Параметры CLR и BCL.	См. ниже.

`configProperties` — ключевые настройки CLR

Ключ	Тип	Описание	По умолчанию
`System.GC.Server`	bool	Серверный GC.	`true` для ASP.NET, `false` для консольных приложений.
`System.GC.Concurrent`	bool	Параллельная сборка мусора.	`true`.
`System.GC.RetainVM`	bool	Удерживать память после GC (не возвращать ОС).	`false`.
`System.Threading.ThreadPool.MinThreads`	int	Мин. число потоков в пуле.	Зависит от ядер.
`System.Threading.ThreadPool.MaxThreads`	int	Макс. число потоков.	Очень большое (≈32767).
`System.Globalization.Invariant`	bool	Отключить локализацию (меньше памяти, быстрее).	`false`.
`System.Reflection.Metadata.MetadataUpdater.IsSupported`	bool	Разрешить hot reload.	`true` в Debug, `false` в Release.
`System.Runtime.Loader.DefaultContext.TrustedPlatformAssemblies`	строка	Явный список `.dll` (для изолированных загрузчиков).	Редко используется.
`Microsoft.NET.HostModel.AppHost.OptimizeAppHost`	bool	Оптимизировать `apphost` (self-contained).	`true`.

⚠️ Эти параметры можно задавать:

через runtimeconfig.template.json (в проекте: <RuntimeHostConfigurationOption>),
через переменные окружения (префикс DOTNET_),
через аргументы dotnet (например, --runtimeconfig).

Пример `runtimeconfig.template.json`

{
  "configProperties": {
    "System.GC.Server": true,
    "System.Globalization.Invariant": true
  }
}

В .csproj:

<PropertyGroup>
  <RuntimeHostConfigurationOption Include="System.Globalization.Invariant" Value="true" />
</PropertyGroup>

7. `deps.json` — зависимости приложения

Генерируется при сборке (<AssemblyName>.deps.json). Содержит:

список всех зависимостей (включая транзитивные),
пути к сборкам,
хэши,
runtime и compile-временные зависимости,
native-библиотеки (.so, .dylib, .dll).

7.1. Структура

{
  "runtimeTarget": { "name": ".NETCoreApp,Version=v8.0", ... },
  "targets": {
    ".NETCoreApp,Version=v8.0": {
      "MyApp/1.0.0": { "runtime": { "MyApp.dll": { } } },
      "Newtonsoft.Json/13.0.3": {
        "runtime": { "lib/netstandard2.0/Newtonsoft.Json.dll": { } },
        "compile": { "ref/netstandard2.0/Newtonsoft.Json.dll": { } }
      }
    }
  },
  "libraries": { ... }
}

7.2. Ключевые секции

Секция	Описание
`runtimeTarget`	Целевая платформа и RID (если self-contained).
`targets`	Группировка зависимостей по TFM/RID.
`libraries`	Метаданные о каждой библиотеке: хэш, тип (`project`, `package`, `reference`), пути.
`runtimes`	Native-зависимости по RID (например, `win-x64/native/sqlite3.dll`).

⚠️ Этот файл обязателен для dotnet exec и запуска framework-dependent приложений. При его отсутствии — ошибка:

Error: assembly specified in the dependencies manifest was not found...

Изменять вручную не рекомендуется — используется только для диагностики и tooling (например, dotnet store).

dotnet store

8. `packages.lock.json` — фиксация версий зависимостей

Файл генерируется при первом восстановлении (dotnet restore), если в .csproj указано:

dotnet restore

<PropertyGroup>
  <RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
</PropertyGroup>

Цель — детерминированное восстановление: одинаковые версии пакетов на всех машинах и в CI.

8.1. Структура

Код ITЗагрузка примера кода…

Поле	Описание
`version`	Версия формата (на данный момент только `1`).
`dependencies`	Объект: ключ — TFM (например, `net8.0`, `net7.0-windows`), значение — дерево зависимостей.
`type`	`Direct` — прямая зависимость, `Transitive` — транзитивная.
`dependencies` (внутри пакета)	Точный список дочерних пакетов и их версий.

8.2. Поведение

При dotnet restore:
- Если packages.lock.json есть, NuGet строго следует ему (даже если в .csproj указана 13.*).
- Если packages.lock.json отсутствует, он создаётся.
Чтобы обновить — удалите файл и выполните dotnet restore, или используйте:

  dotnet restore --force-evaluate

Для CI рекомендуется коммитить packages.lock.json.

⚠️ Ограничения:

Не поддерживает динамические версии (*, latest).
Не влияет на PackageReference с Version="..." в .csproj — версии в .csproj и .lock должны совпадать.
Может конфликтовать с CentralPackageVersionManagement (CPVM).

9. `nuget.config` — глобальные и локальные настройки NuGet

Файл может располагаться:

в корне решения (рекомендуется),
в ~/.nuget/NuGet/NuGet.Config (глобальный),
в %AppData%\NuGet\NuGet.Config (Windows),
в $XDG_CONFIG_HOME/NuGet/NuGet.Config или ~/.config/NuGet/NuGet.Config (Linux/macOS).

Формат — XML.

9.1. Основные секции

Код ITЗагрузка примера кода…

9.2. Ключевые параметры

В `<config>`

Ключ	Описание	Примечания
`repositoryPath`	Каталог для `packages.config` (устаревшее).	Не влияет на `PackageReference`.
`globalPackagesFolder`	Глобальный кэш пакетов (`~/.nuget/packages`).	Можно переопределить через `NUGET_PACKAGES`.
`http_proxy`, `https_proxy`	Прокси для скачивания пакетов.	Поддерживает аутентификацию через `user:pass@host:port`.
`no_proxy`	Список хостов без прокси (через `,`).	Может включать домены и CIDR-блоки.
`defaultPushSource`	Источник по умолчанию для `nuget push`.
`dependencyVersion`	Стратегия выбора версий при восстановлении.	`Lowest`, `HighestPatch`, `HighestMinor`, `Highest`. По умолчанию — `Lowest`.

В `<packageSources>`

<clear /> — сброс настроек из родительских конфигов.
Порядок источников важен: первое совпадение побеждает.
Можно использовать локальные источники: value="C:\local-packages".

В `<packageSourceCredentials>`

Поддерживает ClearTextPassword, Password (зашифрован), ValidAuthenticationTypes.
Для Azure Artifacts рекомендуется использовать AzureDevOpsCredentialProvider.

Прочие секции

Секция	Назначение
`<solution>`	`<add key="disableSourceControlIntegration" value="true" />` — отключить `.nuget` в TFS.
`<bindingRedirects>`	Автогенерация `app.config`-перенаправлений (для legacy).

10. `packages.config` — устаревшая модель управления пакетами

Использовалась до .NET Core. Хранит все зависимости в одном XML-файле.

10.1. Структура

<?xml version="1.0" encoding="utf-8"?>
<packages>
  <package id="Newtonsoft.Json" version="13.0.3" targetFramework="net48" />
  <package id="Microsoft.AspNet.Mvc" version="5.2.9" targetFramework="net48" />
</packages>

Атрибут	Описание
`id`	Имя пакета.
`version`	Точная версия.
`targetFramework`	Целевой фреймворк (например, `net48`, `net461`).
`allowedVersions`	Ограничение обновлений (например, `[13.0,14.0)`).

10.2. Недостатки (почему устарела)

Нет транзитивных зависимостей — все зависимости дублируются.
Нет централизованного управления версиями.
Зависимости копируются в packages/, увеличивая размер репозитория.
Не поддерживает dotnet CLI (только nuget.exe и msbuild legacy).
Не совместима с PackageReference.

Конвертация:

nuget.exe update MyProject.csproj -self

11. `project.assets.json` — промежуточный файл восстановления

Генерируется в obj/project.assets.json при dotnet restore. Используется MSBuild и dotnet build для:

dotnet restore

разрешения зависимостей,
формирования deps.json,
копирования сборок в выходную папку.

11.1. Структура (сокращённо)

{
  "version": 3,
  "targets": { ... },
  "libraries": { ... },
  "projectFileDependencyGroups": {
    "net8.0": [ "Newtonsoft.Json >= 13.0.3" ]
  },
  "packageFolders": {
    "C:\\Users\\user\\.nuget\\packages\\": {}
  }
}

Секция	Описание
`targets`	Зависимости по TFM/RID. Аналог `deps.json`, но до упаковки.
`libraries`	Метаданные пакетов: тип, хэш, версия, зависимости.
`projectFileDependencyGroups`	Группировка по TFM: какие `PackageReference` были в `.csproj`.
`packageFolders`	Каталоги с пакетами (глобальный кэш, fallback folders).

⚠️ Этот файл не коммитится (в .gitignore по умолчанию).
Если повреждён — пересоздайте артефакты restore:

rm -rf obj bin
dotnet restore

12. `.nuspec` — манифест NuGet-пакета

Файл XML, описывающий пакет. Может генерироваться автоматически из .csproj, либо создаваться вручную.

12.1. Структура (минимальная)

Код ITЗагрузка примера кода…

12.2. Элементы `<metadata>`

Элемент	Обязательный	Описание	Заметки
`id`	✅	Уникальное имя пакета.	Должно совпадать с `PackageId`.
`version`	✅	Версия пакета (семвер).	Может содержать метки: `1.0.0-alpha`.
`authors`	✅	Авторы.	Разделитель — `,`.
`description`	✅	Описание (до 4000 символов).	Поддерживает Markdown в некоторых клиентах.
`license`	✅ (или `licenseUrl`)	Лицензия.	Предпочтительно `type="expression"` (SPDX: `MIT`, `Apache-2.0`).
`projectUrl`	❌	Ссылка на проект.	Отображается в NuGet.org.
`icon`	❌	Путь к иконке в пакете (например, `icon.png`).	Должен быть в `<files>`.
`readme`	❌	`readme.md` в корне пакета.	Отображается на NuGet.org.
`repository`	❌	Тип и URL репозитория.	Поддерживает `git`, `svn`, `hg`.
`tags`	❌	Ключевые слова (через пробел).	Улучшает поиск.
`releaseNotes`	❌	Изменения в версии.	Поддерживает Markdown.
`copyright`	❌	Уведомление об авторских правах.	Например: `© 2025 Timur Tagirov`.

12.3. `<files>` — содержимое пакета

target — папка в распакованном пакете:
- lib/{tfm}/ — сборки времени выполнения,
- ref/{tfm}/ — reference-сборки (для компиляции),
- runtimes/{rid}/native/ — native-библиотеки,
- content/ — файлы, копируемые в проект (устаревшее),
- build/ — .targets/.props для MSBuild,
- analyzers/dotnet/cs/ — анализаторы.

Пример структуры пакета

MyLib.1.0.0.nupkg
├── lib/
│   └── net8.0/
│       └── MyLib.dll
├── ref/
│   └── net8.0/
│       └── MyLib.dll
├── build/
│   └── MyLib.targets
├── icon.png
├── README.md
└── MyLib.nuspec

13. Дополнительные параметры в `.csproj` для публикации и упаковки

13.1. `dotnet publish` — параметры публикации

dotnet publish

Свойство	Описание	Пример
`PublishDir`	Целевая папка.	`/p:PublishDir=./out`
`PublishReadyToRun`	AOT-компиляция (R2R).	`true`
`PublishSingleFile`	Один файл.	`true`
`IncludeNativeLibrariesForSelfExtract`	Включить native-библиотеки в single-file.	`true` (по умолчанию при `PublishSingleFile=true`)
`SelfContained`	Включить runtime.	`true`/`false`
`RuntimeIdentifier`	Целевой RID.	`win-x64`, `linux-arm64`
`PublishTrimmed`	Обрезка неиспользуемого кода (linking).	`true` (осторожно: может сломать reflection)
`TrimMode`	`copyused`, `link`.
`SuppressTrimAnalysisWarnings`	Подавить предупреждения обрезки.	`true`
`DebugType`	Тип отладки в publish.	`embedded` — встроить `.pdb` в `.dll`
`ContinuousIntegrationBuild`	Включить SourceLink и детерминированность.	`true`

13.2. `dotnet pack` — параметры упаковки

Свойство	Описание
`IsPackable`	Включать ли в `pack`.
`PackageOutputPath`	Куда класть `.nupkg`.
`IncludeSymbols`	Генерировать `.snupkg`.
`SymbolPackageFormat`	`snupkg`, `symbols.nupkg`.
`EmbedUntrackedSources`	Встраивать исходники без истории git.
`EmbedAllSources`	Встраивать все исходники.
`AllowedOutputExtensionsInPackageBuildOutputFolder`	Какие расширения включать в `build/`. Например: `.dll;.pdb;.xml`.

Типовые команды CLI:

dotnet publish -c Release -r linux-x64 --self-contained true \
  -p:PublishSingleFile=true -p:PublishTrimmed=true
dotnet pack -c Release -o ./nupkgs
dotnet restore --force-evaluate

14. `app.config` / `web.config` — конфигурация .NET Framework

Файл app.config переименовывается в <AssemblyName>.exe.config при сборке. Для ASP.NET — web.config.

14.1. Корневая структура

Код ITЗагрузка примера кода…

14.2. `<configSections>` — объявление секций

Обязательно первым дочерним элементом <configuration>.

Элемент `<section>`

<section 
  name="mySection"
  type="System.Configuration.NameValueSectionHandler"
  allowLocation="true"
  requirePermission="false" />

Атрибут	Описание
`name`	Имя секции в конфигурации.
`type`	Полное имя класса + сборка (или встроенного обработчика).
`allowLocation`	Можно ли использовать `<location>` вокруг секции.
`requirePermission`	Требуются ли права администратора для чтения.

Встроенные обработчики секций

Тип	Описание	Формат секции
`System.Configuration.AppSettingsSection`	Для `<appSettings>`	`<add key="K" value="V" />`
`System.Configuration.NameValueSectionHandler`	Простой key-value	`<add key="K" value="V" />`
`System.Configuration.DictionarySectionHandler`	То же, но возвращает `IDictionary`	`<add key="K" value="V" />`
`System.Configuration.SingleTagSectionHandler`	Один тег с атрибутами	`<my attr1="v1" attr2="v2" />`
`System.Configuration.IgnoreSectionHandler`	Игнорировать секцию	Любое содержимое

`<sectionGroup>` — группировка секций

<sectionGroup name="applicationSettings" 
              type="System.Configuration.ApplicationSettingsGroup, System">
  <section name="MyApp.Properties.Settings"
           type="System.Configuration.ClientSettingsSection, System" />
</sectionGroup>

14.3. Системные секции

`<startup>`

<startup useLegacyV2RuntimeActivationPolicy="true">
  <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.8" />
</startup>

Элемент/атрибут	Описание
`useLegacyV2RuntimeActivationPolicy`	Разрешить загрузку смешанных сборок (mixed-mode) под CLR 4.
`supportedRuntime` → `version`	`v2.0.50727`, `v4.0.30319`.
`supportedRuntime` → `sku`	`.NETFramework,Version=v4.8`, `.NETCoreApp,Version=v3.1` (редко).

`<runtime>`

Контролирует поведение CLR.

`<assemblyBinding>`

<runtime>
  <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
    <dependentAssembly>
      <assemblyIdentity name="Newtonsoft.Json" 
                        publicKeyToken="30ad4fe6b2a6aeed" 
                        Культура="neutral" />
      <bindingRedirect oldVersion="0.0.0.0-13.0.0.0" newVersion="13.0.0.0" />
      <codeBase version="13.0.0.0" href="lib/Newtonsoft.Json.dll" />
    </dependentAssembly>
  </assemblyBinding>
</runtime>

Элемент	Описание
`assemblyIdentity`	Уникальный идентификатор сборки (имя + `publicKeyToken`).
`bindingRedirect`	Перенаправление версий. Формат: `A-B` → `C`.
`codeBase`	Явный путь к `.dll` (для сборок вне GAC).
`publisherPolicy`	`apply="no"` — игнорировать политики издателя.

Прочие параметры `<runtime>`

Параметр	Описание	Значение
`<gcServer enabled="true" />`	Серверный GC.	`true`/`false`.
`<gcConcurrent enabled="true" />`	Параллельный GC.
`<legacyUnhandledExceptionPolicy enabled="false" />`	Обратная совместимость с .NET 1.1.
`<loadFromRemoteSources enabled="true" />`	Загрузка сборок из сети (UNC, HTTP).	Требуется для `Assembly.LoadFrom("//server/app.dll")`.
`<generatePublisherEvidence enabled="false" />`	Отключить проверку подписи (ускоряет запуск).

`<System.web>` — настройки ASP.NET

Секция	Описание
`compilation`	`debug="true"`, `targetFramework="4.8"`, `batch="true"`.
`authentication`	`mode="Windows"`, `mode="Forms"`.
`authorization`	`<allow users="*"/>`, `<deny users="?" />`.
`sessionState`	`mode="InProc"`, `mode="StateServer"`, `mode="SQLServer"`.
`httpRuntime`	`maxRequestLength="4096"`, `executionTimeout="110"`.
`customErrors`	`mode="RemoteOnly"`, `<error statusCode="404" redirect="404.htm" />`.
`pages`	`viewStateEncryptionMode="Always"`, `controlRenderingCompatibilityVersion="4.8"`.

`<System.Data>`

<System.Data>
  <DbProviderFactories>
    <remove invariant="System.Data.SQLite" />
    <add name="SQLite Data Provider"
         invariant="System.Data.SQLite"
         description=".NET Framework Data Provider for SQLite"
         type="System.Data.SQLite.SQLiteFactory, System.Data.SQLite" />
  </DbProviderFactories>
</System.Data>

Используется для регистрации ADO.NET-провайдеров.

15. Трансформации конфигурации (`web.debug.config`, `web.release.config`)

Механизм Visual Studio для изменения web.config при публикации.

15.1. Синтаксис трансформаций

Атрибут	Описание	Пример
`xdt:Transform="Replace"`	Полная замена элемента.	`<compilation xdt:Transform="Replace" debug="false" />`
`xdt:Transform="Insert"`	Вставка элемента.	`<add key="Feature" value="On" xdt:Transform="Insert" />`
`xdt:Transform="Remove"`	Удаление элемента.	`<add key="DebugOnly" xdt:Transform="Remove" />`
`xdt:Transform="RemoveAll"`	Удалить все совпадения.	`<add xdt:Transform="RemoveAll" xdt:Locator="XPath(//add[@key='Temp'])" />`
`xdt:Transform="SetAttributes"`	Замена атрибутов.	`<compilation xdt:Transform="SetAttributes" debug="false" />`
`xdt:Locator="Match(key)"`	Поиск по атрибуту `key`.	`<add key="LogLevel" xdt:Locator="Match(key)" xdt:Transform="SetAttributes" value="Warn" />`

15.2. Автоматические трансформации (VS)

web.debug.config → применяется при сборке в Debug,
web.release.config → при Release,
web.{Profile}.config → при публикации с профилем Profile.

⚠️ Не работает с dotnet publish (только MSBuild + VS).

dotnet publish

Альтернатива в .NET Core+: appsettings.{Environment}.json.

16. Внешние файлы конфигурации

16.1. `configSource`

Выносит секцию в отдельный файл:

<appSettings configSource="appSettings.secret.config" />

Файл должен содержать только содержимое секции, без <appSettings>.
Путь — относительно .config.
Файл не может находиться в другом каталоге (только рядом или глубже).

16.2. `file` (только для `<appSettings>`)

Аналогично, но позволяет объединять значения:

<appSettings file="local.overrides.config">
  <add key="BaseUrl" value="https://prod.com" />
</appSettings>

local.overrides.config может переопределять BaseUrl и добавлять новые ключи.
Используется для локальных переопределений без коммита.

17. `machine.config`

Глобальный конфиг для всех приложений на машине. Расположение:

Windows:
C:\Windows\Microsoft.NET\Framework\v4.0.30319\Config\machine.config
C:\Windows\Microsoft.NET\Framework64\v4.0.30319\Config\machine.config
Linux/macOS (mono):
/etc/mono/4.0/machine.config

Содержит:

<configSections> по умолчанию,
<System.web> для ASP.NET,
<System.Data> с провайдерами,
<runtime> с политиками по умолчанию.

⚠️ Изменение требует прав администратора.
Редко редактируется напрямую — предпочтительно переопределять в app.config.

18. `Settings.settings` и `userSettings`

Visual Studio генерирует Properties/Settings.settings, который компилируется в app.config.

18.1. `appSettings` и `userSettings`

Критерий	`appSettings`	`userSettings`
Хранение	В `app.config`	В `%LocalAppData%\Company\Product\version\user.config`
Доступ	Только чтение (`ConfigurationManager.AppSettings`)	Чтение/запись (`Properties.Settings.Default.Key = value;`)
Область	Приложение	Пользователь + машина
Шифрование	Нет	Поддерживается через `protectedData`

18.2. `userSettings` в `app.config`

<userSettings>
  <MyApp.Properties.Settings>
    <setting name="WindowSize" serializeAs="String">
      <value>800,600</value>
    </setting>
    <setting name="Theme" serializeAs="String">
      <value>Dark</value>
    </setting>
  </MyApp.Properties.Settings>
</userSettings>

При изменении и вызове Settings.Default.Save(), значения пишутся в user.config.

19. WCF-конфигурация (`System.serviceModel`)

19.1. Структура

Код ITЗагрузка примера кода…

19.2. Ключевые узлы

Узел	Назначение
`services`	Определение хостинга сервисов.
`bindings`	Настройка транспорта (HTTP, TCP, Named Pipes).
`behaviors`	Доп. поведение (метаданные, трассировка, throttling).
`client`	Конфигурация клиентских прокси.
`diagnostics`	Включение WCF-трассировки (`<messageLogging logEntireMessage="true" />`).

20. `app.manifest` — манифест приложения Windows

Контролирует:

UAC-поведение,
DPI-awareness,
поддержку Windows тем,
Visual Styles.

20.1. Подключение

В .csproj:

<ApplicationManifest>app.manifest</ApplicationManifest>

20.2. Пример

Код ITЗагрузка примера кода…

Параметр	Описание
`level="asInvoker"`	Запуск без повышенных прав.
`level="requireAdministrator"`	Требовать права админа.
`level="highestAvailable"`	Максимальные доступные права.
`dpiAware="true/pm"`	Per-Monitor DPI Awareness (устаревший).
`dpiAwareness="PerMonitorV2"`	Современный режим (Windows 10 1703+).

21. Дополнительно — CPVM и анализ

21.1. `Directory.Packages.props` — централизованное управление версиями

Файл в корне репозитория для CentralPackageVersionManagement.

<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
  </PropertyGroup>

  <ItemGroup>
    <PackageVersion Include="Newtonsoft.Json" Version="13.0.3" />
    <PackageVersion Include="Microsoft.Extensions.Logging" Version="8.0.0" />
  </ItemGroup>
</Project>

В .csproj:

<PackageReference Include="Newtonsoft.Json" />
<!-- версия берётся из Directory.Packages.props -->

Требует:

<ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>,
NuGet >= 6.2 / .NET SDK >= 6.0.300.

21.2. `FxCopRules.ruleset` — устаревший анализ

Файл правил для Microsoft.CodeAnalysis.FxCopAnalyzers (до .NET 5).

<RuleSet Name="My Rules" ToolsVersion="16.0">
  <Rules AnalyzerId="Microsoft.Analyzers.ManagedCodeAnalysis" RuleNamespace="Microsoft.Rules.Managed">
    <Rule Id="CA1001" Action="Warning" />
    <Rule Id="CA1822" Action="None" /> <!-- отключить -->
  </Rules>
</RuleSet>

В .csproj:

<CodeAnalysisRuleSet>MyRules.ruleset</CodeAnalysisRuleSet>

⚠️ В .NET 5+ заменён на AnalysisLevel, AnalysisMode, .editorconfig.

Основа по протоколу

Базовый разбор HTTP и HTTPS находится в отдельной статье — HTTP как основа веб-интеграций.

В подборках

Статья входит в тематические подборки и блок "С чего начать?" на главной. Соседние шаги того же маршрута:

Справочники — Справочник по F#, Справочник по LINQ, Документация и инструменты Java (Microsoft), Справочник по ASP.NET, Справочник по Java, Справочник по C#.

Справочные таблицы​

Содержание справочника​

1. .csproj — файл проекта (MSBuild)​

1.1. Корневой элемент и базовые атрибуты​

1.2. <PropertyGroup> — свойства проекта​

Пример​

1.3. <ItemGroup> — элементы проекта​

1.3.1. <PackageReference>​

1.3.2. <ProjectReference>​

1.3.3. <Reference> — ссылка на сборку (устаревшее, но допустимо)​

1.3.4. <Compile>, <EmbeddedResource>, <None>, <Content>​

1.3.5. <FrameworkReference> — ссылка на метапакет фреймворка​

2. Directory.Build.props и Directory.Build.targets​

Пример Directory.Build.props​

3. global.json​

4. launchSettings.json — настройки запуска (отладка и CLI)​

4.1. Корневые секции​

iisSettings — конфигурация IIS Express (только для .Web SDK)​

profiles — набор сред запуска​

Пример профиля​

5. appsettings.json и окружения​

5.1. Формат и загрузка​

5.2. Поддерживаемые типы значений​

Пример​

5.3. Специальные секции (интерпретируются фреймворком)​

5.4. Переменные окружения как источник​

6. runtimeconfig.json — конфигурация среды выполнения​

6.1. Структура​

runtimeOptions → ключи​

configProperties — ключевые настройки CLR​

Пример runtimeconfig.template.json​

7. deps.json — зависимости приложения​

7.1. Структура​

7.2. Ключевые секции​

8. packages.lock.json — фиксация версий зависимостей​

8.1. Структура​

8.2. Поведение​

9. nuget.config — глобальные и локальные настройки NuGet​

9.1. Основные секции​

9.2. Ключевые параметры​

В <config>​

В <packageSources>​

В <packageSourceCredentials>​

Прочие секции​

10. packages.config — устаревшая модель управления пакетами​

10.1. Структура​

10.2. Недостатки (почему устарела)​

11. project.assets.json — промежуточный файл восстановления​

11.1. Структура (сокращённо)​

12. .nuspec — манифест NuGet-пакета​

12.1. Структура (минимальная)​

12.2. Элементы <metadata>​

12.3. <files> — содержимое пакета​

Пример структуры пакета​

13. Дополнительные параметры в .csproj для публикации и упаковки​

13.1. dotnet publish — параметры публикации​

13.2. dotnet pack — параметры упаковки​

14. app.config / web.config — конфигурация .NET Framework​

14.1. Корневая структура​

14.2. <configSections> — объявление секций​

Элемент <section>​

Встроенные обработчики секций​

<sectionGroup> — группировка секций​

14.3. Системные секции​

<startup>​

<runtime>​

<assemblyBinding>​

Прочие параметры <runtime>​

<System.web> — настройки ASP.NET​

<System.Data>​

15. Трансформации конфигурации (web.debug.config, web.release.config)​

15.1. Синтаксис трансформаций​

15.2. Автоматические трансформации (VS)​

16. Внешние файлы конфигурации​

16.1. configSource​

16.2. file (только для <appSettings>)​

17. machine.config​

18. Settings.settings и userSettings​

18.1. appSettings и userSettings​

18.2. userSettings в app.config​

Справочные таблицы

Содержание справочника

1. `.csproj` — файл проекта (MSBuild)

1.1. Корневой элемент и базовые атрибуты

1.2. `<PropertyGroup>` — свойства проекта

Пример

1.3. `<ItemGroup>` — элементы проекта

1.3.1. `<PackageReference>`

1.3.2. `<ProjectReference>`

1.3.3. `<Reference>` — ссылка на сборку (устаревшее, но допустимо)

1.3.4. `<Compile>`, `<EmbeddedResource>`, `<None>`, `<Content>`

1.3.5. `<FrameworkReference>` — ссылка на метапакет фреймворка

2. `Directory.Build.props` и `Directory.Build.targets`

Пример `Directory.Build.props`

3. `global.json`

4. `launchSettings.json` — настройки запуска (отладка и CLI)

4.1. Корневые секции

`iisSettings` — конфигурация IIS Express (только для `.Web` SDK)

`profiles` — набор сред запуска

Пример профиля

5. `appsettings.json` и окружения

5.1. Формат и загрузка

5.2. Поддерживаемые типы значений

Пример

5.3. Специальные секции (интерпретируются фреймворком)

5.4. Переменные окружения как источник

6. `runtimeconfig.json` — конфигурация среды выполнения

6.1. Структура

`runtimeOptions` → ключи

`configProperties` — ключевые настройки CLR

Пример `runtimeconfig.template.json`

7. `deps.json` — зависимости приложения

7.1. Структура

7.2. Ключевые секции

8. `packages.lock.json` — фиксация версий зависимостей

8.1. Структура

8.2. Поведение

9. `nuget.config` — глобальные и локальные настройки NuGet

9.1. Основные секции

9.2. Ключевые параметры

В `<config>`

В `<packageSources>`

В `<packageSourceCredentials>`

Прочие секции

10. `packages.config` — устаревшая модель управления пакетами

10.1. Структура

10.2. Недостатки (почему устарела)

11. `project.assets.json` — промежуточный файл восстановления

11.1. Структура (сокращённо)

12. `.nuspec` — манифест NuGet-пакета

12.1. Структура (минимальная)

12.2. Элементы `<metadata>`

12.3. `<files>` — содержимое пакета

Пример структуры пакета

13. Дополнительные параметры в `.csproj` для публикации и упаковки

13.1. `dotnet publish` — параметры публикации

13.2. `dotnet pack` — параметры упаковки

14. `app.config` / `web.config` — конфигурация .NET Framework

14.1. Корневая структура

14.2. `<configSections>` — объявление секций

Элемент `<section>`

Встроенные обработчики секций

`<sectionGroup>` — группировка секций

14.3. Системные секции

`<startup>`

`<runtime>`

`<assemblyBinding>`

Прочие параметры `<runtime>`

`<System.web>` — настройки ASP.NET

`<System.Data>`

15. Трансформации конфигурации (`web.debug.config`, `web.release.config`)

15.1. Синтаксис трансформаций

15.2. Автоматические трансформации (VS)

16. Внешние файлы конфигурации

16.1. `configSource`

16.2. `file` (только для `<appSettings>`)

17. `machine.config`

18. `Settings.settings` и `userSettings`

18.1. `appSettings` и `userSettings`

18.2. `userSettings` в `app.config`